zmem 0.1.0__tar.gz

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/LICENSE ADDED
@@ -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-0.1.0/PKG-INFO ADDED
@@ -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`.
zmem-0.1.0/README.md ADDED
@@ -0,0 +1,114 @@
1
+ # zmem
2
+
3
+ > **Local memory for Claude Code. One SQLite file. No cloud, no model, no subscription.**
4
+ > Search everything you've built with Claude, and save only the facts you approve.
5
+
6
+ ## Why it exists
7
+
8
+ Claude Code forgets between sessions. Your transcripts already sit on your disk, full of
9
+ decisions, dead ends and "why did we do it that way" answers, but there is no good way to
10
+ find them again.
11
+
12
+ The usual fix is a memory service that copies your conversations to someone else's server.
13
+ Those transcripts contain your code, your ticket names and your internal paths. zmem keeps
14
+ all of it on your machine instead: it indexes the transcripts you already have into one
15
+ SQLite file and searches them with plain word matching. Nothing leaves the machine and no
16
+ model is called.
17
+
18
+ It also never saves a fact on its own. `/remember` drafts short facts from a session and
19
+ waits for your yes. You can read, search and delete every one.
20
+
21
+ **Limits, up front:**
22
+ - **Keyword search only.** It matches words (stemmed), not meaning. "auth bug" will not
23
+ find "login failure". There are no embeddings, on purpose.
24
+ - **Claude Code only.** It reads Claude Code transcripts, not other tools or chats.
25
+ - **Single machine.** No sync and no sharing between people.
26
+ - **Manual saves.** Facts are written only when you approve them, so you have to remember to.
27
+
28
+ ## What it is
29
+
30
+ Local full-text search over your Claude Code session transcripts, plus a small table of
31
+ facts you approve yourself. Python standard library only. No network, no model, no embeddings.
32
+
33
+ - Index: one SQLite file (FTS5). Default `~/.zmem/index.db`, override with `ZMEM_DB`.
34
+ - Scope filter: `~/.zmem/scope.txt`, override with `ZMEM_SCOPE`. See below.
35
+ - Input: `~/.claude/projects/<project-folder>/<session-id>.jsonl`.
36
+
37
+ ## Files
38
+
39
+ | File | What it is |
40
+ |---|---|
41
+ | `pyproject.toml` | packaging: installs `zmem` and `zmem-mcp` commands |
42
+ | `zmem.py` | the CLI: `index`, `search`, `fact`, `show`, `sessions`, `scope`, `purge`, `stats` |
43
+ | `zmem_mcp.py` | read-only MCP server (search, list sessions, read session, list facts). No write tool |
44
+ | `skills/remember`, `skills/recall` | Claude Code skills that wrap the CLI. Copy into `~/.claude/skills/` |
45
+ | `scope.example.txt` | template for your scope file |
46
+ | `docs/HELP.md` | how to install and use it: commands, scope, skills, MCP, troubleshooting |
47
+ | `docs/SPEC.md` | brief product spec: problem, goals, non-goals, data, rules |
48
+ | `docs/PROMPT.md` | the detailed build spec the tool was built from |
49
+
50
+ ## Setup
51
+
52
+ Full guide: [docs/HELP.md](docs/HELP.md).
53
+
54
+ **Install with uv** (adds `zmem` and `zmem-mcp` to your PATH):
55
+
56
+ ```bash
57
+ git clone <repo-url> ~/gitrepos/zmem
58
+ uv tool install ~/gitrepos/zmem
59
+ zmem --help
60
+ ```
61
+
62
+ Then create a scope file (nothing is indexed without one), index, and search:
63
+
64
+ ```bash
65
+ mkdir -p ~/.zmem
66
+ cp ~/gitrepos/zmem/scope.example.txt ~/.zmem/scope.txt # then edit it
67
+ zmem scope # see which projects are in or out of scope
68
+ zmem index
69
+ zmem search "some words"
70
+ ```
71
+
72
+ **Or run from a clone, no install:**
73
+
74
+ ```bash
75
+ git clone <repo-url> ~/gitrepos/zmem
76
+ export ZMEM_HOME=~/gitrepos/zmem # used by the skills
77
+ python3 "$ZMEM_HOME/zmem.py" scope
78
+ ```
79
+
80
+ **Optional:**
81
+
82
+ ```bash
83
+ cp -r ~/gitrepos/zmem/skills/remember ~/gitrepos/zmem/skills/recall ~/.claude/skills/
84
+ claude mcp add zmem -- zmem-mcp # or: python3 "$ZMEM_HOME/zmem_mcp.py"
85
+ ```
86
+
87
+ Not published to PyPI yet. The `uv` install above builds from your local clone.
88
+
89
+ ## Scope: what it is and is not
90
+
91
+ `scope.txt` lists project-folder-name prefixes. A session is indexed, and a fact saved,
92
+ only if its project folder starts with one of them. Its purpose is to separate work
93
+ projects from non-work ones.
94
+
95
+ It is a classification filter, not a security control:
96
+
97
+ - `--project` on `fact add` is whatever the caller types; it is not derived from where the
98
+ work happened.
99
+ - A `fact add` with no project skips the check (the tool prints a note).
100
+ - `scope.txt`, `ZMEM_SCOPE` and the code are all ordinary editable files.
101
+
102
+ ## Keep out of git
103
+
104
+ The index holds your session text. Never put `~/.zmem` or any `.db` file in a repository.
105
+ `.gitignore` already excludes `*.db` and `scope.txt`.
106
+
107
+ ## Status
108
+
109
+ Written for one person's workflow. Not verified: behaviour on non-Linux paths, large
110
+ indexes, and MCP protocol error handling beyond the normal path.
111
+
112
+ ## License
113
+
114
+ MIT. See `LICENSE`.
@@ -0,0 +1,28 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "zmem"
7
+ version = "0.1.0"
8
+ description = "Local memory for Claude Code: SQLite FTS5 search over your session transcripts, plus facts you approve."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "Joe Palala" }]
13
+ requires-python = ">=3.8"
14
+ dependencies = []
15
+ keywords = ["claude-code", "memory", "sqlite", "fts5", "mcp", "local-first"]
16
+ classifiers = [
17
+ "Environment :: Console",
18
+ "Programming Language :: Python :: 3",
19
+ "Operating System :: POSIX :: Linux",
20
+ "Topic :: Utilities",
21
+ ]
22
+
23
+ [project.scripts]
24
+ zmem = "zmem:main"
25
+ zmem-mcp = "zmem_mcp:main"
26
+
27
+ [tool.setuptools]
28
+ py-modules = ["zmem", "zmem_mcp"]
zmem-0.1.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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,10 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ zmem.py
5
+ zmem_mcp.py
6
+ zmem.egg-info/PKG-INFO
7
+ zmem.egg-info/SOURCES.txt
8
+ zmem.egg-info/dependency_links.txt
9
+ zmem.egg-info/entry_points.txt
10
+ zmem.egg-info/top_level.txt
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ zmem = zmem:main
3
+ zmem-mcp = zmem_mcp:main
@@ -0,0 +1,2 @@
1
+ zmem
2
+ zmem_mcp
zmem-0.1.0/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-0.1.0/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()