Metadata-Version: 2.4
Name: zmem
Version: 0.2.0
Summary: Local memory for Claude Code: SQLite FTS5 search over your session transcripts, plus facts you approve.
Author: Joe Palala
License-Expression: MIT
Keywords: claude-code,memory,sqlite,fts5,mcp,local-first
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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](docs/HELP.md).

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

```bash
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](docs/HELP.md):

```bash
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:**

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

```text
<PROJECTKEY>-<NUMBER>      PMR3-1234     ABC-42
```

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