Magnemo — the governed memory layer

Reference implementation of the Mnemosyne Protocol · SVTech Inc.

ATLAS runs the OS. Mnemosyne runs the memory.

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 five MCP tools. Promotion is not one of them.

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":{"MEMOS_VAULT":"/absolute/path/to/vault",
#            "MEMOS_AGENT":"my-agent",
#            "MEMOS_SCOPE":"ops,shared",
#            "MEMOS_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/        ← SVROS partition
  ops/      knowledge/ playbooks/ clients/ decisions/ style/  ← SVTOS 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: memory_search(max_chars=…) bounds every snippet; 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 (Register #29)

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 memory_write(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 (Register #14/#59/#68)

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 (Register #69)

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 (Register #13)

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), P-01 is G0001, 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 Register #67 gauntlet. Package magnemo; CLI python -m magnemo.cli (or magnemo); MCP server magnemo-mcp. The previous package name survives as a deprecation shim for this release only. Full notes: CHANGELOG.md.

New in v0.4 — the four-verb MCP server (Register #82)

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 (#81). 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 (MEMOS_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. The legacy five-tool magnemo.server remains for existing mounts.

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 (MEMOS_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.