Metadata-Version: 2.4
Name: magnemo
Version: 0.6.0
Summary: Magnemo — governed memory for AI agents. Agents stage; humans promote. Agents stage; humans promote. Four-verb MCP server included.
Author: SVTech Inc. · Silver Valley Technologies
License: Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: test
Requires-Dist: pytest<9,>=8; extra == "test"

# 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.

| Actor  | Door                | Can do |
|--------|---------------------|--------|
| Agents | MCP server (stdio)  | search canonical memory · read notes · **write → staging only** · list queue · query provenance |
| Human  | CLI + git (any editor)| review the queue · **promote / reject** · edit anything · own everything |

## Quick start (open beta)
Five minutes from install to a governed, booted agent. Python 3.10+, zero dependencies.

```bash
# 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.
```bash
magnemo review          # interactive queue: promote / reject
magnemo ledger          # every decision, forever
```
Beta honesty: read [KNOWN_LIMITS.md](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](docs/CONFIG.md).

## New in v0.3 — the Boot Pack: served on every wake (Register #14/#59/#68)
```bash
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](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)
```bash
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)
```bash
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](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](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
```bash
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.
