claude-db 0.1.0 → 0.1.1
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.
- package/README.md +79 -242
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,301 +5,138 @@
|
|
|
5
5
|
[](https://www.npmjs.com/package/claude-db)
|
|
6
6
|
[](https://github.com/Avijit07x/claude-db/actions/workflows/ci.yml)
|
|
7
7
|
[](./LICENSE)
|
|
8
|
-
[](https://nodejs.org)
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## What it is
|
|
12
|
+
|
|
13
|
+
Claude Code forgets everything when a session ends. Next time you open it, you
|
|
14
|
+
re-explain the architecture, why you chose X over Y, and what already failed.
|
|
12
15
|
|
|
13
|
-
claude-db records
|
|
14
|
-
|
|
16
|
+
claude-db records those decisions as you work and gives them back
|
|
17
|
+
automatically. Local by default, no account, no subscription.
|
|
15
18
|
|
|
16
19
|
```bash
|
|
17
20
|
npm install -g claude-db
|
|
21
|
+
|
|
18
22
|
cd your-project
|
|
19
23
|
claude-db install --project
|
|
20
24
|
```
|
|
21
25
|
|
|
22
|
-
Restart Claude Code.
|
|
26
|
+
Restart Claude Code. That's it.
|
|
23
27
|
|
|
24
|
-
|
|
28
|
+
## How it works
|
|
29
|
+
|
|
30
|
+
Claude Code already writes every session to disk as JSONL — your prompts, its
|
|
31
|
+
replies, every tool call. claude-db reads that file, so it captures **why** you
|
|
32
|
+
did something, not just which files changed.
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
you send a prompt
|
|
36
|
+
│
|
|
37
|
+
├─ 1. save the previous turn
|
|
38
|
+
│ read new lines from the session transcript
|
|
39
|
+
│ keep turns that changed something
|
|
40
|
+
│ store title + reasoning + files, with an embedding
|
|
41
|
+
│
|
|
42
|
+
└─ 2. search memory using your prompt
|
|
43
|
+
inject the best match above your message
|
|
44
|
+
```
|
|
25
45
|
|
|
26
|
-
|
|
46
|
+
Both steps are hooks, so they always run. Nothing depends on Claude deciding to
|
|
47
|
+
look something up.
|
|
27
48
|
|
|
28
|
-
|
|
29
|
-
|
|
49
|
+
**What gets saved.** One observation per turn, and only if that turn edited a
|
|
50
|
+
file or ran a real command. Questions, `grep`, and "ok" are skipped. A busy day
|
|
51
|
+
produces 10 to 20 rows, not hundreds.
|
|
52
|
+
|
|
53
|
+
**What gets injected.** Recent session summaries at startup, plus the single
|
|
54
|
+
best match in full on each prompt. Roughly 350 tokens when something relevant
|
|
55
|
+
exists, zero when it doesn't.
|
|
56
|
+
|
|
57
|
+
An example of one stored memory:
|
|
30
58
|
|
|
31
59
|
```
|
|
32
60
|
[decision] Chose WebSocket over polling for live order updates
|
|
33
61
|
|
|
34
|
-
Asked: the
|
|
35
|
-
feel hand made not ai
|
|
62
|
+
Asked: the order feed keeps dropping
|
|
36
63
|
|
|
37
64
|
Polling at 3s hammered the API and still lagged behind. Switched to a
|
|
38
|
-
WebSocket subscription with exponential backoff
|
|
39
|
-
|
|
65
|
+
WebSocket subscription with exponential backoff and a replay flag, so no
|
|
66
|
+
order is missed during a drop.
|
|
40
67
|
|
|
41
68
|
Files: src/ws/client.ts, src/ws/reconnect.ts
|
|
42
69
|
Ran: Test run: pnpm test
|
|
43
70
|
```
|
|
44
71
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
The prompt is the only record of *what you wanted*. The agent's reply is the
|
|
48
|
-
only record of *why it did that*. Both exist in the transcript, and nowhere
|
|
49
|
-
else.
|
|
50
|
-
|
|
51
|
-
## Recall is automatic, not left to the model
|
|
52
|
-
|
|
53
|
-
| Moment | Who decides | Reliability |
|
|
54
|
-
| ---------------- | --------------------- | ------------- |
|
|
55
|
-
| Capture | hook, unconditional | always |
|
|
56
|
-
| Session start | hook, unconditional | always |
|
|
57
|
-
| **Every prompt** | **hook, if relevant** | **always** |
|
|
58
|
-
| Mid-conversation | the agent, via MCP | its judgment |
|
|
59
|
-
|
|
60
|
-
Exposing search as a tool and hoping the agent calls it is unreliable.
|
|
61
|
-
`UserPromptSubmit` searches with your prompt text and injects the best match
|
|
62
|
-
in full, so the reasoning is already in context before the agent decides
|
|
63
|
-
anything.
|
|
64
|
-
|
|
65
|
-
Three things keep this cheap and quiet:
|
|
66
|
-
|
|
67
|
-
- **Trivial prompts are rejected before any query runs.** "ok", "continue",
|
|
68
|
-
"thanks" cost 43ms and inject nothing.
|
|
69
|
-
- **A relevance floor suppresses noise.** Nearest-neighbour search always
|
|
70
|
-
returns its top k however poor the match, so anything below the embedder's
|
|
71
|
-
measured noise floor is dropped. An unrelated prompt injects nothing at all.
|
|
72
|
-
- **A character budget caps the block.**
|
|
73
|
-
|
|
74
|
-
Measured: about **350 tokens** on a prompt with relevant history, **0** on one
|
|
75
|
-
without, 114ms of latency.
|
|
72
|
+
## Commands
|
|
76
73
|
|
|
77
|
-
|
|
74
|
+
Nine. `cdb` is a shorter alias for all of them.
|
|
78
75
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
76
|
+
| Command | What it does |
|
|
77
|
+
| --- | --- |
|
|
78
|
+
| `claude-db install [--project]` | Register hooks and the MCP server |
|
|
79
|
+
| `claude-db uninstall [--project]` | Remove them, keeping your memory |
|
|
80
|
+
| `claude-db status` | Is it wired up, has it recorded anything |
|
|
81
|
+
| `claude-db doctor` | Resolved config and database connectivity |
|
|
82
|
+
| `claude-db search <query>` | Search this project's memory |
|
|
83
|
+
| `claude-db projects` | Every project with memory stored |
|
|
84
|
+
| `claude-db use <url>` | Switch database and verify it |
|
|
85
|
+
| `claude-db flush` | Re-ingest every transcript for this project |
|
|
86
|
+
| `claude-db reset [--project] --yes` | Delete memory (dry run without `--yes`) |
|
|
88
87
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
88
|
+
`--project` scopes to one repo instead of every project on the machine. It
|
|
89
|
+
writes `.claude/settings.local.json` and `.mcp.json` — add `.mcp.json` to your
|
|
90
|
+
`.gitignore`, since it holds a machine-specific path.
|
|
92
91
|
|
|
93
92
|
## Bring your own database
|
|
94
93
|
|
|
95
|
-
|
|
96
|
-
|
|
94
|
+
SQLite by default, at `~/.claude-memory/memory.db`. No setup, no network.
|
|
95
|
+
|
|
96
|
+
Only needed if you want memory shared across machines:
|
|
97
97
|
|
|
98
98
|
```bash
|
|
99
99
|
claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
|
|
100
100
|
claude-db use "postgres://user:pass@host:5432/memory"
|
|
101
|
-
claude-db use "~/.claude-memory/memory.db" # SQLite, the default
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
Or set `CLAUDE_DB_URL`, which overrides the config file so containers and CI
|
|
105
|
-
can share a database without editing anything on disk.
|
|
106
|
-
|
|
107
|
-
| Backend | Keyword search | Vector search | Setup |
|
|
108
|
-
| -------- | ---------------- | -------------------------------------- | ------------------------ |
|
|
109
|
-
| SQLite | FTS5 + bm25 | exact cosine, in process | none, builtin to Node |
|
|
110
|
-
| MongoDB | text index | Atlas `$vectorSearch`, else in process | any Mongo, Atlas not req |
|
|
111
|
-
| Postgres | tsvector/ts_rank | pgvector HNSW when available | any Postgres |
|
|
112
|
-
|
|
113
|
-
Every adapter implements one small interface. Ranking, fusion and token
|
|
114
|
-
budgeting live outside the adapters, so recall behaves identically no matter
|
|
115
|
-
what you plug in. Only the retrieval cost changes.
|
|
116
|
-
|
|
117
|
-
```bash
|
|
118
|
-
npm install mongodb # only if you use a mongodb:// URL
|
|
119
|
-
npm install pg # only if you use a postgres:// URL
|
|
120
101
|
```
|
|
121
102
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
```
|
|
127
|
-
$ claude-db projects
|
|
128
|
-
* 412 2026-08-15 /Users/you/work/animateicons
|
|
129
|
-
87 2026-08-14 /Users/you/work/shop-api
|
|
130
|
-
```
|
|
103
|
+
The connection string picks the backend. Install the driver you need
|
|
104
|
+
(`npm install mongodb` or `pg`); neither ships by default. `CLAUDE_DB_URL`
|
|
105
|
+
overrides the config file if you prefer an env var.
|
|
131
106
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
nothing.
|
|
107
|
+
Search is hybrid — keyword plus vector — on all three. Memory is partitioned by
|
|
108
|
+
project path, so one database serves every repo you work in.
|
|
135
109
|
|
|
136
|
-
|
|
137
|
-
`~/repo/packages/web` creates two separate memories, so install at the repo
|
|
138
|
-
root. And moving a project orphans its memory, since the path is the key;
|
|
139
|
-
`claude-db flush` rebuilds it.
|
|
140
|
-
|
|
141
|
-
## Commands
|
|
142
|
-
|
|
143
|
-
```
|
|
144
|
-
claude-db install [--project] register hooks + MCP server
|
|
145
|
-
claude-db uninstall [--project] remove them, leaving memory intact
|
|
146
|
-
claude-db status is it wired up, has it recorded anything
|
|
147
|
-
claude-db doctor resolved config and connectivity
|
|
148
|
-
claude-db use <url> switch database and verify it
|
|
149
|
-
claude-db search <query> search this project's memory
|
|
150
|
-
claude-db projects every project with memory
|
|
151
|
-
claude-db flush re-ingest every transcript for this project
|
|
152
|
-
claude-db reset [--project] --yes delete memory (dry run without --yes)
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
`cdb` is a shorter alias for all of the above.
|
|
156
|
-
|
|
157
|
-
`--project` scopes to one repo via `.claude/settings.local.json` and
|
|
158
|
-
`.mcp.json`, instead of every project on the machine. Add `.mcp.json` to your
|
|
159
|
-
`.gitignore`: it holds an absolute path that would break for teammates.
|
|
160
|
-
|
|
161
|
-
## The part worth stealing: progressive disclosure
|
|
162
|
-
|
|
163
|
-
Naive memory search returns whole records and burns thousands of tokens on
|
|
164
|
-
results the agent throws away. Retrieval here is split into three layers, so
|
|
165
|
-
the agent pays for detail only after deciding what is relevant.
|
|
166
|
-
|
|
167
|
-
```
|
|
168
|
-
search() compact index, ~50-100 tokens per hit, no bodies
|
|
169
|
-
timeline() chronological neighbours of a promising hit
|
|
170
|
-
get_observations() full bodies, only for hand-picked ids
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
Filter at layer 1, expand at layer 3. That is where the roughly 10x saving
|
|
174
|
-
comes from. These are exposed as three MCP tools whose descriptions state the
|
|
175
|
-
intended order, because the saving only materialises if the agent filters
|
|
176
|
-
before fetching.
|
|
110
|
+
## Requirements
|
|
177
111
|
|
|
178
|
-
|
|
112
|
+
Node 22.5 or newer. That's the only hard requirement: SQLite comes from Node's
|
|
113
|
+
builtin `node:sqlite`, so nothing compiles at install time.
|
|
179
114
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
claude-db uses Reciprocal Rank Fusion instead: it discards magnitudes and
|
|
183
|
-
fuses on rank position alone, which needs no per-backend tuning. A mild
|
|
184
|
-
recency boost follows, 45-day half life with a floor, so a recent decision
|
|
185
|
-
edges out an equally relevant old one without burying it.
|
|
115
|
+
Embeddings run locally with a zero-dependency embedder. For real semantic
|
|
116
|
+
search, `npm install @xenova/transformers` and it upgrades itself.
|
|
186
117
|
|
|
187
118
|
## Privacy
|
|
188
119
|
|
|
189
120
|
Nothing leaves your machine unless you point it at a remote database.
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
- Text wrapped in `<private>...</private>` is stripped before storage
|
|
194
|
-
- API keys, GitHub tokens and `password`/`secret`/`token` values are redacted
|
|
195
|
-
by pattern before anything is written
|
|
196
|
-
|
|
197
|
-
Embeddings are computed locally in both modes. There is no API key, no
|
|
198
|
-
per-token cost, and no path that sends your code to a third party.
|
|
199
|
-
|
|
200
|
-
## Embedding providers
|
|
201
|
-
|
|
202
|
-
| Provider | Install cost | What it catches |
|
|
203
|
-
| --------- | -------------- | -------------------------------------------------- |
|
|
204
|
-
| `auto` | none | default: tries `local`, falls back to `builtin` |
|
|
205
|
-
| `builtin` | none | morphology and typos: `reconnect` ~ `reconnecting` |
|
|
206
|
-
| `local` | ~25MB download | real semantics: `car` ~ `automobile` |
|
|
207
|
-
| `none` | none | keyword only |
|
|
208
|
-
|
|
209
|
-
The builtin embedder uses the hashing trick over word and character trigrams.
|
|
210
|
-
Being honest about it: that is lexical similarity, not meaning. It will match
|
|
211
|
-
`reconnect` to `reconnecting` where FTS5 token matching fails, but it will not
|
|
212
|
-
match `car` to `automobile`. It exists so a zero-config install gets fuzzy
|
|
213
|
-
recall rather than nothing.
|
|
214
|
-
|
|
215
|
-
```bash
|
|
216
|
-
npm install @xenova/transformers # upgrade to real sentence embeddings
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
`auto` probes the model with a real inference call, so a broken ONNX runtime
|
|
220
|
-
degrades silently instead of failing.
|
|
221
|
-
|
|
222
|
-
## Configuration
|
|
223
|
-
|
|
224
|
-
Everything is optional. These are the defaults with no file present.
|
|
225
|
-
|
|
226
|
-
`~/.claude-memory/config.json`:
|
|
227
|
-
|
|
228
|
-
```json
|
|
229
|
-
{
|
|
230
|
-
"database": "",
|
|
231
|
-
"embeddings": { "provider": "auto", "maxScanCandidates": 25000 },
|
|
232
|
-
"capture": {
|
|
233
|
-
"tools": ["Edit", "Write", "Bash", "NotebookEdit"],
|
|
234
|
-
"exclude": [".env", "secrets", "node_modules", ".git/"],
|
|
235
|
-
"maxBodyChars": 4000
|
|
236
|
-
},
|
|
237
|
-
"inject": {
|
|
238
|
-
"sessions": 5,
|
|
239
|
-
"maxChars": 6000,
|
|
240
|
-
"perPrompt": true,
|
|
241
|
-
"promptResults": 4,
|
|
242
|
-
"promptMaxChars": 500,
|
|
243
|
-
"expandTop": 1,
|
|
244
|
-
"expandMaxChars": 900
|
|
245
|
-
}
|
|
246
|
-
}
|
|
247
|
-
```
|
|
248
|
-
|
|
249
|
-
Set `inject.perPrompt` to `false` for tool-only recall.
|
|
250
|
-
|
|
251
|
-
## How it works
|
|
252
|
-
|
|
253
|
-
```
|
|
254
|
-
SessionStart inject summaries of recent sessions
|
|
255
|
-
UserPromptSubmit flush the previous turn, then inject relevant memory
|
|
256
|
-
SessionEnd final flush and close
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
Memory is written **on every prompt**, not only at session end. A prompt is
|
|
260
|
-
the moment the previous turn is provably finished, and it is the one event
|
|
261
|
-
guaranteed to fire while a session is alive. Sessions that crash, are
|
|
262
|
-
force-quit, or stay open for days never reach `SessionEnd`.
|
|
263
|
-
|
|
264
|
-
That is only safe because observation ids are content-derived
|
|
265
|
-
(`sha256(session + turn timestamp + prompt)`), so re-reading a turn rewrites
|
|
266
|
-
the same row instead of appending a duplicate. A byte cursor per session means
|
|
267
|
-
each flush parses only the new tail, which matters because these transcripts
|
|
268
|
-
reach 90MB.
|
|
269
|
-
|
|
270
|
-
## Failure behaviour
|
|
271
|
-
|
|
272
|
-
A memory layer that breaks your session is worse than one that forgets, so
|
|
273
|
-
degradation is deliberate and tested:
|
|
274
|
-
|
|
275
|
-
- A hook that throws logs to stderr and exits 0. It never fails your session.
|
|
276
|
-
- If the sentence-transformer is unavailable, `auto` falls back to the builtin
|
|
277
|
-
and hybrid search keeps working.
|
|
278
|
-
- If embedding fails outright, observations are still persisted.
|
|
279
|
-
- If a backend cannot do vector search, fusion proceeds with keyword results.
|
|
280
|
-
|
|
281
|
-
## Requirements
|
|
282
|
-
|
|
283
|
-
Node 22.5 or newer. That is the only hard requirement. `mongodb`, `pg` and
|
|
284
|
-
`@xenova/transformers` are optional peers, loaded lazily, only if you opt in.
|
|
121
|
+
`.env`, `secrets/`, `node_modules` and `.git/` are never stored, text wrapped
|
|
122
|
+
in `<private>...</private>` is stripped, and API keys and tokens are redacted
|
|
123
|
+
before anything is written.
|
|
285
124
|
|
|
286
125
|
## Development
|
|
287
126
|
|
|
288
127
|
```bash
|
|
289
|
-
git clone https://github.com/Avijit07x/claude-db
|
|
290
|
-
cd claude-db
|
|
291
128
|
npm install
|
|
292
129
|
npm run build
|
|
293
130
|
npm test # 87 checks
|
|
294
|
-
npm run try # simulate a session
|
|
295
|
-
npm run bench # scaling curve
|
|
131
|
+
npm run try # simulate a session, touches nothing
|
|
296
132
|
```
|
|
297
133
|
|
|
298
|
-
|
|
299
|
-
`/tmp` is a symlink to `/private/tmp`, which is exactly the case that once
|
|
300
|
-
split a single project's memory in two.
|
|
134
|
+
Releases publish from CI on a version tag:
|
|
301
135
|
|
|
302
|
-
|
|
136
|
+
```bash
|
|
137
|
+
npm version patch
|
|
138
|
+
git push --follow-tags
|
|
139
|
+
```
|
|
303
140
|
|
|
304
141
|
## License
|
|
305
142
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "claude-db",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Persistent memory for Claude Code and other AI coding agents. Captures why decisions were made, not just which files changed. Bring your own database: SQLite, MongoDB or Postgres. No cloud, no subscription.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"type": "module",
|