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

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.1

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.1
File Size Uploaded Provenance Actions
zmem-0.1.1.tar.gz 10.2 kB Without provenance Details for zmem-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 21.3 kB

Release files / zmem-0.1.1.tar.gz

Download URL zmem-0.1.1.tar.gz
Size 10.2 kB
Tags Source
SHA-256 checksum
How to use checksums
ba01a822e5125b71f23814a23ccdb08e88bbb19beee8ef40c10caf433f761fd1
BLAKE2b-256 checksum
How to use checksums
3c6f941aa1d4b62e1e6bcac9fdbe024de45aa0ce579a4d0f1cf9fd384bf2acec
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.1-py3-none-any.whl

Download URL zmem-0.1.1-py3-none-any.whl
Size 11.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0748eaa63536e47aed687721b5368a0de79a4adf7e8d1300b12f3c263fc0f0fc
BLAKE2b-256 checksum
How to use checksums
bda324ccfa446c573273ac9206726861dacf05673622b92ffb9c1138689d3484
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.1

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