zmem 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- zmem-0.1.0.dist-info/METADATA +130 -0
- zmem-0.1.0.dist-info/RECORD +8 -0
- zmem-0.1.0.dist-info/WHEEL +5 -0
- zmem-0.1.0.dist-info/entry_points.txt +3 -0
- zmem-0.1.0.dist-info/licenses/LICENSE +21 -0
- zmem-0.1.0.dist-info/top_level.txt +2 -0
- zmem.py +313 -0
- zmem_mcp.py +112 -0
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: zmem
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Local memory for Claude Code: SQLite FTS5 search over your session transcripts, plus facts you approve.
|
|
5
|
+
Author: Joe Palala
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Keywords: claude-code,memory,sqlite,fts5,mcp,local-first
|
|
8
|
+
Classifier: Environment :: Console
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
11
|
+
Classifier: Topic :: Utilities
|
|
12
|
+
Requires-Python: >=3.8
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
Dynamic: license-file
|
|
16
|
+
|
|
17
|
+
# zmem
|
|
18
|
+
|
|
19
|
+
> **Local memory for Claude Code. One SQLite file. No cloud, no model, no subscription.**
|
|
20
|
+
> Search everything you've built with Claude, and save only the facts you approve.
|
|
21
|
+
|
|
22
|
+
## Why it exists
|
|
23
|
+
|
|
24
|
+
Claude Code forgets between sessions. Your transcripts already sit on your disk, full of
|
|
25
|
+
decisions, dead ends and "why did we do it that way" answers, but there is no good way to
|
|
26
|
+
find them again.
|
|
27
|
+
|
|
28
|
+
The usual fix is a memory service that copies your conversations to someone else's server.
|
|
29
|
+
Those transcripts contain your code, your ticket names and your internal paths. zmem keeps
|
|
30
|
+
all of it on your machine instead: it indexes the transcripts you already have into one
|
|
31
|
+
SQLite file and searches them with plain word matching. Nothing leaves the machine and no
|
|
32
|
+
model is called.
|
|
33
|
+
|
|
34
|
+
It also never saves a fact on its own. `/remember` drafts short facts from a session and
|
|
35
|
+
waits for your yes. You can read, search and delete every one.
|
|
36
|
+
|
|
37
|
+
**Limits, up front:**
|
|
38
|
+
- **Keyword search only.** It matches words (stemmed), not meaning. "auth bug" will not
|
|
39
|
+
find "login failure". There are no embeddings, on purpose.
|
|
40
|
+
- **Claude Code only.** It reads Claude Code transcripts, not other tools or chats.
|
|
41
|
+
- **Single machine.** No sync and no sharing between people.
|
|
42
|
+
- **Manual saves.** Facts are written only when you approve them, so you have to remember to.
|
|
43
|
+
|
|
44
|
+
## What it is
|
|
45
|
+
|
|
46
|
+
Local full-text search over your Claude Code session transcripts, plus a small table of
|
|
47
|
+
facts you approve yourself. Python standard library only. No network, no model, no embeddings.
|
|
48
|
+
|
|
49
|
+
- Index: one SQLite file (FTS5). Default `~/.zmem/index.db`, override with `ZMEM_DB`.
|
|
50
|
+
- Scope filter: `~/.zmem/scope.txt`, override with `ZMEM_SCOPE`. See below.
|
|
51
|
+
- Input: `~/.claude/projects/<project-folder>/<session-id>.jsonl`.
|
|
52
|
+
|
|
53
|
+
## Files
|
|
54
|
+
|
|
55
|
+
| File | What it is |
|
|
56
|
+
|---|---|
|
|
57
|
+
| `pyproject.toml` | packaging: installs `zmem` and `zmem-mcp` commands |
|
|
58
|
+
| `zmem.py` | the CLI: `index`, `search`, `fact`, `show`, `sessions`, `scope`, `purge`, `stats` |
|
|
59
|
+
| `zmem_mcp.py` | read-only MCP server (search, list sessions, read session, list facts). No write tool |
|
|
60
|
+
| `skills/remember`, `skills/recall` | Claude Code skills that wrap the CLI. Copy into `~/.claude/skills/` |
|
|
61
|
+
| `scope.example.txt` | template for your scope file |
|
|
62
|
+
| `docs/HELP.md` | how to install and use it: commands, scope, skills, MCP, troubleshooting |
|
|
63
|
+
| `docs/SPEC.md` | brief product spec: problem, goals, non-goals, data, rules |
|
|
64
|
+
| `docs/PROMPT.md` | the detailed build spec the tool was built from |
|
|
65
|
+
|
|
66
|
+
## Setup
|
|
67
|
+
|
|
68
|
+
Full guide: [docs/HELP.md](docs/HELP.md).
|
|
69
|
+
|
|
70
|
+
**Install with uv** (adds `zmem` and `zmem-mcp` to your PATH):
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
git clone <repo-url> ~/gitrepos/zmem
|
|
74
|
+
uv tool install ~/gitrepos/zmem
|
|
75
|
+
zmem --help
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Then create a scope file (nothing is indexed without one), index, and search:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
mkdir -p ~/.zmem
|
|
82
|
+
cp ~/gitrepos/zmem/scope.example.txt ~/.zmem/scope.txt # then edit it
|
|
83
|
+
zmem scope # see which projects are in or out of scope
|
|
84
|
+
zmem index
|
|
85
|
+
zmem search "some words"
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
**Or run from a clone, no install:**
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
git clone <repo-url> ~/gitrepos/zmem
|
|
92
|
+
export ZMEM_HOME=~/gitrepos/zmem # used by the skills
|
|
93
|
+
python3 "$ZMEM_HOME/zmem.py" scope
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
**Optional:**
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
cp -r ~/gitrepos/zmem/skills/remember ~/gitrepos/zmem/skills/recall ~/.claude/skills/
|
|
100
|
+
claude mcp add zmem -- zmem-mcp # or: python3 "$ZMEM_HOME/zmem_mcp.py"
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Not published to PyPI yet. The `uv` install above builds from your local clone.
|
|
104
|
+
|
|
105
|
+
## Scope: what it is and is not
|
|
106
|
+
|
|
107
|
+
`scope.txt` lists project-folder-name prefixes. A session is indexed, and a fact saved,
|
|
108
|
+
only if its project folder starts with one of them. Its purpose is to separate work
|
|
109
|
+
projects from non-work ones.
|
|
110
|
+
|
|
111
|
+
It is a classification filter, not a security control:
|
|
112
|
+
|
|
113
|
+
- `--project` on `fact add` is whatever the caller types; it is not derived from where the
|
|
114
|
+
work happened.
|
|
115
|
+
- A `fact add` with no project skips the check (the tool prints a note).
|
|
116
|
+
- `scope.txt`, `ZMEM_SCOPE` and the code are all ordinary editable files.
|
|
117
|
+
|
|
118
|
+
## Keep out of git
|
|
119
|
+
|
|
120
|
+
The index holds your session text. Never put `~/.zmem` or any `.db` file in a repository.
|
|
121
|
+
`.gitignore` already excludes `*.db` and `scope.txt`.
|
|
122
|
+
|
|
123
|
+
## Status
|
|
124
|
+
|
|
125
|
+
Written for one person's workflow. Not verified: behaviour on non-Linux paths, large
|
|
126
|
+
indexes, and MCP protocol error handling beyond the normal path.
|
|
127
|
+
|
|
128
|
+
## License
|
|
129
|
+
|
|
130
|
+
MIT. See `LICENSE`.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
zmem.py,sha256=ZilT6G4u0F-sNafMyY8woy1DD4EwVDSp8rQISUHQFR4,13166
|
|
2
|
+
zmem_mcp.py,sha256=R5ZXGHMNK5HTKQEHVWzpmDL6MqQ2eFzFra1wWR7b8Kk,4913
|
|
3
|
+
zmem-0.1.0.dist-info/licenses/LICENSE,sha256=tsefZq6d3gUHo0U2kzCgO3jHqPWyydGXVoEgo-85C_o,1067
|
|
4
|
+
zmem-0.1.0.dist-info/METADATA,sha256=fq6WQHK5o8SYP6Ypb5pBhQDAuVbtnKKXqHpxn6W88dE,4892
|
|
5
|
+
zmem-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
6
|
+
zmem-0.1.0.dist-info/entry_points.txt,sha256=INOdUeVabzcGZq0RnzeXHZe8j9zjwYx7scBzhtB23S4,60
|
|
7
|
+
zmem-0.1.0.dist-info/top_level.txt,sha256=mzgxLQOlkw2VxnhImsCm0ISAruCiYeRIVWT43rTfH2Y,14
|
|
8
|
+
zmem-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Joe Palala
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
zmem.py
ADDED
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""zmem: local full-text search over Claude Code session transcripts and notes.
|
|
3
|
+
Stdlib only. No network, no model. Index lives in $ZMEM_DB (default ~/.zmem/index.db).
|
|
4
|
+
|
|
5
|
+
zmem.py index [paths...] add/refresh sessions (default: ~/.claude/projects) and notes
|
|
6
|
+
zmem.py search "words" [-n 10] [--project X]
|
|
7
|
+
zmem.py show <session-id-prefix> [--grep word]
|
|
8
|
+
zmem.py scope show which projects are in/out of scope (names + counts only)
|
|
9
|
+
zmem.py purge [--yes] drop out-of-scope rows from the index (dry run without --yes)
|
|
10
|
+
zmem.py stats
|
|
11
|
+
zmem.py fact add "text" [--quote "exact words"] [--session ID] [--project P] [--tags a,b]
|
|
12
|
+
zmem.py fact list [-n 20] | fact delete <id>
|
|
13
|
+
Facts are written only when you ask (/remember); search shows them first.
|
|
14
|
+
|
|
15
|
+
Workflow (the slash commands wrap this tool; all local, nothing leaves the machine)
|
|
16
|
+
|
|
17
|
+
/remember [topic] save what is worth keeping from the current session
|
|
18
|
+
1. Claude drafts 3-12 short facts (one sentence each, with the why, dated,
|
|
19
|
+
"not verified" where unchecked) and checks `fact list` / `search --facts-only`
|
|
20
|
+
for duplicates.
|
|
21
|
+
2. You read the list and say yes, edit or drop lines. Nothing is saved before that.
|
|
22
|
+
3. Claude runs `fact add "<fact>" --quote "<your exact words>" --session <id>
|
|
23
|
+
--project=<folder> --tags a,b` for each approved fact.
|
|
24
|
+
4. Undo one with `fact delete <id>`. A project outside scope.txt is refused
|
|
25
|
+
("outside of scope"); check with `scope`.
|
|
26
|
+
|
|
27
|
+
/recall <words> find earlier work again
|
|
28
|
+
1. `search <words>` shows matching saved facts first, then matching session messages
|
|
29
|
+
(session id, date, role, project folder, snippet with your words in [brackets]).
|
|
30
|
+
Narrow with --project, limit with -n, facts only with --facts-only.
|
|
31
|
+
2. `sessions` lists sessions (id, dates, message count, project) when you do not
|
|
32
|
+
know the words.
|
|
33
|
+
3. `show <session-id-prefix> [--grep word]` reads one session in full, or only the
|
|
34
|
+
lines that match.
|
|
35
|
+
|
|
36
|
+
Notes
|
|
37
|
+
- Search is word matching, not meaning, and it has no topic field.
|
|
38
|
+
- `search` reads the existing index and does not refresh it. Run `index` to pick up
|
|
39
|
+
new sessions; `scope` and `purge` keep the index inside scope.txt.
|
|
40
|
+
"""
|
|
41
|
+
import argparse, datetime, json, os, re, sqlite3, sys, glob
|
|
42
|
+
|
|
43
|
+
DB = os.environ.get("ZMEM_DB", os.path.expanduser("~/.zmem/index.db"))
|
|
44
|
+
DEFAULT_ROOT = os.path.expanduser("~/.claude/projects")
|
|
45
|
+
SCOPE_FILE = os.environ.get("ZMEM_SCOPE", os.path.expanduser("~/.zmem/scope.txt"))
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def load_scope():
|
|
49
|
+
"""Prefixes of project folder names that may be indexed. None = no scope file."""
|
|
50
|
+
if not os.path.exists(SCOPE_FILE):
|
|
51
|
+
return None
|
|
52
|
+
with open(SCOPE_FILE, encoding="utf-8") as f:
|
|
53
|
+
return [l.strip().lower() for l in f if l.strip() and not l.lstrip().startswith("#")]
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def top_project(path):
|
|
57
|
+
rel = os.path.relpath(path, DEFAULT_ROOT)
|
|
58
|
+
if not rel.startswith(".."):
|
|
59
|
+
parts = rel.split(os.sep)
|
|
60
|
+
return parts[0] if len(parts) > 1 else ""
|
|
61
|
+
return os.path.basename(os.path.dirname(path))
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def in_scope(project, scope):
|
|
65
|
+
return any(project.lower().startswith(p) for p in scope)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def connect():
|
|
69
|
+
os.makedirs(os.path.dirname(DB), exist_ok=True)
|
|
70
|
+
c = sqlite3.connect(DB)
|
|
71
|
+
c.executescript("""
|
|
72
|
+
CREATE TABLE IF NOT EXISTS files(path TEXT PRIMARY KEY, mtime REAL, size INTEGER);
|
|
73
|
+
CREATE VIRTUAL TABLE IF NOT EXISTS msgs USING fts5(
|
|
74
|
+
text, role UNINDEXED, session UNINDEXED, project UNINDEXED,
|
|
75
|
+
ts UNINDEXED, path UNINDEXED, tokenize='porter unicode61');
|
|
76
|
+
CREATE VIRTUAL TABLE IF NOT EXISTS facts USING fts5(
|
|
77
|
+
text, quote, tags, session UNINDEXED, project UNINDEXED,
|
|
78
|
+
ts UNINDEXED, tokenize='porter unicode61');
|
|
79
|
+
""")
|
|
80
|
+
return c
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def text_of(content):
|
|
84
|
+
if isinstance(content, str):
|
|
85
|
+
return content
|
|
86
|
+
out = []
|
|
87
|
+
for b in content or []:
|
|
88
|
+
if isinstance(b, dict) and b.get("type") == "text":
|
|
89
|
+
out.append(b.get("text", ""))
|
|
90
|
+
return "\n".join(out)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def rows_from(path):
|
|
94
|
+
project = top_project(path)
|
|
95
|
+
session = os.path.splitext(os.path.basename(path))[0]
|
|
96
|
+
if path.endswith(".jsonl"):
|
|
97
|
+
with open(path, encoding="utf-8", errors="replace") as f:
|
|
98
|
+
for line in f:
|
|
99
|
+
try:
|
|
100
|
+
o = json.loads(line)
|
|
101
|
+
except ValueError:
|
|
102
|
+
continue
|
|
103
|
+
if o.get("type") not in ("user", "assistant") or o.get("isSidechain"):
|
|
104
|
+
continue
|
|
105
|
+
t = text_of((o.get("message") or {}).get("content")).strip()
|
|
106
|
+
if t:
|
|
107
|
+
yield (t, o["type"], session, project, o.get("timestamp", ""), path)
|
|
108
|
+
else:
|
|
109
|
+
with open(path, encoding="utf-8", errors="replace") as f:
|
|
110
|
+
t = f.read().strip()
|
|
111
|
+
if t:
|
|
112
|
+
yield (t, "note", os.path.basename(path), project, "", path)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def cmd_index(a):
|
|
116
|
+
c = connect()
|
|
117
|
+
n, total = index_paths(c, a.paths)
|
|
118
|
+
print(f"indexed {n} changed file(s) of {total}; db={DB}")
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def index_paths(c, paths=None):
|
|
122
|
+
paths = paths or [DEFAULT_ROOT]
|
|
123
|
+
scope = load_scope()
|
|
124
|
+
files = []
|
|
125
|
+
for p in paths:
|
|
126
|
+
p = os.path.expanduser(p)
|
|
127
|
+
if os.path.isdir(p):
|
|
128
|
+
if scope is None:
|
|
129
|
+
raise RuntimeError(f"no scope file at {SCOPE_FILE}; refusing to index folders. "
|
|
130
|
+
"Create it (one project-name substring per line) or run `zmem scope`.")
|
|
131
|
+
found = glob.glob(os.path.join(p, "**", "*.jsonl"), recursive=True)
|
|
132
|
+
files += [f for f in found if in_scope(top_project(f), scope)]
|
|
133
|
+
else:
|
|
134
|
+
files.append(p)
|
|
135
|
+
n = 0
|
|
136
|
+
for p in files:
|
|
137
|
+
st = os.stat(p)
|
|
138
|
+
row = c.execute("SELECT mtime,size FROM files WHERE path=?", (p,)).fetchone()
|
|
139
|
+
if row and row == (st.st_mtime, st.st_size):
|
|
140
|
+
continue
|
|
141
|
+
c.execute("DELETE FROM msgs WHERE path=?", (p,))
|
|
142
|
+
c.executemany("INSERT INTO msgs VALUES(?,?,?,?,?,?)", rows_from(p))
|
|
143
|
+
c.execute("REPLACE INTO files VALUES(?,?,?)", (p, st.st_mtime, st.st_size))
|
|
144
|
+
n += 1
|
|
145
|
+
c.commit()
|
|
146
|
+
return n, len(files)
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
SECRET = re.compile(r"AKIA[0-9A-Z]{12,}|eyJ[A-Za-z0-9_-]{15,}\.|(password|passwd|secret|token|api[_-]?key)\s*[=:]\s*\S{6,}|-----BEGIN [A-Z ]*PRIVATE KEY", re.I)
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def fact_project(a):
|
|
153
|
+
"""Project folder name for a fact: --project, else looked up from the session id."""
|
|
154
|
+
pr = a.project or ""
|
|
155
|
+
if pr.startswith("/"):
|
|
156
|
+
pr = pr.replace("/", "-").replace(".", "-")
|
|
157
|
+
if not pr and a.session:
|
|
158
|
+
hit = glob.glob(os.path.join(DEFAULT_ROOT, "*", a.session + "*.jsonl"))
|
|
159
|
+
pr = top_project(hit[0]) if hit else ""
|
|
160
|
+
return pr
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def cmd_fact(a):
|
|
164
|
+
c = connect()
|
|
165
|
+
if a.action == "add":
|
|
166
|
+
body = " ".join(a.text)
|
|
167
|
+
scope = load_scope()
|
|
168
|
+
if scope is None:
|
|
169
|
+
sys.exit(f"refused: no scope file at {SCOPE_FILE}, so nothing can be saved.")
|
|
170
|
+
pr = fact_project(a)
|
|
171
|
+
if pr and not in_scope(pr, scope):
|
|
172
|
+
sys.exit("outside of scope")
|
|
173
|
+
if not pr:
|
|
174
|
+
print("note: project unknown, scope not checked", file=sys.stderr)
|
|
175
|
+
a.project = pr
|
|
176
|
+
if SECRET.search(body) or SECRET.search(a.quote or ""):
|
|
177
|
+
sys.exit("refused: looks like a credential. Say where it lives, not what it is.")
|
|
178
|
+
ts = datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds")
|
|
179
|
+
cur = c.execute("INSERT INTO facts(text,quote,tags,session,project,ts) VALUES(?,?,?,?,?,?)",
|
|
180
|
+
(body, a.quote or "", a.tags or "", a.session or "", a.project or "", ts))
|
|
181
|
+
c.commit()
|
|
182
|
+
print(f"fact #{cur.lastrowid} saved")
|
|
183
|
+
elif a.action == "list":
|
|
184
|
+
for i, t, sess, ts in c.execute(
|
|
185
|
+
"SELECT rowid,text,session,ts FROM facts ORDER BY rowid DESC LIMIT ?", (a.n,)):
|
|
186
|
+
print(f"#{i} {ts[:10]} {sess[:8]} {t}")
|
|
187
|
+
elif a.action == "delete":
|
|
188
|
+
c.execute("DELETE FROM facts WHERE rowid=?", (int(a.text[0]),))
|
|
189
|
+
c.commit()
|
|
190
|
+
print("deleted")
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
def cmd_search(a):
|
|
194
|
+
c = connect()
|
|
195
|
+
q = " ".join(a.words)
|
|
196
|
+
fsql = "SELECT rowid,text,quote,session,ts,tags FROM facts WHERE facts MATCH ?"
|
|
197
|
+
fargs = [q]
|
|
198
|
+
if a.project:
|
|
199
|
+
fsql += " AND project LIKE ?"
|
|
200
|
+
fargs.append(f"%{a.project}%")
|
|
201
|
+
for i, t, qu, sess, ts, tg in c.execute(fsql + " ORDER BY rank LIMIT ?", fargs + [a.n]):
|
|
202
|
+
print(f"FACT #{i} {ts[:10]} {sess[:8]} {tg}\n {t}" + (f"\n quote: {qu}" if qu else ""))
|
|
203
|
+
if a.facts_only:
|
|
204
|
+
return
|
|
205
|
+
sql = ("SELECT session, project, ts, role, snippet(msgs,0,'[',']','…',24) "
|
|
206
|
+
"FROM msgs WHERE msgs MATCH ?")
|
|
207
|
+
args = [q]
|
|
208
|
+
if a.project:
|
|
209
|
+
sql += " AND project LIKE ?"
|
|
210
|
+
args.append(f"%{a.project}%")
|
|
211
|
+
sql += " ORDER BY rank LIMIT ?"
|
|
212
|
+
args.append(a.n)
|
|
213
|
+
for s, p, ts, r, sn in c.execute(sql, args):
|
|
214
|
+
print(f"{s[:8]} {ts[:10]} {r:9} {p}\n {sn.replace(chr(10), ' ')}")
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
def cmd_show(a):
|
|
218
|
+
c = connect()
|
|
219
|
+
rows = c.execute("SELECT ts, role, text FROM msgs WHERE session LIKE ? ORDER BY ts",
|
|
220
|
+
(a.session + "%",)).fetchall()
|
|
221
|
+
for ts, r, t in rows:
|
|
222
|
+
if a.grep and a.grep.lower() not in t.lower():
|
|
223
|
+
continue
|
|
224
|
+
print(f"--- {ts[:19]} {r}\n{t}\n")
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def list_sessions(c, project=None, n=20):
|
|
228
|
+
sql = ("SELECT session, project, min(ts), max(ts), count(*) FROM msgs "
|
|
229
|
+
"WHERE role IN ('user','assistant')")
|
|
230
|
+
args = []
|
|
231
|
+
if project:
|
|
232
|
+
sql += " AND project LIKE ?"
|
|
233
|
+
args.append(f"%{project}%")
|
|
234
|
+
sql += " GROUP BY session ORDER BY max(ts) DESC LIMIT ?"
|
|
235
|
+
return c.execute(sql, args + [n]).fetchall()
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
def cmd_sessions(a):
|
|
239
|
+
for sess, proj, t0, t1, cnt in list_sessions(connect(), a.project, a.n):
|
|
240
|
+
print(f"{sess[:8]} {t0[:10]} to {t1[:10]} {cnt:4} msgs {proj}")
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
def project_counts():
|
|
244
|
+
out = {}
|
|
245
|
+
for f in glob.glob(os.path.join(DEFAULT_ROOT, "**", "*.jsonl"), recursive=True):
|
|
246
|
+
pr = top_project(f)
|
|
247
|
+
out[pr] = out.get(pr, 0) + 1
|
|
248
|
+
return out
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
def cmd_scope(a):
|
|
252
|
+
scope = load_scope()
|
|
253
|
+
print(f"scope file: {SCOPE_FILE} ({'missing: nothing will be indexed' if scope is None else str(len(scope)) + ' patterns'})")
|
|
254
|
+
ins = outs = 0
|
|
255
|
+
for pr, n in sorted(project_counts().items(), key=lambda x: -x[1]):
|
|
256
|
+
ok = scope is not None and in_scope(pr, scope)
|
|
257
|
+
ins += n if ok else 0
|
|
258
|
+
outs += 0 if ok else n
|
|
259
|
+
print(f" {'IN ' if ok else 'out'} {n:3} {pr}")
|
|
260
|
+
print(f"in scope: {ins} sessions, out of scope: {outs} (names and counts only; no content read)")
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
def cmd_purge(a):
|
|
264
|
+
c = connect()
|
|
265
|
+
scope = load_scope() or []
|
|
266
|
+
bad = [r[0] for r in c.execute("SELECT DISTINCT project FROM msgs") if not in_scope(r[0], scope)]
|
|
267
|
+
for pr in bad:
|
|
268
|
+
n = c.execute("SELECT count(*) FROM msgs WHERE project=?", (pr,)).fetchone()[0]
|
|
269
|
+
print(f"{'deleting' if a.yes else 'would delete'} {n:5} msgs {pr}")
|
|
270
|
+
if a.yes:
|
|
271
|
+
c.execute("DELETE FROM msgs WHERE project=?", (pr,))
|
|
272
|
+
c.execute("DELETE FROM files WHERE path LIKE ?", (f"%/{pr}/%",))
|
|
273
|
+
c.commit()
|
|
274
|
+
if bad and a.yes:
|
|
275
|
+
c.execute("INSERT INTO msgs(msgs) VALUES('optimize')")
|
|
276
|
+
c.commit()
|
|
277
|
+
c.execute("VACUUM")
|
|
278
|
+
print("compacted: deleted text no longer sits in the index file")
|
|
279
|
+
if not bad:
|
|
280
|
+
print("nothing out of scope in the index")
|
|
281
|
+
elif not a.yes:
|
|
282
|
+
print("dry run. add --yes to delete these rows from the index (raw session files are never touched)")
|
|
283
|
+
|
|
284
|
+
|
|
285
|
+
def cmd_stats(a):
|
|
286
|
+
c = connect()
|
|
287
|
+
print(c.execute("SELECT count(*) FROM files").fetchone()[0], "files,",
|
|
288
|
+
c.execute("SELECT count(*) FROM msgs").fetchone()[0], "messages,",
|
|
289
|
+
c.execute("SELECT count(*) FROM facts").fetchone()[0], "facts")
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def main():
|
|
293
|
+
p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
|
|
294
|
+
s = p.add_subparsers(dest="cmd", required=True)
|
|
295
|
+
i = s.add_parser("index"); i.add_argument("paths", nargs="*"); i.set_defaults(f=cmd_index)
|
|
296
|
+
q = s.add_parser("search"); q.add_argument("words", nargs="+"); q.add_argument("-n", type=int, default=10)
|
|
297
|
+
q.add_argument("--project"); q.add_argument("--facts-only", action="store_true"); q.set_defaults(f=cmd_search)
|
|
298
|
+
f = s.add_parser("fact"); f.add_argument("action", choices=["add", "list", "delete"])
|
|
299
|
+
f.add_argument("text", nargs="*"); f.add_argument("--quote"); f.add_argument("--session")
|
|
300
|
+
f.add_argument("--project"); f.add_argument("--tags"); f.add_argument("-n", type=int, default=20)
|
|
301
|
+
f.set_defaults(f=cmd_fact)
|
|
302
|
+
w = s.add_parser("show"); w.add_argument("session"); w.add_argument("--grep"); w.set_defaults(f=cmd_show)
|
|
303
|
+
l = s.add_parser("sessions"); l.add_argument("--project"); l.add_argument("-n", type=int, default=20)
|
|
304
|
+
l.set_defaults(f=cmd_sessions)
|
|
305
|
+
sc = s.add_parser("scope"); sc.set_defaults(f=cmd_scope)
|
|
306
|
+
pg = s.add_parser("purge"); pg.add_argument("--yes", action="store_true"); pg.set_defaults(f=cmd_purge)
|
|
307
|
+
t = s.add_parser("stats"); t.set_defaults(f=cmd_stats)
|
|
308
|
+
a = p.parse_args()
|
|
309
|
+
a.f(a)
|
|
310
|
+
|
|
311
|
+
|
|
312
|
+
if __name__ == "__main__":
|
|
313
|
+
main()
|
zmem_mcp.py
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""zmem MCP server (stdio, stdlib only). Read-only: search, list_sessions, read_session, facts.
|
|
3
|
+
Facts are written only through /remember (CLI), never by a tool call.
|
|
4
|
+
Register: claude mcp add zmem -- python3 /path/to/zmem_mcp.py
|
|
5
|
+
"""
|
|
6
|
+
import json, os, re, sys
|
|
7
|
+
|
|
8
|
+
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
|
9
|
+
import zmem
|
|
10
|
+
|
|
11
|
+
CAP = 20000
|
|
12
|
+
TOOLS = [
|
|
13
|
+
{"name": "search", "description": "Full-text search over past Claude Code sessions and saved facts. Facts come first.",
|
|
14
|
+
"inputSchema": {"type": "object", "properties": {
|
|
15
|
+
"query": {"type": "string"}, "project": {"type": "string"},
|
|
16
|
+
"limit": {"type": "integer", "default": 10}}, "required": ["query"]}},
|
|
17
|
+
{"name": "list_sessions", "description": "List indexed sessions, newest first.",
|
|
18
|
+
"inputSchema": {"type": "object", "properties": {
|
|
19
|
+
"project": {"type": "string"}, "limit": {"type": "integer", "default": 20}}}},
|
|
20
|
+
{"name": "read_session", "description": "Read messages of one session (id prefix). Optional word filter and last_n.",
|
|
21
|
+
"inputSchema": {"type": "object", "properties": {
|
|
22
|
+
"session": {"type": "string"}, "grep": {"type": "string"},
|
|
23
|
+
"last_n": {"type": "integer"}}, "required": ["session"]}},
|
|
24
|
+
{"name": "list_facts", "description": "List saved facts, newest first.",
|
|
25
|
+
"inputSchema": {"type": "object", "properties": {"limit": {"type": "integer", "default": 20}}}},
|
|
26
|
+
]
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def fts(q):
|
|
30
|
+
return " ".join('"%s"' % t.replace('"', "") for t in re.findall(r"\S+", q))
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def cap(t):
|
|
34
|
+
return t if len(t) <= CAP else t[:CAP] + f"\n[cut at {CAP} chars]"
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def call(name, a):
|
|
38
|
+
c = zmem.connect()
|
|
39
|
+
out = []
|
|
40
|
+
if name == "search":
|
|
41
|
+
q, n, pj = fts(a["query"]), int(a.get("limit", 10)), a.get("project")
|
|
42
|
+
fs, fa = "SELECT rowid,text,quote,session,ts FROM facts WHERE facts MATCH ?", [q]
|
|
43
|
+
ms = ("SELECT session,project,ts,role,snippet(msgs,0,'[',']','…',24) FROM msgs "
|
|
44
|
+
"WHERE msgs MATCH ?")
|
|
45
|
+
ma = [q]
|
|
46
|
+
if pj:
|
|
47
|
+
fs += " AND project LIKE ?"; fa.append(f"%{pj}%")
|
|
48
|
+
ms += " AND project LIKE ?"; ma.append(f"%{pj}%")
|
|
49
|
+
for i, t, qu, s, ts in c.execute(fs + " ORDER BY rank LIMIT ?", fa + [n]):
|
|
50
|
+
out.append(f"FACT #{i} {ts[:10]} {s[:8]}: {t}" + (f"\n quote: {qu}" if qu else ""))
|
|
51
|
+
for s, p, ts, r, sn in c.execute(ms + " ORDER BY rank LIMIT ?", ma + [n]):
|
|
52
|
+
out.append(f"{s[:8]} {ts[:10]} {r} {p}\n {sn.replace(chr(10), ' ')}")
|
|
53
|
+
elif name == "list_sessions":
|
|
54
|
+
for s, p, t0, t1, cnt in zmem.list_sessions(c, a.get("project"), int(a.get("limit", 20))):
|
|
55
|
+
out.append(f"{s[:8]} {t0[:10]} to {t1[:10]} {cnt} msgs {p}")
|
|
56
|
+
elif name == "read_session":
|
|
57
|
+
rows = c.execute("SELECT ts, role, text FROM msgs WHERE session LIKE ? ORDER BY ts",
|
|
58
|
+
(a["session"] + "%",)).fetchall()
|
|
59
|
+
g = (a.get("grep") or "").lower()
|
|
60
|
+
rows = [r for r in rows if g in r[2].lower()]
|
|
61
|
+
if a.get("last_n"):
|
|
62
|
+
rows = rows[-int(a["last_n"]):]
|
|
63
|
+
out = [f"--- {ts[:19]} {r}\n{t}" for ts, r, t in rows]
|
|
64
|
+
elif name == "list_facts":
|
|
65
|
+
for i, t, s, ts in c.execute("SELECT rowid,text,session,ts FROM facts ORDER BY rowid DESC LIMIT ?",
|
|
66
|
+
(int(a.get("limit", 20)),)):
|
|
67
|
+
out.append(f"#{i} {ts[:10]} {s[:8]} {t}")
|
|
68
|
+
else:
|
|
69
|
+
raise ValueError("unknown tool " + name)
|
|
70
|
+
return cap("\n".join(out) or "no results")
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def reply(i, result=None, error=None):
|
|
74
|
+
m = {"jsonrpc": "2.0", "id": i}
|
|
75
|
+
m["error" if error else "result"] = error or result
|
|
76
|
+
sys.stdout.write(json.dumps(m) + "\n")
|
|
77
|
+
sys.stdout.flush()
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def main():
|
|
81
|
+
try:
|
|
82
|
+
zmem.index_paths(zmem.connect())
|
|
83
|
+
except Exception as e:
|
|
84
|
+
print(f"zmem: startup index skipped: {e}", file=sys.stderr)
|
|
85
|
+
for line in sys.stdin:
|
|
86
|
+
try:
|
|
87
|
+
m = json.loads(line)
|
|
88
|
+
except ValueError:
|
|
89
|
+
continue
|
|
90
|
+
i, method = m.get("id"), m.get("method", "")
|
|
91
|
+
if i is None:
|
|
92
|
+
continue
|
|
93
|
+
if method == "initialize":
|
|
94
|
+
v = (m.get("params") or {}).get("protocolVersion", "2024-11-05")
|
|
95
|
+
reply(i, {"protocolVersion": v, "capabilities": {"tools": {}},
|
|
96
|
+
"serverInfo": {"name": "zmem", "version": "0.1"}})
|
|
97
|
+
elif method == "tools/list":
|
|
98
|
+
reply(i, {"tools": TOOLS})
|
|
99
|
+
elif method == "tools/call":
|
|
100
|
+
p = m.get("params") or {}
|
|
101
|
+
try:
|
|
102
|
+
reply(i, {"content": [{"type": "text", "text": call(p.get("name"), p.get("arguments") or {})}]})
|
|
103
|
+
except Exception as e:
|
|
104
|
+
reply(i, {"content": [{"type": "text", "text": f"error: {e}"}], "isError": True})
|
|
105
|
+
elif method == "ping":
|
|
106
|
+
reply(i, {})
|
|
107
|
+
else:
|
|
108
|
+
reply(i, error={"code": -32601, "message": "method not found"})
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
if __name__ == "__main__":
|
|
112
|
+
main()
|