Verified Memory

verified-memory-mcp

Why

AI agents are starting to pay invoices and buy things. An agent pays wherever its memory says to pay. If someone swaps a remembered account number, the agent pays the attacker. This is vendor-payment fraud moving from fooling clerks to fooling AI.

Verified Memory serves only facts signed by a key you pin, and refuses anything changed after signing. An AI attacker red-teamed it with 12 tampering attacks (swapped files, broken signatures, fake clocks, a 5,000-file flood, the folder replaced while running). None got tampered data served (full log). Latest release: Verified Memory 0.4.1.

Free, MIT-licensed local stdio MCP server exposing verified_memory_search and verified_memory_get using the official MCP TypeScript SDK (@modelcontextprotocol/sdk 1.32.1). Published on npm as @python1/verified-memory-mcp and in the MCP Registry as io.github.python1/verified-memory.

Runtime is read-only and offline: no network transport, sockets, telemetry, embeddings, accounts, filesystem writes, subprocesses or shell execution. It reads one configured pack at startup and serves an isolated in-memory snapshot. On every request it checks, from file metadata only, that the pack folder is still the one it verified, and stops serving if it is not (no watchers, nothing re-read). Stdout is exclusively MCP protocol output; startup errors go to stderr and exit nonzero. Only these two tools are exposed; no resources, prompts, filesystem or command tools.

Run with npx

The npm package contains only dist/, the pack builder, this README and LICENSE. It ships no pack, so --pack is required:

npx -y @python1/verified-memory-mcp --pack /absolute/path/to/pack

Claude Code: claude mcp add verified-memory -- npx -y @python1/verified-memory-mcp --pack /absolute/path/to/pack. Running through npx does not apply Node's permission mode, because npx starts its own Node process. For the read-only filesystem allowlist described below, install the package and run its dist/index.js with node directly.

Build your own pack

A pack is a directory with exactly four files: records.jsonl, MEMORY.md, README.md and SHA256SUMS, plus an optional PACK.json (creation and expiry dates) and an optional signature, SHA256SUMS.sig (see Signed and dated packs). The easiest way to make one is the bundled offline builder. It reads your messages and the records you want to remember, finds every quote in its message, computes offsets and hashes, writes the pack, and then loads it with the server's own verifier. If any quote is not verbatim in its message, it writes nothing.

From a ChatGPT or Claude export, in your browser

Pack maker (beta): [https://python1.github.io/data-lore-hive/](https://python1.github.io/data-lore-hive/). Load your data export, search your chats, select the exact sentences to remember, and download a ready pack. It runs entirely in the browser (no server, and its Content-Security-Policy forbids network requests), uses the same building code as the command-line builder, and checks the pack with the server's own verifier before offering the download. It does not sign packs or add dates (use sign-pack, below), but its *Check a signed pack* panel runs the same verifier on a signed pack and the public keys you paste. Its source is in web/; to run it from a checkout instead, run npm install && npm run build there and open web/dist/index.html. See web/README.md.

Quick start

1. Put your source messages in messages.jsonl, one JSON object per line:

   {"id": 3, "date": "2026-03-02T08:20:00Z", "speaker": "Rowan", "text": "Quick thing first: the shed code changed. Also, the café on the corner sells seedlings on Saturdays."}

1. Put what you want remembered in records.jsonl, one record per line, each citing exact quotes from those messages:

   {"record_id": "M-garden-3", "role": "user", "topic": "Seedlings", "category": "places", "quotes": [{"message_id": 3, "quote": "the café on the corner sells seedlings on Saturdays."}]}

Unknown fields are refused, so typos fail loudly.

1. Build into a directory that does not exist yet, then point the server at it:

   npx -y -p @python1/verified-memory-mcp verified-memory-build-pack \

--messages messages.jsonl --records records.jsonl \ --out /absolute/path/to/my-pack --title "My memory" --description "Optional text for the pack README" npx -y @python1/verified-memory-mcp --pack /absolute/path/to/my-pack

From a repository checkout, run node tools/build-pack.mjs ... after npm run build. The building rules (verbatim quotes, code-point offsets, hashes, file layout) live in tools/pack-core.mjs, which has no imports so a browser can run the same code. The builder makes no network calls. It never overwrites: it stages in a hidden sibling directory and renames it into place only after verification passes.

examples/input/ holds invented sample input (a fictional community garden, not real people), and examples/pack/ is the pack built from it; the test suite rebuilds it byte for byte. Neither ships in the npm package.

records.jsonl format (what the server verifies)

One JSON object per line, UTF-8, at most 10,000 records, unique record_ids. Every field below is required unless marked optional:

Each citation in evidence:

Example (one line in the file; wrapped here for reading):

{"record_id":"M-garden-3","role":"user","speaker":"Rowan","category":"places","topic":"Seedlings",

"statement":"the café on the corner sells seedlings on Saturdays.", "date_first_utc":"2026-03-02T08:20:00Z","date_last_utc":"2026-03-02T08:20:00Z", "evidence":[{"message_id":3,"date_utc":"2026-03-02T08:20:00Z", "quote":"the café on the corner sells seedlings on Saturdays.","start":48,"end":100, "message_sha256":"e3aebbd25f7b809dd5b0b8d55b9ad7df6566464dc2a5033d02e3c5aa7ed8eeb2"}]}

Quotes are checked against their source messages when the pack is built, and after that the signature protects them. The builder (or agent-memory/) refuses any quote that is not verbatim in its message and computes message_sha256 from that message. The server never sees your original messages, so at load and at serve time it checks only citation structure, offsets' arithmetic and the hash's format; it does not re-check quotes against message_sha256. Once the pack is sealed, SHA256SUMS (and, for a signed pack, SHA256SUMS.sig) is what protects those quotes from later changes. A pack with no records is refused at load (since 0.4.1).

MEMORY.md and the pack README.md

The server requires both to exist, be valid UTF-8 and match SHA256SUMS. It does not parse them or return them from either tool; they are for people and agents reading the pack directly. By convention, and as the builder writes them:

• MEMORY.md: a # Title heading, then for each record its ID and speaker, its statement, and each quote with its message ID and date, marked as historical data.
• README.md: what the pack is and where it came from (SHA-256 of the input files, record count), plus the notice that quotes are data, not instructions, and that checksums prove integrity, not truth or approval.

SHA256SUMS format

Exactly one line per other file (three, or four with PACK.json), each <64 lowercase hex> + two spaces + file name; no entry for SHA256SUMS or SHA256SUMS.sig; at most 4 KiB:

f3ed88bca6a7a451a892f49bd6d2970f5671b8c704d0bc6cae7646c46978bc69  MEMORY.md

0685a25133fd3e7f60e70ba1e836a2e8b045ace1e2be2ecbd306a4fc656f558f README.md 34212f199411c8e4ef52cb341b0c68d970b5b30d9b8117c2eae5729b0d71dfa5 records.jsonl

If you edit a pack by hand, regenerate it from inside the pack directory:

shasum -a 256 MEMORY.md README.md records.jsonl > SHA256SUMS   # macOS

sha256sum MEMORY.md README.md records.jsonl > SHA256SUMS # Linux

Resealing by hand only makes the checksums match again; it does not re-check quotes. Prefer rebuilding with the builder. Resealing also invalidates any signature: sign again.

Signed and dated packs

A pack can carry two optional extras:

• SHA256SUMS.sig: an OpenSSH signature over the exact SHA256SUMS bytes, which pin every other file. Only Ed25519 keys, the sha512 hash and the namespace verified-memory-pack-v1 are accepted, so a git or code-release signature cannot be reused as a pack signature.
• PACK.json (since 0.3.0): when the pack was made and when it stops being current, and (since 0.4.0) an optional sequence number. It is listed in SHA256SUMS like every other file, so the signature covers the dates and the sequence.

{

"format": "verified-memory-pack", "version": 2, "created_utc": "2026-10-12T18:00:00Z", "expires_utc": "2027-01-10T18:00:00Z", "sequence": 3 }

Exactly these four keys plus the optional sequence; dates are UTC ISO 8601 and created_utc is before expires_utc. version is the format version and stays 2; sequence is a whole number (0 or more) that the signer raises with every pack they publish, so hosts can refuse an older one (see Rollback protection). A malformed PACK.json refuses to load. The pack maker and the builder never write one, so their packs still load on 0.2.0 hosts; packs with a PACK.json need 0.3.0 or later (older hosts refuse the extra file), and packs with a sequence need 0.4.0 or later (0.3.0 hosts refuse the extra key).

Signing: sign-pack

Sign on a machine you trust with a passphrase-protected key. Since 0.4.1, sign-pack ships in the npm package as the verified-memory-sign-pack command (in a checkout it is tools/sign-pack.mjs). It copies a verified pack to a new folder, writes PACK.json, reseals SHA256SUMS and runs ssh-keygen -Y sign. It never opens the private key itself: ssh-keygen reads it and asks for the passph