keepsake

A small, local MCP server that gives AI chats a memory that lasts between sessions. It needs no cloud service, no GPU and no background service: just one SQLite file and Python.

• Local only. Memories live in a single SQLite file on your machine (default ~/.local/share/keepsake/memory.db, or %LOCALAPPDATA%\keepsake on Windows; readable only by you).

• Hybrid search. Keyword search (SQLite FTS5), plus optional meaning-based search with a small CPU model (all-MiniLM-L6-v2, ONNX). "Where's my vegetable patch?" finds the allotment.

• No duplicates piling up. Exact duplicates are counted, not re-saved. Near-duplicates are shown to the AI so it can update the existing memory instead. Subjects that evolve use a stable topic_key and are updated in place, with every earlier version kept.

• Nothing silently lost. Out-of-date memories are superseded (hidden but kept), and forget is a soft delete.

• Secrets refused. Anything that looks like a token, key, password or credential-bearing URL is rejected before it reaches disk. Card expiry dates, PINs and security codes are removed automatically. Wrap other sensitive parts in <private>…</private> to have them redacted.

• Exact matching. IPs, emails, card and gift card numbers, phone numbers, order and reference numbers, UUIDs and hashes are indexed, so match can check a list of values from elsewhere and report exact hits only: 203.0.113.45 never matches 203.0.113.46.

Renamed from chat-memory in 0.6. Existing databases, models, exports and CHAT_MEMORY_* settings are still found automatically; KEEPSAKE_* settings take priority.

The AI you're chatting with decides what is worth remembering, guided by the server's instructions (see INSTRUCTIONS in src/keepsake/server.py). The server stores, searches and guards against duplicates. That split keeps it light enough for an ordinary laptop.

Install

Requires Python 3.11+ and works on Linux, macOS and Windows. (Windows: see the Windows section for the commands.)

git clone https://github.com/mav-rix/keepsake.git
cd keepsake
python3 -m venv .venv
.venv/bin/pip install -e .

Optional: semantic search

.venv/bin/pip install -e '.[semantic]'
.venv/bin/keepsake download-model   # ~90 MB, pinned revision, SHA-256 checked

Privacy: the model runs entirely on your CPU. The only network access is download-model fetching two files (an HTTPS download from huggingface.co; nothing is sent except the request itself). Your memories and searches never leave the machine, and ONNX Runtime's optional telemetry is switched off. On a locked-down network, download the two files another way and set KEEPSAKE_MODEL_DIR (see below).

The model is stored in ~/.cache/keepsake/models/ (Windows: %LOCALAPPDATA%\keepsake\models) and loads on the first search, so a session that never searches stays at about 75 MB of RAM (about 275 MB once loaded). Existing memories are embedded automatically the first time they're needed, or run keepsake reindex. Set KEEPSAKE_SEMANTIC=0 to switch it off.

Claude Code

claude mcp add --scope user keepsake -- "$PWD/.venv/bin/keepsake"

GitHub Copilot (VS Code, Copilot CLI)

keepsake works with any model Copilot offers (OpenAI, Anthropic, Google...): MCP is model-neutral. Add it to Copilot's MCP config, ~/.copilot/mcp-config.json (Windows: %USERPROFILE%\.copilot\mcp-config.json), which VS Code's Copilot agent and the Copilot CLI both read:

{
  "mcpServers": {
    "keepsake": {
      "type": "stdio",
      "command": "C:\\Users\\you\\keepsake\\.venv\\Scripts\\keepsake.exe",
      "args": [],
      "env": { "KEEPSAKE_MODE": "work" },
      "tools": ["*"]
    }
  }
}

(Older VS Code setups use MCP: Open User Configuration, with the same entry under a "servers" key instead of "mcpServers".) Then, in Copilot Chat, check the tools list shows keepsake.

• Business/Enterprise seats: an organisation policy, MCP servers in Copilot, controls whether MCP servers can be used at all, and is off by default on some plans. Ask your admin.

• Instructions: VS Code passes the server's instructions to the model. If a model still doesn't save or recall when it should, run keepsake instructions --mode work and paste the output into your Copilot custom instructions.

• Models differ: how readily a model calls remember or match varies between models; asking directly ("check these against my cases", "log this case") always works.

• Data flow: recalled memories become part of the conversation, which Copilot sends to the model you've selected, under your organisation's Copilot agreement.

Claude Desktop and other MCP clients

Add to the client's MCP config (adjust the path):

{
  "mcpServers": {
    "keepsake": {
      "command": "/path/to/keepsake/.venv/bin/keepsake"
    }
  }
}

Set KEEPSAKE_DB to store the database somewhere else (see .env.example).

Windows

In PowerShell. Check py --version shows 3.11 or newer first (otherwise winget install Python.Python.3.12).

git clone https://github.com/mav-rix/keepsake.git
cd keepsake
py -3 -m venv .venv
.venv\Scripts\pip install -e ".[semantic]"        # or just -e . for keyword-only search
.venv\Scripts\keepsake download-model         # optional, ~90 MB
claude mcp add --scope user keepsake -- "$PWD\.venv\Scripts\keepsake.exe"
# work mode: add  -e KEEPSAKE_MODE=work  after "--scope user keepsake"
claude mcp list                                   # should show keepsake: Connected

• Where things live: the database is %LOCALAPPDATA%\keepsake\memory.db and the model is under %LOCALAPPDATA%\keepsake\models. They're protected by your Windows user account's folder permissions (the Linux/macOS "owner only" file mode doesn't apply).

• Claude Desktop: in its JSON config, double the backslashes: "command": "C:\\Users\\you\\keepsake\\.venv\\Scripts\\keepsake.exe".

• Don't move the folder after registering it; Claude Code runs the server from there. If you do, run claude mcp remove keepsake --scope user and add it again.

• Keep the database out of OneDrive/Dropbox. Syncing a live SQLite file can corrupt it. Use export/import to copy memories between machines.

Behind a company network

• pip: use your company's package mirror or proxy (pip install --proxy ... or pip config set global.index-url ...).

• Model download blocked? Many company filters block huggingface.co. You don't need it: keyword search and match work without the model. To get semantic search, use an approved internal copy; every file is still checked against its pinned SHA-256, whatever the source:

  # an Artifactory/Nexus "Hugging Face" repository (any HF-compatible endpoint; HF_ENDPOINT works too)
  keepsake download-model --mirror https://artifacts.example.com/artifactory/api/huggingfaceml/hf-remote
  # a plain file store: {name} becomes model.onnx / tokenizer.json ({path}: onnx/model.onnx)
  keepsake download-model --mirror "https://artifacts.example.com/generic/minilm/{name}"
  # files IT has given you
  keepsake download-model --from C:\path\to\folder

  If the mirror needs a token, set KEEPSAKE_MODEL_MIRROR_TOKEN (sent as a Bearer token; not passed on the command line so it stays out of shell history). KEEPSAKE_MODEL_MIRROR sets a default mirror. Files to request: onnx/model.onnx and tokenizer.json from sentence-transformers/all-MiniLM-L6-v2 at revision 1110a243fdf4706b3f48f1d95db1a4f5529b4d41 (Apache-2.0); their SHA-256 values are in src/keepsake/embed.py.

• Managed Claude Code: your IT team may only allow approved MCP servers. If claude mcp list doesn't show it, that's likely why. Check that keeping work chat memories in a local file is allowed.

Related MCP server: simple-memory-mcp

Tools

Your data stays private

The database is never inside the repository. .gitignore blocks database files and .jsonl exports anyway, as a second line of defence.

Work mode: case work and exact matching

For investigation work (fraud, disputes, support cases), where you need to check data from other parties against what you've seen before, run the server in work mode:

claude mcp add --scope user keepsake -e KEEPSAKE_MODE=work -- "$PWD/.venv/bin/keepsake"

Work mode changes only what the AI is asked to save: customer names, emails, phone numbers, IP addresses, order IDs, transaction references, device IDs and card or gift card numbers are saved in full (matching depends on exact values), one evolving record per case (kind="case", topic_key="case/<id>"). In every mode:

• Card expiry dates, PINs and security codes (CVV/CVC) are removed before saving and replaced with [REDACTED]; the response says what was removed. Card and gift card numbers are kept. Labelled values are caught (exp 12/27, PIN: 4821, CVV 123), as is an unlabelled MM/YY straight after a card number.

• Credentials are refused, as always.

How matching works

When a memory is saved, the identifiers in it are indexed in a normalised form, so different ways of writing the same value match:

Anything else, such as a customer name, is matched as a whole phrase, ignoring case (Jane Example matches; Jan doesn't match Jane). Superseded memories are included and marked, because old records still count as evidence; forgotten ones are not.

In a chat, give the AI the values and it calls match. From the command line, any text or CSV file works; every cell is checked:

keepsake match partner-report.csv          # identifiers only
keepsake match partner-report.csv --text   # also names and other plain cells

FOUND      ref     ORD-2026-118843  →  [12] Fraud case FR-1042
not found  ip      203.0.113.46
1 of 2 values found (exact matches only).

Before using this for real case data, check it fits your organisation's rules: card numbers and customer details will sit in a local SQLite file (not encrypted by keepsake, so rely on disk encryption such as BitLocker or FileVault), and recalled memories are sent to the AI as part of the conversation. Keep work and personal memories in separate databases.

Backups, moving machines, tidying up

keepsake export ~/memory-backup.jsonl     # readable only by you; warns if inside a git repo
keepsake import ~/memory-backup.jsonl --dry-run
keepsake import ~/memory-backup.jsonl
keepsake import ~/.claude/projects/<project>/memory   # bring in Claude Code's memory files
keepsake import other-tool.db --dry-run                # another tool's SQLite memory database

Moving from another SQLite-based memory tool

Many memory tools keep their data in SQLite, each with its own tables. inspect shows the tables, columns and row counts, and which columns it would use. It never prints row contents, so its output is safe to share with whoever is helping you migrate:

keepsake inspect old-memory.db
#   memories (1520 rows)  ← suggested
#     id INTEGER, content TEXT, tags TEXT, memory_type TEXT, created_at REAL, ...
#   Suggested: --table memories --map content=content --map kind=memory_type ...
keepsake import old-memory.db --dry-run
keepsake import old-memory.db                          # add --kind case for case records
keepsake import old-memory.db --table kb --map content=note_text --map title=heading

Fields you can map: content (required), title (else the first line of the content), kind, tags (JSON list or comma-separated), topic_key, project, created_at and updated_at (ISO text, or Unix seconds/milliseconds), and deleted_at (rows with a value are skipped). A type that isn't a keepsake kind is kept as a type:<name> tag; every imported memory is tagged imported. Full-text (FTS5/FTS4) tables are read when they hold the memories themselves; ones that only index another table, or hold no text, are skipped. The old database is opened read-only and never changed; close the old tool first (or import a copy). Records go through the same checks as any save, so card expiry dates, PINs and security codes are removed and credentials are refused. Importing again adds nothing new.

Exports are JSON Lines: a header line, then one memory per line with its version history (embeddings are rebuilt on import). Import is all or nothing and safe to repeat: exact duplicates are skipped, a topic_key that already exists keeps whichever version is newer (the other goes into history), superseded links are kept, and every record passes the same secret filter as remember.

keepsake review lists pairs that look like the same fact (cosine ≥ 0.80) or a changed fact (≥ 0.60), each with a suggested supersede, plus stale, repeated, superseded and forgotten memories. In a chat, ask the AI to tidy up your memory; it calls review and asks before changing anything. keepsake purge permanently deletes memories forgotten more than 30 days ago (it asks first).

How duplicates are judged

The cosine thresholds were calibrated on sample pairs with all-MiniLM-L6-v2: paraphrased duplicates scored 0.82–0.92, changed facts 0.61–0.74, related topics 0.21–0.38, unrelated ≤ 0.11. Embeddings use the memory's content only; titles count through keyword search.

Search scores mix 0.7 × meaning + 0.3 × keyword (BM25, normalised), with a small boost for pinned memories. On a 2021 laptop CPU, 10,000 memories search in about 45 ms.

Command line

keepsake                  # run the MCP server (stdio)
keepsake download-model   # fetch the embedding model (--mirror URL / --from FOLDER)
keepsake reindex          # embed memories that lack embeddings
keepsake stats            # counts and search mode
keepsake usage            # estimated tokens used by memory tool calls
keepsake review           # what needs tidying
keepsake match FILE       # exact hits for identifiers in a text/CSV file (--text for names)
keepsake export [FILE]    # back up as JSON Lines (stdout if no file)
keepsake import PATH      # merge an export, a Claude Code memory folder or a SQLite db (--dry-run)
keepsake inspect DB       # another tool's tables/columns and the suggested mapping (no content)
keepsake instructions     # the AI instructions, for clients' custom-instructions settings
keepsake purge            # permanently delete long-forgotten memories (--days, --yes)

Token use

Every tool call means the AI re-reads the whole conversation, so the number of round trips matters far more than the size of each answer. recall therefore returns the full text of its best hits (up to 3, within 8,000 characters), and the instructions ask for a single recall only when past context could matter, not a get_profile at every session start. In tests with Claude Code this cut tokens on memory-backed questions by roughly 45%, and added nothing measurable to questions that need no memory (Claude Code loads MCP tool definitions on demand). keepsake usage shows what the tools have returned; it logs only tool names and sizes, never content.

Development

.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
git config core.hooksPath .githooks   # runs gitleaks before each commit

The pre-commit hook needs gitleaks on your PATH.

Roadmap

1. Keyword search, topic keys, duplicate and secret guards (0.1)

2. Optional meaning-based search, mixed with keyword scores (0.2)

3. Export and import, near-duplicate and conflict review, restore (0.3)

4. Usage log, fewer round trips (0.4)

5. Work mode, card-detail redaction, exact identifier matching (0.5)

Credits

The design borrows ideas from these projects (no code copied):

• Engram (MIT): topic keys, normalized-hash duplicate counting, <private> redaction, version history

• mcp-memory-service (Apache-2.0): superseding instead of deleting, similarity bands for duplicates vs. related memories, the 0.7 / 0.3 hybrid weighting, the choice of all-MiniLM-L6-v2

• The reference memory server (MIT): one fact per observation, a prompt that guides what to remember

License

MIT. The optional embedding model, all-MiniLM-L6-v2, is Apache-2.0 and is downloaded separately, not bundled.