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 withZMEM_DB. - Scope filter:
~/.zmem/scope.txt, override withZMEM_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:
--projectonfact addis whatever the caller types; it is not derived from where the work happened.- A
fact addwith no project skips the check (the tool prints a note). scope.txt,ZMEM_SCOPEand 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.