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. - Input:
~/.claude/projects/<project-folder>/<session-id>.jsonl.
Files
| File | What it is |
|---|---|
pyproject.toml |
packaging: installs zmem and zmem-mcp commands |
zmem.py |
the CLI: index, search, fact, show, sessions, scope, purge, stats |
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):
git clone <repo-url> ~/gitrepos/zmem
uv tool install ~/gitrepos/zmem
zmem --help
Then create a scope file (nothing is indexed without one), index, and search:
mkdir -p ~/.zmem
cp ~/gitrepos/zmem/scope.example.txt ~/.zmem/scope.txt # then edit it
zmem scope # see which projects are in or out of scope
zmem index
zmem search "some words"
Or run from a clone, no install:
git clone <repo-url> ~/gitrepos/zmem
export ZMEM_HOME=~/gitrepos/zmem # used by the skills
python3 "$ZMEM_HOME/zmem.py" scope
Optional:
cp -r ~/gitrepos/zmem/skills/remember ~/gitrepos/zmem/skills/recall ~/.claude/skills/
claude mcp add zmem -- zmem-mcp # or: python3 "$ZMEM_HOME/zmem_mcp.py"
Not published to PyPI yet. The uv install above builds from your local clone.
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.1.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.1.0.tar.gz | 10.2 kB | Without provenance | Details for zmem-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zmem-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for zmem-0.1.0-py3-none-any.whl |
Total release size: 21.4 kB
Release files / zmem-0.1.0.tar.gz
| Download URL | zmem-0.1.0.tar.gz |
|---|---|
| Size | 10.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4931febde5f035d2f5337d416195fe8767bc6075ed639c9ddd50f7f7bc43fe21
|
|
BLAKE2b-256 checksum How to use checksums |
6f882a738d36ac11d47ed71e4fc02c8c2ed823321ec2d2d2db5db6dabe2e5e75
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / zmem-0.1.0-py3-none-any.whl
| Download URL | zmem-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6c0a804ecfed7cd92ba983d2aa6cd76b062b9fcc18cdf38d4b70f04ee72b7557
|
|
BLAKE2b-256 checksum How to use checksums |
b2f57c71abe9e80dc58380d71faaf9fc6ccf036c3f953abf72150dc7354f1294
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for zmem 0.1.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.