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.
  • 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:

  • --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.1.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.1.0
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)

Table of built distributions (wheels) for zmem 0.1.0
File Interpreter ABI Platform Actions
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.

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