A complete INDEX at startup
The opt-in INDEX keeps every “when to read → which document” route available. Large maps can use complete topic views. Going over the soft budget warns; it does not silently remove a route.
Read the INDEX guide ↗LOCAL MARKDOWN MEMORY / v0.7.0
Memory that survives the session.
Your agent starts over. Your notes shouldn't. Keep memory as local Markdown, load the map at startup, and open the details when they're needed.
pip install birkin-mnemosyne
your vault/Markdown on disk
INDEX
Always loaded. A complete map of when to read which document.
project notes
The complete details for the task, not the whole vault.
session handoff
Work, decisions, open items and the next step.
- 01 Plain files you can read and diff
- 02 No model or API key for the core
- 03 Zero core runtime dependencies
01 / KEEP THE MAP. OPEN THE NOTE.
Carry context, not the whole vault.
A new session needs a way back to earlier work. Loading every note upfront spends context on details that may have nothing to do with the task.
Details when the task needs them
Exact triggers open complete documents. Task-bound startup reads return every lexically matched document in full. Ordinary recall uses multilingual BM25, usage-driven decay and zone priorities. Lexical matching is not a semantic guarantee.
A handoff for the next session
Immutable project/task checkpoints keep work, decisions, open items, open questions, the next step and links. Scoped startup includes the complete latest capture. MCP clients manage capture and resume calls; Hermes has opt-in lifecycle callbacks.
Labels and a preview-first start
Readable namespace:value labels filter eligible notes without becoming ranking terms. mnemosyne init previews organization and imports before an explicit apply. It does not automatically merge, archive or delete your notes.
02 / MEASURED, WITH THE SMALL PRINT
Less startup context.
Not a universal saving.
These are documented experiments, not a promise about your vault or your agent's answers.
CURRENT PUBLIC REPLAY · 2026-10-11
45,128 → 1,297
Whole startup payload, o200k_base tokens.
Fictional large-note corpus; main 876ad40.
The resident INDEX alone is 144 tokens; all 30 routes and 155,749 source bytes remain intact. Separate frozen Sol and Claude answer sets both stay at 12/12, not an accuracy gain.
Read the current measurement ↗The cost of reading small notes
Small-note combined task costs are 199–221 tokens for Sol (12/12 cost more than the full original) and 229–432 for Claude (0/12 cost more). These are separate measurements, not task accuracy on the large corpus.
Historical v0.6.0 measurement
The earlier fictional large-note result was 45,128 → 1,781 o200k_base whole-startup tokens. There was no accuracy gain. On its separate small-note fixtures, all 12 Sol tasks and 7 of 12 Claude tasks cost more than reading the full original.
Handoffs and labels add context
The Windows-shaped handoff fixture grew from 163 to 919 estimated tokens (+756). The separate label fixture grew from 1,052 to 1,076 (+24). These use ceil(UTF-8 bytes / 4), not a model tokenizer. They are different fixtures: never add them into a universal total.
Optional retrieval has trade-offs
Semantic mode is opt-in and not the recommended default: some test slices lose to the core. The Linux replay measured a 0.38 → 80.24 MB install, excluding 669.1 MB of raw and compact model files. Its largest indexing-memory addition was 163 MB, above the 150 MB budget. These are not service-level guarantees.
Host-written query expansion costs about 115–200 output tokens per widened search and about twice the ranking time. The default core does not improve Korean recall; synthetic results do not establish superiority, answer accuracy or universal multilingual coverage.
Read all documented limits ↗03 / USE THE AGENT YOU ALREADY HAVE
One vault. Different entry points.
Keep the storage local. Choose a documented adapter or expose the Python API to your own agent loop.
MCP clients
The optional stdio server connects Claude Code, Claude Desktop, Codex CLI, Cursor and other MCP clients. Setup guidance is not a claim that every IDE was launched and tested.
Choose your client configuration ↗Hermes
The external memory provider uses local Markdown with a separate vault per Hermes profile. Scoped handoff capture at session end and before compression is opt-in.
Set up the Hermes provider ↗omo
Use the MCP tools for recall and complete startup reads. Capture a checkpoint explicitly, then resume with the same project/task keys. This lifecycle is caller-managed.
Read the checkpoint contract ↗04 / START WITH PLAIN FILES
Install. Preview. Then apply.
Python 3.10 or newer. The core stores and searches notes without a model, API key or runtime dependency.
Install the core
pip install birkin-mnemosyne
mnemosyne init --vault my_vault
mnemosyne init --vault my_vault --applyThe first init command is a read-only preview. Inspect the plan before applying. Without --vault, init uses the current directory.
Connect an MCP client
uvx --from "birkin-mnemosyne[mcp]" \
mnemosyne-mcp --vault ~/mnemosyneThe MCP extra downloads the official SDK on first launch. Configure this stdio command in your client. Point clients at the same vault to share memory.
Read the full setup instructions ↗05 / WORK THAT GOES BACK UPSTREAM
From local experiments
to shared improvements.
Gwanghoon started this work to address gaps in Korean agent memory. The README records contributions derived from that work, with their status as of 2026-10-11 KST.
- oh-my-openagent
CJK-aware recall, Han-character matching and optional query expansion.
#9209 · merged / #9341 · merged / #9342 · merged - Hermes Agent
External memory provider in the community catalog.
#131586 · merged - HOL Guard / OpenClaw
Opt-in MCP registration and Python stdio bundle guidance. Open proposals are not shipped improvements; approval does not mean merged.
HOL Guard #3441 · approved, still open
OpenClaw #163588 · open - Awesome Agent Memory
The maintainer added the listing by hand; the original PR is closed.
#122 · closed, landed by hand