Mnemosyne Documentation

August 4, 2026 ยท View on GitHub

Local-first, zero-cloud memory for AI agents. SQLite-backed. Sub-millisecond. Fully private.

Guides

DocumentDescription
Getting StartedInstallation, quickstart, storing your first memory
ArchitectureBEAM tiers, SQLite backend, hybrid search, knowledge graph
API ReferencePython API: remember, recall, sleep, triples, stats
CLI ReferenceEvery command, including the ones --help omits
IntegrationsPlatform guides: Cursor, Claude Code, Codex, OpenWebUI, Windsurf, OpenClaw, Hermes
OpenWebUI Deep IntegrationAuto-save every chat, memory browser dashboard, cross-session recall
Integration Template~100-line pattern for adding any new platform
Hermes IntegrationUsing Mnemosyne as a Hermes memory backend
LLM Installation GuideInstallation instructions for AI agents/LLMs
ConfigurationEnvironment variables, data directory, vector compression
Mnemosyne SyncBidirectional sync, encryption, deployment, tutorial
Security & PrivacyThreat model, encryption internals, BYOK comparison
BenchmarkingMaintainer guide: per-tool A/B benchmark env vars, diagnostics, pure-recall mode, test sequence template
Benchmark Results AnalysisOutput-file schemas + analysis recipes (per-ability scores, paired bootstrap CIs, voice attribution). AI-assistant-friendly reference
ChangelogPointer to the root CHANGELOG.md, plus release-state notes

Generated references

Written from the code by scripts/generate-docs.py and verified in CI by scripts/verify-docs.py. Do not hand-edit these two files; edit the code or the generator instead.

DocumentDescription
MCP Tool SchemaAll declared tools with parameters, split by whether they are reachable over MCP or only through the Hermes plugin
Configuration ReferenceEvery config key with its environment variable, real default, and restart requirement, plus the environment-only variables

Subsystems

DocumentDescription
Memory HygieneNoise scoring, the audit and clean workflow, secret detection, and how to prevent noise being stored
Configuration ProfilesThe eight built-in profiles, what distinguishes them, validation rules, and the vec_type restart trap
L3 Persona TierDurable behavioural facts promoted into a store; prompt injection reads an opt-in persona.md file. Includes an explicit list of what is not yet wired
SHMRSelf-harmonizing memory reasoning. Library only; nothing calls it yet

Reference and analysis

DocumentDescription
Sync Protocol ReferenceWire protocol, endpoints, CLI reference, deployment recipes
Comparison: Mnemosyne vs HindsightArchitecture, retrieval, and integration comparison against Hindsight self-hosted
BEAM Benchmark ResultsThe v3.0.0 BEAM run, methodology, and judge caveats. Source for the README figures
Compression PluginAAAK compression, the plugin interface, and the legacy caveman fallback
Hermes LLM IntegrationRouting consolidation and extraction through a host-provided LLM backend
Audit WorkflowHow documentation audits are run, and the report format

Design Proposals (RFCs)

Forward-looking design documents. An RFC describes intended behaviour, not shipped behaviour, so check its Status line before treating it as a description of the code.

DocumentDescription
RFC 0001: Tags and Scope UnificationFirst-class tags on memories, scope as a reserved tag namespace, tag filtering in recall()
RFC 0002: Modality ProvidersThe ModalityBackend seam for vision, video, and audio understanding, and the Atlas Cloud configuration recipe
RFC 0003: Media Assets and the Moment IndexReference-hash asset registry plus semantically tagged spans, so recall can locate a moment inside a video or document
RFC 0004: The Archive BoundaryContentResolver and the contract that keeps heavy files outside the engine. The brain stores text and spans; an archive stores bytes
R&D: Noise RemediationExploratory report on the pre-storage filter, hygiene audit, and the gaps between them
Roadmap: Layered Agent MemoryProposed L0 through L4 layering. Extends BEAM rather than replacing it. Not shipped