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.
Files changed (2) hide show
  1. package/README.md +79 -242
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -5,301 +5,138 @@
5
5
  [![npm](https://img.shields.io/npm/v/claude-db.svg)](https://www.npmjs.com/package/claude-db)
6
6
  [![CI](https://github.com/Avijit07x/claude-db/actions/workflows/ci.yml/badge.svg)](https://github.com/Avijit07x/claude-db/actions/workflows/ci.yml)
7
7
  [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
8
- [![node](https://img.shields.io/badge/node-%3E%3D22.5-brightgreen.svg)](https://nodejs.org)
9
8
 
10
- Your agent forgets everything when a session ends. You re-explain the
11
- architecture, why you chose X over Y, and which approaches already failed.
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 that as it happens and gives it back on the next session.
14
- No hosted service, no subscription, no account, no database URL required.
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. Done.
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
- ## What it actually remembers
46
+ Both steps are hooks, so they always run. Nothing depends on Claude deciding to
47
+ look something up.
27
48
 
28
- Most memory tools capture file paths, because that is all a tool hook can see.
29
- claude-db reads the session transcript, so it captures **intent and reasoning**:
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 plan was not good, the output was really bad, it should
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 reconnect and a replay
39
- flag so no order is missed during a drop.
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
- Compare that with what a file-watching approach stores: `Write client.ts`.
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
- ## Works fully local, out of the box
74
+ Nine. `cdb` is a shorter alias for all of them.
78
75
 
79
- ```
80
- $ claude-db doctor
81
- database : ~/.claude-memory/memory.db
82
- adapter : sqlite
83
- reachable: yes
84
- embedder : builtin-hashing (256d)
85
- vectors : working (256d)
86
- search : hybrid (keyword + vector)
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
- No connection string, no config file, no model download, no network. SQLite
90
- comes from Node's builtin `node:sqlite`, so there is no native compilation
91
- step and nothing to fail at install time.
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
- Only needed if you want memory shared across machines. The connection string
96
- picks the backend; nothing else changes.
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
- ## Multiple projects
123
-
124
- One database, partitioned by the project's canonical absolute path.
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
- Searches only ever see one row. The project token is indexed inside FTS rather
133
- than applied as a post-match filter, so adding a project costs the others
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
- Two limits worth knowing: opening Claude Code in `~/repo` and
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
- ### Hybrid ranking
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
- Keyword scores (bm25, ts_rank) and vector scores (cosine) live on
181
- incompatible scales, so normalising one against the other is guesswork.
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
- - Paths matching `capture.exclude` (`.env`, `secrets`, `node_modules`,
192
- `.git/`) are never persisted
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 end to end, touches nothing
295
- npm run bench # scaling curve
131
+ npm run try # simulate a session, touches nothing
296
132
  ```
297
133
 
298
- CI runs on Node 22 and 24, on Linux and macOS. macOS is not optional there:
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
- See [RELEASING.md](./RELEASING.md) for the publish process.
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.0",
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",