Metadata-Version: 2.4
Name: zmem
Version: 0.1.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.
- 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](docs/HELP.md).

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

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

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

```bash
git clone <repo-url> ~/gitrepos/zmem
export ZMEM_HOME=~/gitrepos/zmem            # used by the skills
python3 "$ZMEM_HOME/zmem.py" scope
```

**Optional:**

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