Skip to main content

zmem

Local memory for Claude Code. One SQLite file. No cloud, no model, no subscription. Search everything you've built with Claude, and save only the facts you approve.

Why it exists

Claude Code forgets between sessions. Your transcripts already sit on your disk, full of decisions, dead ends and "why did we do it that way" answers, but there is no good way to find them again.

The usual fix is a memory service that copies your conversations to someone else's server. Those transcripts contain your code, your ticket names and your internal paths. zmem keeps all of it on your machine instead: it indexes the transcripts you already have into one SQLite file and searches them with plain word matching. Nothing leaves the machine and no model is called.

It also never saves a fact on its own. /remember drafts short facts from a session and waits for your yes. You can read, search and delete every one.

Limits, up front:

  • Keyword search only. It matches words (stemmed), not meaning. "auth bug" will not find "login failure". There are no embeddings, on purpose.
  • Claude Code only. It reads Claude Code transcripts, not other tools or chats.
  • Single machine. No sync and no sharing between people.
  • Manual saves. Facts are written only when you approve them, so you have to remember to.

What it is

Local full-text search over your Claude Code session transcripts, plus a small table of facts you approve yourself. Python standard library only. No network, no model, no embeddings.

  • Index: one SQLite file (FTS5). Default ~/.zmem/index.db, override with ZMEM_DB.
  • Scope filter: ~/.zmem/scope.txt, override with ZMEM_SCOPE. See below.
  • Built for the development process: the facts are what you found, decided, changed and checked. A fact can also carry a stage of your own SDLC, whatever you want to tag that memory with (--stage plan, --stage spike, --stage release). zmem defines no stages and enforces no order. Tag a fact with the ticket it is about too (--ticket PMR3-1234), so you can see where each ticket is in the process: fact list --ticket PMR3-1234. Claude can filter by stage and ticket through the MCP.
  • Input: ~/.claude/projects/<project-folder>/<session-id>.jsonl.

Files

File What it is
pyproject.toml packaging: installs zmem and zmem-mcp commands
src/zmem.py the CLI: index, search, fact, show, sessions, scope, purge, stats
src/zmem_mcp.py read-only MCP server (search, list sessions, read session, list facts). No write tool
skills/remember, skills/recall Claude Code skills that wrap the CLI. Copy into ~/.claude/skills/
scope.example.txt template for your scope file
docs/HELP.md how to install and use it: commands, scope, skills, MCP, troubleshooting
docs/SPEC.md brief product spec: problem, goals, non-goals, data, rules
docs/PROMPT.md the detailed build spec the tool was built from

Setup

Full guide: docs/HELP.md.

Install with uv (adds zmem and zmem-mcp to your PATH):

uv tool install zmem
zmem --help

Then create a scope file (nothing is indexed without one), index, and search. Get scope.example.txt from the source distribution or copy its three lines from docs/HELP.md:

mkdir -p ~/.zmem
$EDITOR ~/.zmem/scope.txt     # one project-folder-name prefix per line, see "Scope" below
zmem scope                    # see which projects are in or out of scope
zmem index
zmem search "some words"

Optional:

claude mcp add zmem -- zmem-mcp     # read-only MCP server

The /remember and /recall skills live in skills/ of the source repository.

Tagging facts by ticket and stage (optional)

Both labels are yours to choose; zmem predefines nothing. A ticket code is Jira-style: a capitalized alphanumeric project key, a hyphen, then the ticket number.

<PROJECTKEY>-<NUMBER>      PMR3-1234     ABC-42
zmem fact add "found the bug in the parser" --ticket PMR3-1234 --stage evaluate --project myrepo
zmem fact add "plan: split parser in two"   --ticket PMR3-1234 --stage plan     --project myrepo
zmem fact list --ticket PMR3-1234          # that ticket's facts, newest first, with stages
zmem search parser --ticket PMR3-1234 --stage plan

Codes are matched whole and ignoring case (pmr3-1234 finds PMR3-1234; PMR3-12 does not find PMR3-1234). They are stored as the tags ticket-pmr3-1234 and stage-plan. The MCP search and list_facts tools take the same optional ticket and stage.

zmem vs Claude Code's built-in memory

They solve different problems and work well together.

Built-in memory (notes and CLAUDE.md) zmem
What it holds A few short notes Claude carries into each new session Your whole transcript history, indexed, plus facts you approve
How it is used Loaded into the session up front Searched on demand (/recall, zmem search, MCP)
Finding old work Only what was written down Any word from any indexed session, e.g. "when did we decide Y"
What gets saved Notes Claude or you write Only facts you approve, one at a time (fact add)
Ticket workflow No ticket or stage labels --ticket PMR3-1234 --stage plan, filterable
Removing data Edit or delete the note files fact delete, and purge compacts the index so deleted text is gone from the file
Where it lives Local files One local SQLite file, no network, no model, no embeddings
Claude's access Reads it, and can write notes Read-only through the MCP; Claude cannot save a fact

Use the built-in memory for the short standing rules Claude should always know. Use zmem when you need to find what was decided or tried in an earlier session, or to see where a ticket stands.

This comparison is based on how each tool is documented to work, not on a side-by-side test.

Scope: what it is and is not

scope.txt lists project-folder-name prefixes. A session is indexed, and a fact saved, only if its project folder starts with one of them. Its purpose is to separate work projects from non-work ones.

It is a classification filter, not a security control:

  • --project on fact add is whatever the caller types; it is not derived from where the work happened.
  • A fact add with no project skips the check (the tool prints a note).
  • scope.txt, ZMEM_SCOPE and the code are all ordinary editable files.

Keep out of git

The index holds your session text. Never put ~/.zmem or any .db file in a repository. .gitignore already excludes *.db and scope.txt.

Status

Written for one person's workflow. Not verified: behaviour on non-Linux paths, large indexes, and MCP protocol error handling beyond the normal path.

License

MIT. See LICENSE.

Metadata

Release files for zmem 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zmem 0.2.0
File Size Uploaded Provenance Actions
zmem-0.2.0.tar.gz 12.4 kB Without provenance Details for zmem-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zmem 0.2.0
File Interpreter ABI Platform Actions
zmem-0.2.0-py3-none-any.whl Python 3 none any Details for zmem-0.2.0-py3-none-any.whl

Total release size: 25.6 kB

Release files / zmem-0.2.0.tar.gz

Download URL zmem-0.2.0.tar.gz
Size 12.4 kB
Tags Source
SHA-256 checksum
How to use checksums
74f1f44c2f4ce89d0efe1728e8f8beec24e2b10866f02965b66182b2b20a43b1
BLAKE2b-256 checksum
How to use checksums
5079819d1f35a8ca1d6f347978764f99b29a5287b592f84f6e098f2adb1b91ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Release files / zmem-0.2.0-py3-none-any.whl

Download URL zmem-0.2.0-py3-none-any.whl
Size 13.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e3132e0a63b34feb27a0655beaa9e525da5b27939ce27f303182e7ec712a061a
BLAKE2b-256 checksum
How to use checksums
ae14c3be0c1105dfb604f0c38a63ef6f9800e0e1e1285a1c66da6d7dba73e68c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Security for zmem 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page