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.
Files changed (40) hide show
  1. package/README.md +95 -243
  2. package/dist/capture/flush.d.ts +22 -0
  3. package/dist/capture/flush.js +45 -10
  4. package/dist/capture/identity.d.ts +6 -0
  5. package/dist/capture/identity.js +14 -0
  6. package/dist/capture/index.d.ts +5 -3
  7. package/dist/capture/index.js +4 -3
  8. package/dist/capture/manual.d.ts +21 -0
  9. package/dist/capture/manual.js +40 -0
  10. package/dist/capture/transcript.d.ts +12 -0
  11. package/dist/capture/transcript.js +69 -1
  12. package/dist/capture/turn-extractor.js +40 -8
  13. package/dist/cli/index.js +376 -30
  14. package/dist/cli/install.d.ts +15 -1
  15. package/dist/cli/install.js +127 -8
  16. package/dist/config/schema.d.ts +1 -0
  17. package/dist/config/schema.js +9 -1
  18. package/dist/context.js +24 -2
  19. package/dist/embed/builtin.js +3 -1
  20. package/dist/hooks/relevance.js +11 -4
  21. package/dist/hooks/session-end.js +2 -1
  22. package/dist/hooks/session-start.js +22 -3
  23. package/dist/mcp/server.js +56 -6
  24. package/dist/search/service.js +4 -1
  25. package/dist/store/adapter.d.ts +22 -6
  26. package/dist/store/adapter.js +10 -1
  27. package/dist/store/mongo/driver.d.ts +1 -0
  28. package/dist/store/mongo/index.d.ts +3 -2
  29. package/dist/store/mongo/index.js +57 -7
  30. package/dist/store/postgres/index.d.ts +22 -8
  31. package/dist/store/postgres/index.js +165 -21
  32. package/dist/store/sqlite/index.d.ts +3 -2
  33. package/dist/store/sqlite/index.js +112 -9
  34. package/dist/store/sqlite/schema.sql +4 -3
  35. package/dist/types.d.ts +28 -0
  36. package/dist/util/project.d.ts +9 -10
  37. package/dist/util/project.js +52 -13
  38. package/dist/util/vector.d.ts +11 -1
  39. package/dist/util/vector.js +14 -3
  40. package/package.json +2 -2
package/README.md CHANGED
@@ -5,301 +5,153 @@
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.
23
-
24
- ---
26
+ Restart Claude Code. That's it.
25
27
 
26
- ## What it actually remembers
28
+ ## How it works
27
29
 
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**:
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
- [decision] Chose WebSocket over polling for live order updates
33
-
34
- Asked: the plan was not good, the output was really bad, it should
35
- feel hand made not ai
36
-
37
- 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.
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
- 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.
46
+ Both steps are hooks, so they always run. Nothing depends on Claude deciding to
47
+ look something up.
50
48
 
51
- ## Recall is automatic, not left to the model
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
- | 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 |
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
- 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.
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
- Three things keep this cheap and quiet:
64
+ An example of one stored memory:
66
65
 
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.**
66
+ ```
67
+ [decision] Chose WebSocket over polling for live order updates
73
68
 
74
- Measured: about **350 tokens** on a prompt with relevant history, **0** on one
75
- without, 114ms of latency.
69
+ Asked: the order feed keeps dropping
76
70
 
77
- ## Works fully local, out of the box
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
- $ 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)
75
+ Files: src/ws/client.ts, src/ws/reconnect.ts
76
+ Ran: Test run: pnpm test
87
77
  ```
88
78
 
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.
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
- Only needed if you want memory shared across machines. The connection string
96
- picks the backend; nothing else changes.
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
- `cdb` is a shorter alias for all of the above.
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
- `--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
- ```
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
- 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.
125
+ ## Requirements
177
126
 
178
- ### Hybrid ranking
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
- 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.
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
- - 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.
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 end to end, touches nothing
295
- npm run bench # scaling curve
146
+ npm run try # simulate a session, touches nothing
296
147
  ```
297
148
 
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.
149
+ Releases publish from CI on a version tag:
301
150
 
302
- See [RELEASING.md](./RELEASING.md) for the publish process.
151
+ ```bash
152
+ npm version patch
153
+ git push --follow-tags
154
+ ```
303
155
 
304
156
  ## License
305
157
 
@@ -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;
@@ -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 embedAll(ctx, observations);
32
+ await embedObservations(ctx, observations);
33
33
  await ctx.store.insertObservations(observations);
34
- const summary = summarize(observations);
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 embedAll(ctx, observations) {
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
- /** Recap built from what was accomplished, not from file counts. */
66
- function summarize(observations) {
67
- const titles = observations.slice(-3).map((obs) => obs.title);
68
- const extra = observations.length - titles.length;
69
- return `${titles.join(' | ')}${extra > 0 ? ` (+${extra} earlier)` : ''}`;
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
  *
@@ -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
  *
@@ -1,7 +1,9 @@
1
1
  export { classifyCommand } from './command.js';
2
- export { observationId } from './identity.js';
3
- export { readTranscript, transcriptPathFor } from './transcript.js';
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';
@@ -1,5 +1,6 @@
1
1
  export { classifyCommand } from './command.js';
2
- export { observationId } from './identity.js';
3
- export { readTranscript, transcriptPathFor } from './transcript.js';
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[];