birkin-mnemosyne

Landing page

birkin-mnemosyne is local Markdown memory for personal agents: multilingual BM25 retrieval, usage-driven decay and zone priorities, plus provider-portable curation whose file operations are bounded by a deterministic executor. The core has zero runtime dependencies and needs no model or API key to store or search notes. Notes stay readable, greppable and diffable; an optional MCP server connects the vault to agent clients, and an opt-in semantic mode adds meaning-based retrieval.

0.7.1: nested folders and terminal reads

Visible Markdown notes are discovered recursively, including nested imports and folders with spaces or Unicode names. Hidden files, cache folders and links remain excluded. Zones use the complete relative parent; archive moves keep the original subpath, and checked undo restores exact paths and bytes. Duplicate filename stems select the newest file with a warning and a deterministic path tie-break.

The published package also includes read-only search, list and show, repeatable CLI label filters, --version, and journaled undo. Terminal and MCP commands share the documented vault defaults. These changes do not add a model requirement or turn labels into ranking terms.

Install

Requires Python >= 3.10. Install from PyPI:

pip install "birkin-mnemosyne==0.7.1"

From a checkout, the existing development and benchmark commands are:

pip install -e .                 # standard-library-only core
pip install -e ".[dev]"          # pytest, ruff
pip install -e ".[bench]"        # fastembed, numpy: embedding baselines only
pip install -e ".[mcp]"          # official MCP SDK and server
pip install -e ".[semantic]"     # optional meaning-based retrieval

The extras are optional. [bench] reproduces embedding baselines; it does not enable semantic retrieval. See below for explicit semantic preparation.

Quick start for agent users

The commands below ship in 0.7.1. Install the published MCP extra to connect your agent; a source checkout is not required. Give your coding agent a memory, then check from a terminal what it stored:

pip install "birkin-mnemosyne[mcp]==0.7.1"
claude mcp add --scope user mnemosyne -- mnemosyne-mcp --vault ~/mnemosyne

# Start a new agent session and ask it to remember a note titled
# "Release checklist" before inspecting that note below.
mnemosyne --version
mnemosyne --vault ~/mnemosyne search "release checklist"
mnemosyne --vault ~/mnemosyne list
mnemosyne --vault ~/mnemosyne show release-checklist

Other clients (Claude Desktop, Cursor, Codex CLI, IDEs) are in the MCP server section. search, list and show print JSON with the same fields as the MCP tools memory_search, memory_list and memory_get_note. They are read-only: they never count as a use, so they do not change usage ranking. show exits 1 when the note does not exist; a vault directory that does not exist exits 2 and is not created.

For label-aware recall, add --label namespace:value to search or list. Repeat --label to require every label (AND). Filtering happens before ranking or pagination; list reports label_counts for all matching notes, not just the returned page.

User-provided Markdown extensions are case-insensitive (.md, .MD, .Md); imports also recognize .txt and .json without regard to extension case. Original filenames and source bytes are retained. Hidden dot files remain outside ordinary recall, including files inside a visible zone.

Every mnemosyne command finds its vault the same way: --vault (before or after the command name), else $MNEMOSYNE_VAULT, else ~/.birkin-mnemosyne/vault, the same default as mnemosyne-mcp. Only init falls back to the current directory instead. ~ is expanded even when the shell leaves it quoted. Set MNEMOSYNE_VAULT once and the terminal and the MCP server use the same vault without repeating --vault.

First run

From v0.7.0, mnemosyne init previews first-run organization without changing any files. It works offline with the standard-library-only core and needs no model or API key:

mnemosyne init --vault my_vault
mnemosyne init --vault my_vault --apply

# Optional external Markdown import: keep the option when applying its plan.
mnemosyne init --vault my_vault --import ./markdown_export
mnemosyne init --vault my_vault --import ./markdown_export --apply

Without --vault, init uses $MNEMOSYNE_VAULT when it is set, otherwise the current directory; the JSON output's vault key names the absolute directory it acted on. The existing mnemosyne-index --vault my_vault init command uses the same dispatcher. The JSON output lists the plan and reports notes, topics, INDEX token estimates, warnings, and verification status. A preview says planned; an applied run independently verifies the resident INDEX and checks drift. This does not claim that every note fits into one startup bundle.

Initialization reports duplicate and possible overlap/conflict candidates, but never chooses a winner, merges, archives, or deletes notes. It completes missing title, type, and tags through the existing byte-exact review journal, preserving existing fields and body bytes; ambiguous headers and bytes bound by split receipts are retained with warnings. If the output has an undo_transaction, run mnemosyne --vault my_vault undo --transaction <undo_transaction> (or call Consolidation(vault).undo(transaction_id) or the memory_review_undo tool) to restore the original source images. The same command undoes an applied handoff fold or review answer. Added imports, topic catalogues, and INDEX routes remain after undo.

Topic documents are deterministic source-link catalogues, grouped by tag, source directory, or note type. Every source stays routed alongside its catalogue. Existing aliases are retained; large INDEX views use the existing complete topic map or warn about the UTF-8-bytes/4 budget without dropping routes. --max-tokens changes that warning budget. Unchanged reruns reuse outputs and create no additional journal. Changed destinations are refused rather than overwritten; an unfinished journal requires checked recovery.

30-second usage

from birkin_mnemosyne import VaultMemory

mem = VaultMemory({"vault_path": "my_vault"})
mem.write_note(
    "Ingress DNS",
    "nginx ingress resolves service DNS; allow HTTPS through the firewall.",
    zone="devops",
)
for hit in mem.dex.search("ingress dns"):
    print(hit)
# Reinforce the note your agent actually used, not every search candidate.
mem.dex.record_access("ingress-dns")

For an existing vault, use Mnemosyne("my_vault"), call refresh(), then search(query). Unicode normalization, accent folding, Latin prefix stems, and Hangul/Han/kana bigrams support multilingual lexical matching. File changes refresh the index: notes written through the library are searchable at once, and search() looks for edits made outside it (for example in Obsidian) at most once every 2 seconds (refresh() looks immediately). The compressed cache is rebuildable, while usage history persists separately. Usage decay and zone activity adjust ranking.

Widen a query at search time (optional)

Matching is lexical, so a question worded differently from the note can miss it. A host model can widen its own query when it searches. Nothing is stored, the index is untouched, and a search without expansions ranks as before:

mem.search(
    "why can't the pods find each other by name",
    expansions={
        "synonyms": ["service discovery", "name resolution"],  # weight 0.75
        "keywords": ["Namensauflösung", "Dienst"],   # 0.75: your other language(s)
        "related": ["ingress", "firewall"],                    # 0.4
        "note_line": "The ingress resolves service DNS names.",  # 0.4
    },
)

The query's own words weigh 1.0, and a note that contains all of them stays first. Over MCP the same four fields are parameters of memory_search. On the benchmark's test split at 10,000 notes, expansions written by two models that saw only the question moved paraphrase MRR from 0.204 to 0.981 and 0.952. Questions and expansions are both model-written, so read that as an upper bound: see Search-time query expansion.

Always-loaded memory INDEX (opt-in)

Keep a complete when to read -> which document map available from startup context, then open the details only when needed. The INDEX is available from v0.6.0. Task-bound reads and the two-level topic map described below are available from v0.7.0.

from birkin_mnemosyne import MemoryIndex

# Register an existing note, such as the one created in the example above.
index = MemoryIndex("my_vault")
index.register("Ingress DNS", "devops/ingress-dns.md")
print(index.render())                 # complete always-loaded map
opened = index.open("Ingress DNS")     # exact trigger; complete document

The .mnemosyne-memory-index/ directory is the opt-in marker. A vault without that directory keeps its legacy behavior. Managed startup/digest/host surfaces retain the complete resident map. Over-budget reads warn but never remove a route or topic. There is no INDEX removal, expiry, or automatic cleanup operation. Hosts should retain required=True or --require-memory-index across restarts and re-read the complete INDEX after context compaction. Exact triggers are reliable; lexical matching and BM25 fallback are not semantic guarantees.

From v0.7.0, task-bound reads let a host call StartupReader("my_vault").read([], task="Check Ingress DNS") before acting. They return every lexically matched document in full, without the optional lookup's top-k cutoff or search fallback. Pass the same task to memory_startup_read / memory_startup_verify over MCP; indexed Hermes prefetch uses this path automatically. See the usage guide below for the lexical limits and complete-read failure behavior.

From v0.7.0, the renderer also chooses between a flat INDEX and a smaller two-level topic map. Topics follow complete parent-directory paths; every route remains in its complete topic view. index.read(topic="dir:devops") and MCP memory_index_read(topic="dir:devops") expand that topic. Task-bound startup automatically includes matched topic views and their documents from one routing snapshot. Same-document aliases share a label only when shorter; no condition or target is removed. The selected layout uses the declared bytes/4 estimate, not a model-specific tokenizer.

Use .render() or view.context for compact resident text. The default read().entries still returns all original mappings; its complete structured result is not claimed to have the same cost as the resident text.

mnemosyne-index --vault my_vault check
mnemosyne-index --vault my_vault split handoff.md          # read-only preview
mnemosyne-index --vault my_vault split handoff.md --apply  # explicit migration

The splitter preserves every source byte and prints a complete per-line coverage table. The checker reports orphans, dangling routes and lost coverage. MCP exposes memory_index_register, memory_index_read, memory_open_trigger, memory_index_check, and memory_index_split. Keep .mnemosyne-memory-index/ and .mnemosyne-reviews/, including captured source revisions, when backing up a vault.

The latest public replay on 2026-10-11, main 876ad40, reduced the fictional large-note whole startup payload from 45,128 to 1,297 o200k_base tokens. The resi