Magnemo — the governed memory layer

Reference implementation of the Magnemo Protocol · SVTech Inc.

Viewer-agnostic by design. Memory is plain markdown on disk — yours, forever. Read it in the Magnemo review CLI today, the Magnemo interface tomorrow, or any editor you like (VS Code, Obsidian, vim). Magnemo depends on none of them; they are windows, not foundations. It can also mount an EXISTING markdown vault and govern it in place — and, via adapters, sit as the governance gateway in front of other memory stacks (Mem0/Zep/RAG): their retrieval, our customs checkpoint.

Agent memory is the #1 bottleneck holding production agents back. Every framework optimizes retrieval; none ship governance. Magnemo is memory with a constitution: every fact carries provenance, every agent write passes a human review queue before it becomes truth, and every decision feeds a Trust Ledger that will one day compute how much runs without you.

Zero dependencies. Pure Python 3.10+ stdlib. Nothing to install, nothing to trust but this code.

The asymmetry that IS the protocol

Agents get four MCP verbs. Promotion is not one of them.

The one-paste install

No terminal needed — your agent does the install. Paste this ONE message to your agent (Claude Code, Cursor, or anything that speaks MCP), in the project where you want memory:

Set up Magnemo (governed memory) for me in this project:
1. Install it: pip install magnemo  (use pip3 if needed)
2. Initialize the vault: magnemo init
3. Register the MCP server: run magnemo mount — it writes this project's MCP
   config itself. (Or add "magnemo-mcp" with env MAGNEMO_VAULT pointing at the
   vault; nothing else is required.)
4. Verify: run magnemo doctor and confirm everything passes.
5. Then run magnemo bootpack --stdout and read me THE CHARTER section aloud — I
   want to hear who you are now.
If anything fails, show me the doctor output and fix what you can yourself.

Plant the seed — one paste, and your agent grows a memory.

Fresh vault? THE CHARTER section will say it isn't promoted yet — that is the governance speaking: Magnemo never fabricates canon. Stage a charter, review it, promote it, and every boot thereafter serves it back verbatim. (magnemo not found after install? pip's script folder isn't on PATH — python3 -m magnemo always works.)

Open beta — read KNOWN_LIMITS.md before trusting it with anything you can't lose. Honest caveats, no fine print.

Quick start (open beta)

Five minutes from install to a governed, booted agent. Python 3.10+, zero dependencies.

# 1 · install
pip install magnemo

# 2 · create a vault — plain markdown you own; read it in any editor
magnemo init ./vault

# 3 · mount it into your agent (Claude Code / any MCP client) — .mcp.json:
#   {"mcpServers":{"magnemo":{
#     "command":"magnemo-mcp",
#     "env":{"MAGNEMO_VAULT":"/absolute/path/to/vault",
#            "MAGNEMO_AGENT":"my-agent",
#            "MAGNEMO_SCOPE":"ops,shared",
#            "MAGNEMO_PARTITIONS":"ops,shared"}}}}
#   (full tool reference and postures: docs/MCP.md)

# 4 · render the first boot pack — what a fresh session wakes up knowing
magnemo bootpack --stdout

# 5 · checkup — python, vault, config, ledger, and your .mcp.json mount
magnemo doctor --mount .mcp.json

Then the loop begins: agents write to staging, you review.

magnemo review          # interactive queue: promote / reject
magnemo ledger          # every decision, forever

Beta honesty: read KNOWN_LIMITS.md before you rely on it.

The vault

vault/
  dev/      knowledge/ playbooks/ decisions/ debt/        ← example: a dev team's partition
  ops/      knowledge/ playbooks/ clients/ decisions/ style/  ← example: an ops team's partition
  shared/   tickets/ changelog/                            ← interop bus (gated)
  _staging/   agent writes await review here
  _index/     machine-managed
  _ledger/    trust_ledger.jsonl — append-only, never forgets

Every note is markdown with provenance frontmatter (author, written, source, status, reviewed_by, supersedes, strength). Provenance is the file format.

New in v0.2 — the Telos sockets (consequence, taint, token budgets)

• Retrieval receipts: every search returns a rid and logs which notes it served (_ledger/retrievals.jsonl) plus the payload size in chars.
• Outcome recording (magnemo outcome <rid> approved|denied --by NAME): links an action's result back to the memories that informed it. Each note accrues yield_w / yield_l — an earned track record — and ranking multiplies by proven yield. Memory that pays ranks up; memory that misleads sinks.
• Taint propagation: writes from untrusted sources carry taint: in frontmatter; taint is hereditary through supersession and only a human clears it (magnemo cleartaint). Injection cannot launder itself through derivation, and tainted notes are rank-penalized and excludable.
• Char budgets: retrieve(budget=…) bounds every payload; payload size is measured and logged on every retrieval — the instrumentation for the token-efficiency benchmark is on by default from day one.

New in v0.3 — KAIROS v1: salience-sorted review — so a human reads what mattered first

The founder's attention is the scarcest resource in the loop. Every staged note now gets a deterministic salience score at stage time — no model calls, no embeddings — stored in frontmatter (salience + salience_components) so the ranking is auditable from the file alone:

• consequence — the writer's declared impact class (security > money > correctness > process > info, via stage(impact=…))
• novelty — trigram/tag overlap vs existing canon in the same partition; duplicates of settled truth sink, new claims rise
• operator signal — cli flag <note-id> --by NAME; by config invariant a founder-flagged note outranks any unflagged note
• source weight — audit/postmortem findings outrank routine runs

cli review presents the queue salience-descending with score + components, capped per pass (--batch N, default from config), and reports queue depth up front; the MCP server reports queue depth at session start. cli rescore backfills legacy notes. Weights live in the vault's documented config file — see docs/CONFIG.md.

New in v0.3 — the Boot Pack: served on every wake — the agent never starts from nothing

python -m magnemo.cli bootpack [--scope dev|ops|shared] [--class worker|partner]

One command renders BOOT_PACK.md — the orientation a fresh session boots from. Section order is doctrine, for both classes: (1) the Charter, verbatim, always first (an explicit placeholder if not yet promoted — the Charter is never fabricated); (2) canon digest — every canonical note's title, one-line summary, and stable path; (3) open threads, staged count, and the top-5 staged notes by KAIROS salience; (4) trust-ledger tail.

--class partner additionally serves a RELATIONSHIP LAYER sourced from a codex file (voice/lore/relationship — what makes a spawn a partner, not a clone). Worker boots omit it and stay lean. No codex file, no section: a partner boot degrades gracefully. The codex source is a pluggable seam — see docs/CONFIG.md.

The pack is deterministic: a pure function of vault state — identical state yields identical bytes, per class (tested).

New in v0.3 — Boundary Telemetry — every handoff records where it stopped and why

python -m magnemo.cli handoff --usage 91 --trigger planned --cut "deferred X" --by NAME
python -m magnemo.cli handoff --report     # every boundary ever, as a table

Sessions end at boundaries — the context wall, a planned stop, a compaction — and untracked boundaries are where continuity silently dies. Each handoff appends a structured telemetry entry to _ledger/handoffs.jsonl (append-only: usage %, trigger, what was cut, actor) and stages a provenance-complete handoff note for review like any other memory candidate. Known historical boundaries can be recorded honestly with --when: the entry keeps both ts (when the boundary happened) and recorded_at (when it was written down).

The ~90% soft-threshold doctrine. Don't ride to the wall. At ~90% context usage, write the handoff and stand down — a handoff written at the wall is written in a panic with no room to verify the catch. The first recorded datum is the scar that set the rule: Aug 13 2026, 98% usage, trigger=wall (operator-confirmed). Everything after ~90% should be boundary work, not new work; the telemetry exists so the doctrine gets numbers instead of vibes.

New in v0.3 — Foresight counters — what memory costs, measured from day one

python -m magnemo.cli costs      # per-kind payload costs + the stated baseline

Every memory payload served — a retrieval result set, a boot pack — logs an append-only event to _ledger/costs.jsonl: bytes plus a rough token estimate (bytes/4, documented, swappable for a real tokenizer later). cli costs summarizes per kind and states the measured baseline — the number every future payload optimization (renditions, pointers, adaptive resolution) gets judged against. First datum: a full worker boot of this repo's vault costs ~465 tokens. A failed counter never fails the retrieval it was measuring.

v0.5.0 "First Trust" — the trust ledger is math

Every actor holds a computed autonomy level per action class (read · stage · merge-code · promote-canon · publish), derived only from append-only ledger events: score = Σ weight × 0.5^(age/half-life), thresholds → L0 frozen … L3 autonomous; L4 keyholder is held by humans, never computed. Grants are ledger records (magnemo grant) — a standing order becomes a grant id, so permission is data with a receipt — and the Gate Map (magnemo gates) plus your own scorecard ride every boot pack. promote-canon and publish stay human-only forever. Read docs/TRUST.md, docs/GRANTS.md, docs/GATES.md.

v0.4.0 "First Name" — the product is Magnemo

Ratified 2026-08-20 after the naming gauntlet. Package magnemo; CLI python -m magnemo.cli (or magnemo); MCP server magnemo-mcp. The previous package name is retired. Full notes: CHANGELOG.md.

New in v0.4 — the four-verb MCP server — the whole agent surface, nothing more

python -m magnemo.mcp (or magnemo-mcp) exposes exactly four tools, each bound to existing code — retrieve · stage · bootpack · handoff. Promotion is not a tool — promotion is a human act, always. Zero deps, stdio, stdlib only.

retrieve ─▶ scope gate ─▶ walled BM25 ─▶ budget/rendition (snippet→pointer) ─▶ cost event
stage    ─▶ provenance check ─▶ dup flag ─▶ KAIROS salience ─▶ _staging/ ─▶ cost event
bootpack ─▶ Charter ─▶ digest ─▶ KAIROS-ranked queue ─▶ LAST HANDOFF ─▶ ledger tail
handoff  ─▶ handoffs.jsonl ─▶ staged note ─▶ next bootpack inherits it

Tested invariants: staging is the only write path · provenance mandatory · scope walls (MAGNEMO_SCOPE) · budgets cap payloads with logged truncation · free tier · least privilege. Three postures (native / mount-and-govern / gateway), full tool reference and cascade diagrams: docs/MCP.md. magnemo-mcp is the only server.

The chest — machines die, the memory doesn't

magnemo chest add git <url-you-own> --label laptop     # Copy B
magnemo chest add path /Volumes/Drawer/vault --label drawer   # Copy C
magnemo chest push                                     # swept for secrets first, every time
magnemo mount --from <url-or-dir> ./vault              # restore onto a new machine

Magnemo conducts copies to places you own; it never holds them. Full contract: docs/CHEST.md.

Guarantees (Phase 1 — Governed Recall)

• Agent writes NEVER reach canonical stores directly — staging only, always.
• Search returns canonical (human-reviewed) notes only. Staged claims are invisible.
• Partition walls enforced per agent (MAGNEMO_PARTITIONS); cross-partition = DENIED.
• Supersession is explicit: old notes archive with a forward link. Nothing deletes.
• Rejections are kept and recorded — rejections teach.
• Every promote/reject lands in the append-only Trust Ledger with actor + reason.

Designed-in evolution (do not remove these seams)

• strength field + score hook in search.py → Phase 2 reinforcement/decay.
• TrustLedger.pass_rate() → the L0→L3 graduation math.
• Index.search() signature is stable → embedding retrieval swaps in behind it.
• Consolidation/reflection jobs write through Governance.agent_write like any agent — the sleep cycle inherits the review queue for free.

Tests

python -m unittest discover -s tests -v     # incl. full MCP round-trips (legacy + four-verb)
# or: pip install -e ".[test]" && pytest

— Silver Valley Technologies Inc. · Phase 1 of 3 · The memory that learns is the memory that is governed.