claude-db 0.1.0 → 0.2.0
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 +95 -243
- package/dist/capture/flush.d.ts +22 -0
- package/dist/capture/flush.js +45 -10
- package/dist/capture/identity.d.ts +6 -0
- package/dist/capture/identity.js +14 -0
- package/dist/capture/index.d.ts +5 -3
- package/dist/capture/index.js +4 -3
- package/dist/capture/manual.d.ts +21 -0
- package/dist/capture/manual.js +40 -0
- package/dist/capture/transcript.d.ts +12 -0
- package/dist/capture/transcript.js +69 -1
- package/dist/capture/turn-extractor.js +40 -8
- package/dist/cli/index.js +376 -30
- package/dist/cli/install.d.ts +15 -1
- package/dist/cli/install.js +127 -8
- package/dist/config/schema.d.ts +1 -0
- package/dist/config/schema.js +9 -1
- package/dist/context.js +24 -2
- package/dist/embed/builtin.js +3 -1
- package/dist/hooks/relevance.js +11 -4
- package/dist/hooks/session-end.js +2 -1
- package/dist/hooks/session-start.js +22 -3
- package/dist/mcp/server.js +56 -6
- package/dist/search/service.js +4 -1
- package/dist/store/adapter.d.ts +22 -6
- package/dist/store/adapter.js +10 -1
- package/dist/store/mongo/driver.d.ts +1 -0
- package/dist/store/mongo/index.d.ts +3 -2
- package/dist/store/mongo/index.js +57 -7
- package/dist/store/postgres/index.d.ts +22 -8
- package/dist/store/postgres/index.js +165 -21
- package/dist/store/sqlite/index.d.ts +3 -2
- package/dist/store/sqlite/index.js +112 -9
- package/dist/store/sqlite/schema.sql +4 -3
- package/dist/types.d.ts +28 -0
- package/dist/util/project.d.ts +9 -10
- package/dist/util/project.js +52 -13
- package/dist/util/vector.d.ts +11 -1
- package/dist/util/vector.js +14 -3
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -5,301 +5,153 @@
|
|
|
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.
|
|
23
|
-
|
|
24
|
-
---
|
|
26
|
+
Restart Claude Code. That's it.
|
|
25
27
|
|
|
26
|
-
##
|
|
28
|
+
## How it works
|
|
27
29
|
|
|
28
|
-
|
|
29
|
-
claude-db reads
|
|
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.
|
|
30
33
|
|
|
31
34
|
```
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
Files: src/ws/client.ts, src/ws/reconnect.ts
|
|
42
|
-
Ran: Test run: pnpm test
|
|
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
|
|
43
44
|
```
|
|
44
45
|
|
|
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.
|
|
46
|
+
Both steps are hooks, so they always run. Nothing depends on Claude deciding to
|
|
47
|
+
look something up.
|
|
50
48
|
|
|
51
|
-
|
|
49
|
+
Install also writes a short standing instruction into `CLAUDE.local.md` (or
|
|
50
|
+
`~/.claude/CLAUDE.md` for a machine-wide install), telling Claude to search
|
|
51
|
+
memory before asking you to re-explain something. Hook output is context the
|
|
52
|
+
agent may or may not act on; a memory file is a rule for the whole session,
|
|
53
|
+
which is what makes recall the default rather than something you have to ask
|
|
54
|
+
for. `claude-db uninstall` takes the block back out.
|
|
52
55
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
| Session start | hook, unconditional | always |
|
|
57
|
-
| **Every prompt** | **hook, if relevant** | **always** |
|
|
58
|
-
| Mid-conversation | the agent, via MCP | its judgment |
|
|
56
|
+
**What gets saved.** One observation per turn, and only if that turn edited a
|
|
57
|
+
file or ran a real command. Questions, `grep`, and "ok" are skipped. A busy day
|
|
58
|
+
produces 10 to 20 rows, not hundreds.
|
|
59
59
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
anything.
|
|
60
|
+
**What gets injected.** Recent session summaries at startup, plus the single
|
|
61
|
+
best match in full on each prompt. Roughly 350 tokens when something relevant
|
|
62
|
+
exists, zero when it doesn't.
|
|
64
63
|
|
|
65
|
-
|
|
64
|
+
An example of one stored memory:
|
|
66
65
|
|
|
67
|
-
|
|
68
|
-
|
|
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.**
|
|
66
|
+
```
|
|
67
|
+
[decision] Chose WebSocket over polling for live order updates
|
|
73
68
|
|
|
74
|
-
|
|
75
|
-
without, 114ms of latency.
|
|
69
|
+
Asked: the order feed keeps dropping
|
|
76
70
|
|
|
77
|
-
|
|
71
|
+
Polling at 3s hammered the API and still lagged behind. Switched to a
|
|
72
|
+
WebSocket subscription with exponential backoff and a replay flag, so no
|
|
73
|
+
order is missed during a drop.
|
|
78
74
|
|
|
79
|
-
|
|
80
|
-
|
|
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)
|
|
75
|
+
Files: src/ws/client.ts, src/ws/reconnect.ts
|
|
76
|
+
Ran: Test run: pnpm test
|
|
87
77
|
```
|
|
88
78
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
79
|
+
## Commands
|
|
80
|
+
|
|
81
|
+
`cdb` is a shorter alias for all of them.
|
|
82
|
+
|
|
83
|
+
| Command | What it does |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| `claude-db install [--project]` | Register hooks and the MCP server |
|
|
86
|
+
| `claude-db uninstall [--project]` | Remove them, keeping your memory |
|
|
87
|
+
| `claude-db status` | Is it wired up, has it recorded anything |
|
|
88
|
+
| `claude-db doctor` | Resolved config and database connectivity |
|
|
89
|
+
| `claude-db search [--all] <query>` | Search this project's memory, or every project |
|
|
90
|
+
| `claude-db remember <text>` | Record a rule outright, e.g. "always use pnpm here" |
|
|
91
|
+
| `claude-db forget <id>` | Delete specific observations by id |
|
|
92
|
+
| `claude-db stats` | What this project's memory is made of |
|
|
93
|
+
| `claude-db projects` | Every project with memory stored |
|
|
94
|
+
| `claude-db merge [<path>]` | Move memory from an old project path onto this one |
|
|
95
|
+
| `claude-db use <url>` | Switch database and verify it |
|
|
96
|
+
| `claude-db flush` | Re-ingest every transcript for this project |
|
|
97
|
+
| `claude-db export [--all]` | Dump memory as JSONL, for backup or migration |
|
|
98
|
+
| `claude-db import <file>` | Load a dump back in; safe to repeat |
|
|
99
|
+
| `claude-db reembed` | Re-embed everything with the current model |
|
|
100
|
+
| `claude-db prune --older-than <days>` | Delete old memory (dry run without `--yes`) |
|
|
101
|
+
| `claude-db reset [--project] --yes` | Delete memory (dry run without `--yes`) |
|
|
102
|
+
|
|
103
|
+
`--project` scopes to one repo instead of every project on the machine. It
|
|
104
|
+
writes `.claude/settings.local.json` and `.mcp.json` — add `.mcp.json` to your
|
|
105
|
+
`.gitignore`, since it holds a machine-specific path.
|
|
92
106
|
|
|
93
107
|
## Bring your own database
|
|
94
108
|
|
|
95
|
-
|
|
96
|
-
|
|
109
|
+
SQLite by default, at `~/.claude-memory/memory.db`. No setup, no network.
|
|
110
|
+
|
|
111
|
+
Only needed if you want memory shared across machines:
|
|
97
112
|
|
|
98
113
|
```bash
|
|
99
114
|
claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
|
|
100
115
|
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
|
-
```
|
|
121
|
-
|
|
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
|
-
```
|
|
131
|
-
|
|
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.
|
|
135
|
-
|
|
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
116
|
```
|
|
154
117
|
|
|
155
|
-
|
|
118
|
+
The connection string picks the backend. Install the driver you need
|
|
119
|
+
(`npm install mongodb` or `pg`); neither ships by default. `CLAUDE_DB_URL`
|
|
120
|
+
overrides the config file if you prefer an env var.
|
|
156
121
|
|
|
157
|
-
|
|
158
|
-
|
|
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
|
-
```
|
|
122
|
+
Search is hybrid — keyword plus vector — on all three. Memory is partitioned by
|
|
123
|
+
project path, so one database serves every repo you work in.
|
|
172
124
|
|
|
173
|
-
|
|
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.
|
|
125
|
+
## Requirements
|
|
177
126
|
|
|
178
|
-
|
|
127
|
+
Node 22.5 or newer. That's the only hard requirement: SQLite comes from Node's
|
|
128
|
+
builtin `node:sqlite`, so nothing compiles at install time.
|
|
179
129
|
|
|
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.
|
|
130
|
+
Embeddings run locally with a zero-dependency embedder. For real semantic
|
|
131
|
+
search, `npm install @xenova/transformers` and it upgrades itself.
|
|
186
132
|
|
|
187
133
|
## Privacy
|
|
188
134
|
|
|
189
135
|
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.
|
|
136
|
+
`.env`, `secrets/`, `node_modules` and `.git/` are never stored, text wrapped
|
|
137
|
+
in `<private>...</private>` is stripped, and API keys and tokens are redacted
|
|
138
|
+
before anything is written.
|
|
285
139
|
|
|
286
140
|
## Development
|
|
287
141
|
|
|
288
142
|
```bash
|
|
289
|
-
git clone https://github.com/Avijit07x/claude-db
|
|
290
|
-
cd claude-db
|
|
291
143
|
npm install
|
|
292
144
|
npm run build
|
|
293
145
|
npm test # 87 checks
|
|
294
|
-
npm run try # simulate a session
|
|
295
|
-
npm run bench # scaling curve
|
|
146
|
+
npm run try # simulate a session, touches nothing
|
|
296
147
|
```
|
|
297
148
|
|
|
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.
|
|
149
|
+
Releases publish from CI on a version tag:
|
|
301
150
|
|
|
302
|
-
|
|
151
|
+
```bash
|
|
152
|
+
npm version patch
|
|
153
|
+
git push --follow-tags
|
|
154
|
+
```
|
|
303
155
|
|
|
304
156
|
## License
|
|
305
157
|
|
package/dist/capture/flush.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { RecallContext } from '../context.js';
|
|
2
|
+
import type { Observation } from '../types.js';
|
|
2
3
|
export interface FlushResult {
|
|
3
4
|
observations: number;
|
|
4
5
|
summary: string | null;
|
|
@@ -17,4 +18,25 @@ export interface FlushResult {
|
|
|
17
18
|
* same row rather than appending a duplicate.
|
|
18
19
|
*/
|
|
19
20
|
export declare function flushSession(ctx: RecallContext, sessionId: string, project: string, transcriptPath?: string): Promise<FlushResult>;
|
|
21
|
+
/**
|
|
22
|
+
* Embeddings are an enhancement, never a precondition. A missing model must
|
|
23
|
+
* cost semantic recall, not the memory itself.
|
|
24
|
+
*/
|
|
25
|
+
export declare function embedObservations(ctx: RecallContext, observations: Observation[]): Promise<void>;
|
|
26
|
+
/**
|
|
27
|
+
* Recap of the session so far, and the only thing SessionStart injects.
|
|
28
|
+
*
|
|
29
|
+
* Taking the last three titles of the current flush was close to useless once
|
|
30
|
+
* capture became incremental: a flush usually carries a single turn, so the
|
|
31
|
+
* recap of an entire day's session was whatever happened to be typed last.
|
|
32
|
+
* Carrying the previous summary forward makes it cover the session, and
|
|
33
|
+
* ranking by kind keeps a decision over the build command that followed it.
|
|
34
|
+
*
|
|
35
|
+
* ponytail: first three win, so a decision made late in a long session does
|
|
36
|
+
* not displace an earlier one. Rank the session's stored observations instead
|
|
37
|
+
* if that turns out to matter.
|
|
38
|
+
*/
|
|
39
|
+
export declare function summarize(observations: Observation[], previous?: string): string;
|
|
20
40
|
export declare function resetCursor(sessionId: string): void;
|
|
41
|
+
/** The session is over; its offset is scratch state nothing will read again. */
|
|
42
|
+
export declare function clearCursor(sessionId: string): void;
|
package/dist/capture/flush.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
1
|
+
import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
|
|
2
2
|
import { dirname, join } from 'node:path';
|
|
3
3
|
import { CONFIG_DIR } from '../config/index.js';
|
|
4
4
|
import { readTranscript, transcriptPathFor } from './transcript.js';
|
|
@@ -29,9 +29,10 @@ export async function flushSession(ctx, sessionId, project, transcriptPath) {
|
|
|
29
29
|
writeCursor(sessionId, nextOffset);
|
|
30
30
|
return { observations: 0, summary: null };
|
|
31
31
|
}
|
|
32
|
-
await
|
|
32
|
+
await embedObservations(ctx, observations);
|
|
33
33
|
await ctx.store.insertObservations(observations);
|
|
34
|
-
const
|
|
34
|
+
const previous = await ctx.store.getSession(sessionId);
|
|
35
|
+
const summary = summarize(observations, previous?.summary);
|
|
35
36
|
await ctx.store.upsertSession({
|
|
36
37
|
id: sessionId,
|
|
37
38
|
project,
|
|
@@ -45,7 +46,7 @@ export async function flushSession(ctx, sessionId, project, transcriptPath) {
|
|
|
45
46
|
* Embeddings are an enhancement, never a precondition. A missing model must
|
|
46
47
|
* cost semantic recall, not the memory itself.
|
|
47
48
|
*/
|
|
48
|
-
async function
|
|
49
|
+
export async function embedObservations(ctx, observations) {
|
|
49
50
|
try {
|
|
50
51
|
const embedder = await ctx.embedder();
|
|
51
52
|
if (embedder.dimensions === 0)
|
|
@@ -53,8 +54,12 @@ async function embedAll(ctx, observations) {
|
|
|
53
54
|
const vectors = await embedder.embed(observations.map((obs) => `${obs.title}\n${obs.body}`));
|
|
54
55
|
observations.forEach((obs, index) => {
|
|
55
56
|
const vector = vectors[index];
|
|
56
|
-
if (vector && vector.length > 0)
|
|
57
|
+
if (vector && vector.length > 0) {
|
|
57
58
|
obs.embedding = vector;
|
|
59
|
+
// Stamped so search can refuse to compare across embedding spaces and
|
|
60
|
+
// `reembed` can tell which rows are already current.
|
|
61
|
+
obs.embedder = embedder.id;
|
|
62
|
+
}
|
|
58
63
|
});
|
|
59
64
|
}
|
|
60
65
|
catch (error) {
|
|
@@ -62,11 +67,37 @@ async function embedAll(ctx, observations) {
|
|
|
62
67
|
`${error instanceof Error ? error.message : String(error)}\n`);
|
|
63
68
|
}
|
|
64
69
|
}
|
|
65
|
-
/**
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
+
/** Least forgettable first. What a session is *for* is usually a decision. */
|
|
71
|
+
const KIND_RANK = {
|
|
72
|
+
decision: 0,
|
|
73
|
+
deadend: 1,
|
|
74
|
+
preference: 2,
|
|
75
|
+
bugfix: 3,
|
|
76
|
+
pattern: 4,
|
|
77
|
+
context: 5,
|
|
78
|
+
};
|
|
79
|
+
/**
|
|
80
|
+
* Recap of the session so far, and the only thing SessionStart injects.
|
|
81
|
+
*
|
|
82
|
+
* Taking the last three titles of the current flush was close to useless once
|
|
83
|
+
* capture became incremental: a flush usually carries a single turn, so the
|
|
84
|
+
* recap of an entire day's session was whatever happened to be typed last.
|
|
85
|
+
* Carrying the previous summary forward makes it cover the session, and
|
|
86
|
+
* ranking by kind keeps a decision over the build command that followed it.
|
|
87
|
+
*
|
|
88
|
+
* ponytail: first three win, so a decision made late in a long session does
|
|
89
|
+
* not displace an earlier one. Rank the session's stored observations instead
|
|
90
|
+
* if that turns out to matter.
|
|
91
|
+
*/
|
|
92
|
+
export function summarize(observations, previous) {
|
|
93
|
+
const kept = previous ? previous.split(' | ').filter(Boolean) : [];
|
|
94
|
+
for (const obs of [...observations].sort((a, b) => KIND_RANK[a.kind] - KIND_RANK[b.kind])) {
|
|
95
|
+
if (kept.length >= 3)
|
|
96
|
+
break;
|
|
97
|
+
if (!kept.includes(obs.title))
|
|
98
|
+
kept.push(obs.title);
|
|
99
|
+
}
|
|
100
|
+
return kept.join(' | ');
|
|
70
101
|
}
|
|
71
102
|
/**
|
|
72
103
|
* Per-session byte offset into the transcript.
|
|
@@ -100,3 +131,7 @@ function writeCursor(sessionId, offset) {
|
|
|
100
131
|
export function resetCursor(sessionId) {
|
|
101
132
|
writeCursor(sessionId, 0);
|
|
102
133
|
}
|
|
134
|
+
/** The session is over; its offset is scratch state nothing will read again. */
|
|
135
|
+
export function clearCursor(sessionId) {
|
|
136
|
+
rmSync(cursorPath(sessionId), { force: true });
|
|
137
|
+
}
|
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Who recorded an observation. Meaningless on a personal SQLite file and the
|
|
3
|
+
* whole point on a shared Postgres, where "decided X" is far weaker than
|
|
4
|
+
* "alex decided X". Captured now because it cannot be backfilled later.
|
|
5
|
+
*/
|
|
6
|
+
export declare function currentAuthor(): string | undefined;
|
|
1
7
|
/**
|
|
2
8
|
* Derives a stable id for an observation from its content.
|
|
3
9
|
*
|
package/dist/capture/identity.js
CHANGED
|
@@ -1,4 +1,18 @@
|
|
|
1
1
|
import { createHash } from 'node:crypto';
|
|
2
|
+
import { userInfo } from 'node:os';
|
|
3
|
+
/**
|
|
4
|
+
* Who recorded an observation. Meaningless on a personal SQLite file and the
|
|
5
|
+
* whole point on a shared Postgres, where "decided X" is far weaker than
|
|
6
|
+
* "alex decided X". Captured now because it cannot be backfilled later.
|
|
7
|
+
*/
|
|
8
|
+
export function currentAuthor() {
|
|
9
|
+
try {
|
|
10
|
+
return userInfo().username || undefined;
|
|
11
|
+
}
|
|
12
|
+
catch {
|
|
13
|
+
return undefined;
|
|
14
|
+
}
|
|
15
|
+
}
|
|
2
16
|
/**
|
|
3
17
|
* Derives a stable id for an observation from its content.
|
|
4
18
|
*
|
package/dist/capture/index.d.ts
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
export { classifyCommand } from './command.js';
|
|
2
|
-
export { observationId } from './identity.js';
|
|
3
|
-
export {
|
|
2
|
+
export { currentAuthor, observationId } from './identity.js';
|
|
3
|
+
export { remember } from './manual.js';
|
|
4
|
+
export type { RememberInput } from './manual.js';
|
|
5
|
+
export { readTranscript, transcriptPathFor, transcriptsFor } from './transcript.js';
|
|
4
6
|
export type { Turn, TranscriptRead } from './transcript.js';
|
|
5
7
|
export { observationsFromTurns } from './turn-extractor.js';
|
|
6
|
-
export { flushSession, resetCursor } from './flush.js';
|
|
8
|
+
export { flushSession, resetCursor, clearCursor, summarize, embedObservations, } from './flush.js';
|
|
7
9
|
export type { FlushResult } from './flush.js';
|
package/dist/capture/index.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
export { classifyCommand } from './command.js';
|
|
2
|
-
export { observationId } from './identity.js';
|
|
3
|
-
export {
|
|
2
|
+
export { currentAuthor, observationId } from './identity.js';
|
|
3
|
+
export { remember } from './manual.js';
|
|
4
|
+
export { readTranscript, transcriptPathFor, transcriptsFor } from './transcript.js';
|
|
4
5
|
export { observationsFromTurns } from './turn-extractor.js';
|
|
5
|
-
export { flushSession, resetCursor } from './flush.js';
|
|
6
|
+
export { flushSession, resetCursor, clearCursor, summarize, embedObservations, } from './flush.js';
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { RecallContext } from '../context.js';
|
|
2
|
+
import type { Observation, ObservationKind } from '../types.js';
|
|
3
|
+
export interface RememberInput {
|
|
4
|
+
project: string;
|
|
5
|
+
text: string;
|
|
6
|
+
kind?: ObservationKind;
|
|
7
|
+
files?: string[];
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Records something the user stated outright, rather than something inferred
|
|
11
|
+
* from a transcript.
|
|
12
|
+
*
|
|
13
|
+
* Everything else in this package derives memory from what happened. That
|
|
14
|
+
* cannot capture a rule, because a rule is not an event: "we always use pnpm
|
|
15
|
+
* here" leaves no edit and no command, so the extractor correctly drops it and
|
|
16
|
+
* the one thing worth remembering forever is the one thing never stored.
|
|
17
|
+
*
|
|
18
|
+
* Written through the same shape as captured observations, so it is searched,
|
|
19
|
+
* ranked, injected, exported and pruned identically.
|
|
20
|
+
*/
|
|
21
|
+
export declare function remember(ctx: RecallContext, input: RememberInput): Promise<Observation>;
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import { embedObservations } from './flush.js';
|
|
2
|
+
import { currentAuthor, observationId } from './identity.js';
|
|
3
|
+
/**
|
|
4
|
+
* Records something the user stated outright, rather than something inferred
|
|
5
|
+
* from a transcript.
|
|
6
|
+
*
|
|
7
|
+
* Everything else in this package derives memory from what happened. That
|
|
8
|
+
* cannot capture a rule, because a rule is not an event: "we always use pnpm
|
|
9
|
+
* here" leaves no edit and no command, so the extractor correctly drops it and
|
|
10
|
+
* the one thing worth remembering forever is the one thing never stored.
|
|
11
|
+
*
|
|
12
|
+
* Written through the same shape as captured observations, so it is searched,
|
|
13
|
+
* ranked, injected, exported and pruned identically.
|
|
14
|
+
*/
|
|
15
|
+
export async function remember(ctx, input) {
|
|
16
|
+
const createdAt = Date.now();
|
|
17
|
+
const author = currentAuthor();
|
|
18
|
+
const title = firstLine(input.text);
|
|
19
|
+
const observation = {
|
|
20
|
+
id: observationId('manual', createdAt, input.text),
|
|
21
|
+
sessionId: 'manual',
|
|
22
|
+
project: input.project,
|
|
23
|
+
kind: input.kind ?? 'preference',
|
|
24
|
+
title,
|
|
25
|
+
body: input.text,
|
|
26
|
+
files: input.files ?? [],
|
|
27
|
+
tags: ['manual'],
|
|
28
|
+
createdAt,
|
|
29
|
+
...(author ? { author } : {}),
|
|
30
|
+
};
|
|
31
|
+
await embedObservations(ctx, [observation]);
|
|
32
|
+
await ctx.store.insertObservations([observation]);
|
|
33
|
+
return observation;
|
|
34
|
+
}
|
|
35
|
+
const TITLE_MAX = 80;
|
|
36
|
+
function firstLine(text) {
|
|
37
|
+
const line = text.trim().split('\n')[0]?.trim() ?? '';
|
|
38
|
+
const clipped = line.length <= TITLE_MAX ? line : `${line.slice(0, TITLE_MAX)}...`;
|
|
39
|
+
return clipped.length > 0 ? clipped : 'Note';
|
|
40
|
+
}
|
|
@@ -39,3 +39,15 @@ export declare function readTranscript(path: string, fromOffset?: number): Trans
|
|
|
39
39
|
* the absolute path with separators and dots replaced by dashes.
|
|
40
40
|
*/
|
|
41
41
|
export declare function transcriptPathFor(project: string, sessionId: string): string;
|
|
42
|
+
/**
|
|
43
|
+
* Every transcript belonging to a project, including sessions started from one
|
|
44
|
+
* of its subdirectories.
|
|
45
|
+
*
|
|
46
|
+
* Claude Code files transcripts under the directory the agent was launched in,
|
|
47
|
+
* while memory is keyed on the repository root, and those differ the moment
|
|
48
|
+
* anyone runs the agent from `repo/frontend`. Candidate directories are found
|
|
49
|
+
* by prefix and then confirmed by the `cwd` each transcript records: the slug
|
|
50
|
+
* maps both `/` and `.` to `-`, so it cannot tell `~/app` from `~/app-extra`,
|
|
51
|
+
* and without the second step a flush would ingest a neighbour's history.
|
|
52
|
+
*/
|
|
53
|
+
export declare function transcriptsFor(project: string): string[];
|