Reference

Usage

The same engine runs as a browser app, a Bun CLI, and an MCP server. The CLI is the reference for scripts and CI; it takes files and writes files, and it never uses the network.

Install

keepsake is not published to npm. Install the binary from GitHub with the one-line script, or run it without installing through Bun.

install

# one-line install (installs the `keepsake` binary)$ curl -fsSL https://raw.githubusercontent.com/srivtx/keepsake/main/install.sh | sh# run once, without installing$ bunx github:srivtx/keepsake#main --help# install globally$ bun add -g github:srivtx/keepsake# add as a project dev dependency$ bun add -d github:srivtx/keepsake

Commands

Thirteen commands, all local. Every command that touches a vault reads the passphrase from the environment, never from a flag.

keepsake commands.
Command	What it does
`import <file…>`	Import one or more sources into a new sealed vault. `--out` sets the vault path, `--source` overrides the origin label, `--tags a,b` adds tags, and `--iterations` sets the PBKDF2 cost.
`search <query>`	Lexical BM25 search over a decrypted vault. Prints ranked cells; exits `1` when nothing matches.
`export`	Decrypt a vault and print its plaintext cells, as text or with `--json`.
`verify`	Open a vault and confirm the GCM tag, every cell hash, and the Merkle root. Exits `1` if any check fails.
`stats`	Report the cell count, byte size, sources, and tags, as text or with `--json`.
`mcp`	Serve a vault over MCP on stdio for any MCP-capable agent.
`merge <vault…>`	Union two vaults into one sealed vault, keeping every distinct cell.
`forget`	Remove cells by id, tag, source, or query and rewrite the vault; the cells that remain are re-encrypted.
`rotate`	Re-encrypt a vault under a new passphrase, preserving the cells.
`diff <vault…>`	Compare two vaults and report the cells that were added, removed, or changed.
`context <task>`	Print a token-budgeted Markdown context pack for a task. It is generated on demand and never stored in the vault.
`pack`	Decrypt a vault and write a plaintext memory pack: one Markdown file that carries the same cells losslessly, for moving memory between tools or handing it to an agent.
`unpack <pack.md>`	Verify a memory pack's per-cell hashes and Merkle root and seal it into a new vault. Exits `1` if the pack does not verify.
`conformance`	Run the published conformance vectors (L1 parse, L2 integrity, L3 crypto round-trip) against this implementation. Exit 1 if any check fails, so any implementation can be tested in CI.

Import reads ChatGPT exports, Claude conversations.json, JSONL transcripts, JSON message arrays, and plain text or notes.

A memory pack is plaintext, not encrypted: anyone who has the file can read every cell, so treat it as you would the raw text and share it only where that is intended.

Examples

examples

# import a chat export into a new sealed vault$ keepsake import chatgpt-export.zip --source chatgpt-export --out memory.keepsake# import notes as free-form memories$ keepsake import notes.md --source notes.md --out memory.keepsake# search a vault locally (exact, lexical)$ keepsake search "sourdough" --vault memory.keepsake# export the plaintext cells$ keepsake export --vault memory.keepsake --json# verify hashes and the Merkle root$ keepsake verify --vault memory.keepsake# report stats, then serve the vault over MCP$ keepsake stats --vault memory.keepsake$ keepsake mcp --vault memory.keepsake

A real run

keepsake

$ keepsake import notes.md export.json --out memory.keepsakesealed 5 cell(s) into memory.keepsakemerkle  230b272ae6653e4619e67e37f616eb9d56c0d7482ebf4a3ef9ceac97a174f895$ keepsake search "staging database" --vault memory.keepsake1. [json · assistant · 2026-09-20T13:21:37.431Z]  #demoNoted: the staging database is cart-staging, reset nightly.

The passphrase

The passphrase is read from the KEEPSAKE_PASSPHRASE environment variable and is never accepted on the command line. A flag would land in your shell history and the process table. There is no recovery: a lost passphrase means a lost vault.

KEEPSAKE_PASSPHRASE='correct horse battery staple' keepsake export --vault memory.keepsake

Exit codes

The exit code is the CI gate.

keepsake exit codes.
Code	Meaning
`0`	Success, or for `verify`, a vault that checks out.
`1`	A finding or negative result: a failed check, or no matches.
`2`	Invalid usage, or a vault or cell that does not parse.
`3`	I/O error: a file could not be read, written, or found.

MCP server

Point any MCP-capable agent at a vault over stdio. The server exposes six tools: memory_recall, memory_context, memory_stats, and memory_verify to read, and memory_remember and memory_forget to write. memory_context returns the same token-budgeted pack as the CLI, and memory_forget removes a memory by id or query. It makes no network calls: the vault is opened in process.

{
  "mcpServers": {
    "keepsake": {
      "command": "bunx",
      "args": ["github:srivtx/keepsake#main", "mcp", "--vault", "/home/you/memory.keepsake"],
      "env": { "KEEPSAKE_PASSPHRASE": "…" }
    }
  }
}

Browser app

The landing page runs the same import, search, seal, and open operations in the tab, with no upload. See the conformance page to run the published vectors in your browser.

Semantic recall

The browser app can optionally run a real embedding model in the tab. After you click Load on-device model, it embeds every cell locally (384 dimensions, mean-pooled and normalized) and search gains three modes: lexical (BM25, the default), semantic (cosine over the on-device embeddings), and hybrid (a blend of both). The model is self-hosted and runs entirely in the browser, so no memory or query leaves the machine and no external requests are made. Loading it adds about 45 MB of one-time static assets; the feature is optional, and the app works without it. The CLI and the MCP server stay lexical (BM25).

← Spec Conformance →