claude-db 0.5.3 → 0.5.4

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/CHANGELOG.md CHANGED
@@ -1,5 +1,35 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.5.4
4
+
5
+ ### Fixed
6
+
7
+ - **`reembed` could exhaust memory on a large database.** ([#7](https://github.com/Avijit07x/claude-db/issues/7))
8
+ Embedding walked the store 500 rows at a time and handed all 500 to a single
9
+ `embedder.embed()` call, which became one forward pass over 500 sequences in
10
+ the local model. Peak memory was set by that batch, so a database whose rows
11
+ were long enough went to swap and never came back. Embedding is now chunked by
12
+ `embeddings.batchSize`, so peak memory is a property of the chunk rather than
13
+ of the database: re-embedding 1,400 observations holds ~0.8 GB and takes the
14
+ same time per row as re-embedding 128. The chunking lives in
15
+ `embedObservations`, the one call every path routes through, so `flush`,
16
+ `seed` and `manual` capture are bounded by the same change — `seed` had the
17
+ identical ceiling and would have hit it on a large enough repo.
18
+
19
+ ### Added
20
+
21
+ - **`embeddings.batchSize`, default 8.** Measured on `all-MiniLM-L6-v2` with
22
+ worst-case 512-token observations, peak RSS runs 0.8 GB at 8, 1.3 GB at 16,
23
+ 2.4 GB at 32 and 4.5 GB at 64 — while wall-clock stays flat from 1 to 8,
24
+ because CPU inference is compute-bound and the token count is the same however
25
+ it is grouped. Batching buys no speed here and only costs memory, so the
26
+ default is deliberately small; lower it further if you are tight on RAM.
27
+
28
+ - **`reembed --project`.** `reembed` re-embedded every project on the machine
29
+ with no way to narrow it. On a database holding several projects that is the
30
+ difference between minutes and seconds, and the work skipped is work that
31
+ never has to be bounded. Without the flag the behaviour is unchanged.
32
+
3
33
  ## 0.5.3
4
34
 
5
35
  ### Fixed
package/README.md CHANGED
@@ -6,18 +6,32 @@
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
8
 
9
+ [Documentation](https://claude-db.vercel.app/docs) ·
10
+ [Quick start](https://claude-db.vercel.app/docs/quick-start) ·
11
+ [CLI reference](https://claude-db.vercel.app/docs/cli)
12
+
9
13
  ---
10
14
 
11
- ## What it is
15
+ ## Every session starts from zero
16
+
17
+ You spent an hour yesterday explaining why the store uses three adapters, which
18
+ approach you already tried and abandoned, and why that one function must not be
19
+ touched. Today Claude knows none of it. So you explain it again.
12
20
 
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.
21
+ claude-db fixes that, and the other half too. Claude re-derives your codebase
22
+ every time, grepping a name and opening files to work out what calls what.
15
23
 
16
- claude-db records those decisions as you work and gives them back
17
- automatically. Local by default, no account, no subscription.
24
+ ```console
25
+ $ claude-db search "why does capture read the transcript"
18
26
 
19
- It also maps your code: `claude-db scan` builds a graph of every symbol and how
20
- they connect, so "what breaks if I change this" is a query instead of a grep.
27
+ 83cf1246-eb14 decision 2026-08-19 Tested and written up.
28
+ …the old defaults prompt was now cut why does capture read the transcript…
29
+ 88fab24f-5e59 decision 2026-08-19 Finding 4's other half needs checking…
30
+ …cannot work: 0.029483 "why does capture read…" <- highly relevant…
31
+ ```
32
+
33
+ You never run that command. Claude gets the same context injected on every
34
+ prompt, so it walks in already knowing. Nothing leaves your machine.
21
35
 
22
36
  ## Install
23
37
 
@@ -28,27 +42,26 @@ cd your-project
28
42
  claude-db install --project
29
43
  ```
30
44
 
31
- Restart Claude Code. That's it — capture and recall are hooks, so they run
45
+ Restart Claude Code. That's it: capture and recall are hooks, so they run
32
46
  without being asked.
33
47
 
34
48
  `--project` scopes to one repo instead of every project on the machine. It
35
- writes `.claude/settings.local.json` and `.mcp.json` — add `.mcp.json` to your
49
+ writes `.claude/settings.local.json` and `.mcp.json`. Add `.mcp.json` to your
36
50
  `.gitignore`, since it holds a machine-specific path.
37
51
 
38
52
  ## Map your code
39
53
 
54
+ Memory fills itself as you work. The code graph needs one command:
55
+
40
56
  ```bash
41
57
  claude-db scan
42
-
43
- claude-db usages --mode explain resolveProject
44
- claude-db usages --mode path cmdScan observationId
45
58
  ```
46
59
 
47
- Claude gets the same four modes through MCP: `text` (a live grep, no scan
48
- needed), `usages`, `explain` and `path`. Answers re-check the working tree
49
- before replying, so they never report a line the source has moved past.
60
+ Claude then gets four modes through MCP: `text` (a live grep, works with no
61
+ scan at all), `usages`, `explain` and `path`. Re-running `scan` is cheap: it
62
+ hashes files and re-parses only what changed.
50
63
 
51
- Works out of the box on TypeScript, TSX, JavaScript, Python, Go and Rust — the
64
+ Works out of the box on TypeScript, TSX, JavaScript, Python, Go and Rust. The
52
65
  parser ships with the package, so there is nothing else to install.
53
66
 
54
67
  ## Use another database
@@ -64,33 +77,42 @@ claude-db use "postgres://user:pass@host:5432/memory"
64
77
  Install the driver you need (`npm install mongodb` or `pg`); neither ships by
65
78
  default.
66
79
 
80
+ ## With it, and without it
81
+
82
+ Asking _who defines and calls `closeObservations`_ by hand means a grep, then
83
+ opening three store adapters to see which hits are definitions. One `explain`
84
+ call answers it already classified: **2.1x cheaper**, measured across eight
85
+ real symbols in this repo.
86
+
87
+ Recall is the standing cost of ~180 tokens a prompt, skipped entirely on 28% of
88
+ prompts because the answer is already in context:
89
+
90
+ ```
91
+ every prompt costs 180 tokens of recall
92
+ every lookup refunds 597 tokens (1,115 by hand - 518 with)
93
+
94
+ so one lookup pays for 3.3 prompts of recall
95
+ ```
96
+
97
+ Check it on your own repo with `npm run bench:ab` and `npm run bench:tokens`
98
+ from a clone. [With and without](./docs/with-and-without.md) has every number,
99
+ including the symbols where plain grep wins.
100
+
67
101
  ## Commands
68
102
 
69
- `cdb` is a shorter alias for all of them.
70
-
71
- | Command | What it does |
72
- | ------------------------------------------------- | ------------------------------------------------------ |
73
- | `claude-db install [--project]` | Register hooks and the MCP server |
74
- | `claude-db uninstall [--project]` | Remove them, keeping your memory |
75
- | `claude-db status` | Is it wired up, and when did it last record anything |
76
- | `claude-db doctor [--deep]` | Resolved config; `--deep` proves a full round trip |
77
- | `claude-db search [--all] [--tag <name>] <query>` | Search this project's memory, or every project |
78
- | `claude-db remember [--key <name>] <text>` | Record a rule outright, e.g. "always use pnpm here" |
79
- | `claude-db forget <id>` | Delete specific observations by id |
80
- | `claude-db seed --from-git` | Fill a cold memory from this repo's history |
81
- | `claude-db scan [--force]` | Build the code graph for this repo |
82
- | `claude-db usages [--mode <m>] <symbol>` | What uses a symbol: live `git grep`, or the code graph |
83
- | `claude-db stats` | What this project's memory is made of |
84
- | `claude-db projects` | Every project with memory stored |
85
- | `claude-db merge [<path>]` | Move memory from an old project path onto this one |
86
- | `claude-db use <url>` | Switch database and verify it |
87
- | `claude-db sync <url>` | Two-way merge with another database |
88
- | `claude-db flush` | Re-ingest every transcript for this project |
89
- | `claude-db export [--all]` | Dump memory as JSONL, for backup or migration |
90
- | `claude-db import <file>` | Load a dump back in; safe to repeat |
91
- | `claude-db reembed` | Re-embed everything with the current model |
92
- | `claude-db prune --older-than <days>` | Delete old memory (dry run without `--yes`) |
93
- | `claude-db reset [--project] --yes` | Delete memory (dry run without `--yes`) |
103
+ `cdb` is a shorter alias for all of them. These are the ones you actually type:
104
+
105
+ | Command | What it does |
106
+ | ---------------------------------------- | ------------------------------------------------------ |
107
+ | `claude-db install [--project]` | Register hooks and the MCP server |
108
+ | `claude-db status` | Is it wired up, and when did it last record anything |
109
+ | `claude-db doctor [--deep]` | Resolved config; `--deep` proves a full round trip |
110
+ | `claude-db scan [--force]` | Build the code graph for this repo |
111
+ | `claude-db usages [--mode <m>] <symbol>` | What uses a symbol: live `git grep`, or the code graph |
112
+ | `claude-db use <url>` | Switch database and verify it |
113
+
114
+ Every other command, including `search`, `remember`, `seed`, `sync`, `export`,
115
+ `prune` and `reset`, is in the [CLI reference](https://claude-db.vercel.app/docs/cli).
94
116
 
95
117
  Install also adds a `/cdb-scan` skill: run it once on an existing project and
96
118
  Claude maps the codebase into memory, so search has something to find before
@@ -113,16 +135,23 @@ before anything is written.
113
135
 
114
136
  ## Documentation
115
137
 
116
- - [How it works](./docs/how-it-works.md) — what gets captured and injected, how
117
- the code graph is built and kept current, and how the database backends differ
118
- - [Changelog](./CHANGELOG.md)
138
+ **[claude-db.vercel.app/docs](https://claude-db.vercel.app/docs)** has the rest:
139
+ the [CLI reference](https://claude-db.vercel.app/docs/cli),
140
+ [MCP tools](https://claude-db.vercel.app/docs/mcp-tools),
141
+ [how it works](https://claude-db.vercel.app/docs/how-it-works),
142
+ [databases](https://claude-db.vercel.app/docs/databases) and
143
+ [troubleshooting](https://claude-db.vercel.app/docs/troubleshooting).
144
+
145
+ [Benchmarks](https://claude-db.vercel.app/docs/benchmarks) has every number,
146
+ including the symbols where plain grep wins. Releases are in the
147
+ [changelog](./CHANGELOG.md).
119
148
 
120
149
  ## Development
121
150
 
122
151
  ```bash
123
152
  npm install
124
153
  npm run build
125
- npm test # 263 checks
154
+ npm test # 326 checks
126
155
  npm run try # simulate a session, touches nothing
127
156
  npm run format
128
157
  ```
@@ -36,14 +36,22 @@ export async function embedObservations(ctx, observations) {
36
36
  const embedder = await ctx.embedder();
37
37
  if (embedder.dimensions === 0)
38
38
  return;
39
- const vectors = await embedder.embed(observations.map((obs) => `${obs.title}\n${obs.body}`));
40
- observations.forEach((obs, index) => {
41
- const vector = vectors[index];
42
- if (vector && vector.length > 0) {
43
- obs.embedding = vector;
44
- obs.embedder = embedder.id;
45
- }
46
- });
39
+ // ponytail: chunked because peak memory scales with the batch handed to one
40
+ // forward pass, not with the database. Measured on all-MiniLM-L6-v2, 512-token
41
+ // bodies: 8 -> 0.8GB, 16 -> 1.3GB, 32 -> 2.4GB, 64 -> 4.5GB, all at identical
42
+ // wall-clock. Batching buys nothing on CPU, so keep it small.
43
+ const size = ctx.config.embeddings.batchSize;
44
+ for (let start = 0; start < observations.length; start += size) {
45
+ const chunk = observations.slice(start, start + size);
46
+ const vectors = await embedder.embed(chunk.map((obs) => `${obs.title}\n${obs.body}`));
47
+ chunk.forEach((obs, index) => {
48
+ const vector = vectors[index];
49
+ if (vector && vector.length > 0) {
50
+ obs.embedding = vector;
51
+ obs.embedder = embedder.id;
52
+ }
53
+ });
54
+ }
47
55
  }
48
56
  catch (error) {
49
57
  process.stderr.write(`[claude-db] embedding skipped: ` +
@@ -6,4 +6,4 @@ export declare function eachObservation(ctx: RecallContext, filter: {
6
6
  export declare function cmdExport(argv: (string | undefined)[]): Promise<void>;
7
7
  export declare function cmdImport(path: string | undefined): Promise<void>;
8
8
  export declare function cmdPrune(argv: (string | undefined)[]): Promise<void>;
9
- export declare function cmdReembed(): Promise<void>;
9
+ export declare function cmdReembed(argv?: (string | undefined)[]): Promise<void>;
@@ -98,7 +98,8 @@ export async function cmdPrune(argv) {
98
98
  await ctx.close();
99
99
  }
100
100
  }
101
- export async function cmdReembed() {
101
+ export async function cmdReembed(argv = []) {
102
+ const scoped = argv.includes('--project') || argv.includes('-p');
102
103
  const base = loadConfig();
103
104
  const ctx = await createContext({ embeddings: { ...base.embeddings, timeoutMs: 0 } });
104
105
  try {
@@ -109,7 +110,8 @@ export async function cmdReembed() {
109
110
  }
110
111
  let updated = 0;
111
112
  let skipped = 0;
112
- const scanned = await eachObservation(ctx, {}, async (batch) => {
113
+ const filter = scoped ? { project: resolveProject(undefined) } : {};
114
+ const scanned = await eachObservation(ctx, filter, async (batch) => {
113
115
  const stale = batch.filter((obs) => obs.embedder !== embedder.id);
114
116
  skipped += batch.length - stale.length;
115
117
  if (stale.length === 0)
package/dist/cli/index.js CHANGED
@@ -57,7 +57,7 @@ async function run() {
57
57
  await cmdPrune(args);
58
58
  break;
59
59
  case 'reembed':
60
- await cmdReembed();
60
+ await cmdReembed(args);
61
61
  break;
62
62
  case 'stats':
63
63
  await cmdStats();
package/dist/cli/usage.js CHANGED
@@ -25,7 +25,7 @@ export function usage() {
25
25
  import <file.jsonl> Load a dump back in (safe to repeat)
26
26
  sync <url> [--yes] Two-way merge with another database
27
27
  update Install a newer compatible release now
28
- reembed Re-embed everything with the current model
28
+ reembed [--project] Re-embed with the current model
29
29
  prune --older-than <days> Delete old memory (dry run without --yes)
30
30
  reset [--project] --yes Delete stored memory (dry run without --yes)
31
31
 
@@ -1,7 +1,7 @@
1
1
  import { z } from 'zod';
2
2
  export declare const ConfigSchema: z.ZodObject<{
3
3
  database: z.ZodDefault<z.ZodString>;
4
- embeddings: z.ZodDefault<z.ZodObject<{
4
+ embeddings: z.ZodPrefault<z.ZodObject<{
5
5
  provider: z.ZodDefault<z.ZodEnum<{
6
6
  auto: "auto";
7
7
  local: "local";
@@ -10,6 +10,7 @@ export declare const ConfigSchema: z.ZodObject<{
10
10
  }>>;
11
11
  maxScanCandidates: z.ZodDefault<z.ZodNumber>;
12
12
  timeoutMs: z.ZodDefault<z.ZodNumber>;
13
+ batchSize: z.ZodDefault<z.ZodNumber>;
13
14
  }, z.core.$strip>>;
14
15
  updates: z.ZodDefault<z.ZodEnum<{
15
16
  auto: "auto";
@@ -6,8 +6,9 @@ export const ConfigSchema = z.object({
6
6
  provider: z.enum(['auto', 'local', 'builtin', 'none']).default('auto'),
7
7
  maxScanCandidates: z.number().int().positive().default(25000),
8
8
  timeoutMs: z.number().int().nonnegative().default(3000),
9
+ batchSize: z.number().int().positive().default(8),
9
10
  })
10
- .default({ provider: 'auto', maxScanCandidates: 25000, timeoutMs: 3000 }),
11
+ .prefault({}),
11
12
  updates: z.enum(['auto', 'notify', 'off']).default('notify'),
12
13
  capture: z
13
14
  .object({
@@ -6,7 +6,7 @@ graph stays honest.
6
6
 
7
7
  ## Capture
8
8
 
9
- Claude Code already writes every session to disk as JSONL — your prompts, its
9
+ Claude Code already writes every session to disk as JSONL: your prompts, its
10
10
  replies, every tool call. claude-db reads that file, so it captures **why** you
11
11
  did something, not just which files changed.
12
12
 
@@ -41,7 +41,7 @@ best match in full on each prompt. Roughly 350 tokens when something relevant
41
41
  exists, zero when it doesn't.
42
42
 
43
43
  **What search returns.** An id, kind, date, title and one line of the matching
44
- body — enough to tell two similarly-titled rows apart without expanding either.
44
+ body, enough to tell two similarly-titled rows apart without expanding either.
45
45
  Full bodies come only from `get_observations`, for ids you picked.
46
46
 
47
47
  One stored memory looks like this:
@@ -71,8 +71,8 @@ already landed, or a finished task would flicker back into the list every time
71
71
  a neighbouring line changed.
72
72
 
73
73
  `claude-db status` lists what is still open, and SessionStart injects the
74
- newest few. That is what lets a brand-new chat answer "what was I doing" —
75
- memory search ranks by relevance, and a prompt like "do the last task" contains
74
+ newest few. That is what lets a brand-new chat answer "what was I doing".
75
+ Memory search ranks by relevance, and a prompt like "do the last task" contains
76
76
  no words worth matching, so recency has to come from somewhere else.
77
77
 
78
78
  Rows captured before this existed default to `done`. Marking a whole existing
@@ -82,7 +82,7 @@ database unfinished would be worse than saying nothing.
82
82
 
83
83
  `claude-db install` copies two things to disk: the `/cdb-scan` skill, and a
84
84
  standing instruction block in `CLAUDE.local.md`. Claude Code only reads skills
85
- from `~/.claude/skills/`, so a copy has to exist there — but a copy drifts as
85
+ from `~/.claude/skills/`, so a copy has to exist there, but a copy drifts as
86
86
  soon as the package updates.
87
87
 
88
88
  The hooks are registered by absolute path into the installed package, so they
@@ -97,7 +97,7 @@ back, and anything `uninstall` removed stays removed.
97
97
  ## The code graph
98
98
 
99
99
  `claude-db scan` parses every supported source file and stores what it finds:
100
- each symbol, and each relationship between symbols — what calls what, what
100
+ each symbol, and each relationship between symbols: what calls what, what
101
101
  imports what, what extends what. Parsing is local and deterministic, costs no
102
102
  tokens, and takes about a second on a mid-size repository. A rescan only
103
103
  re-parses files whose contents changed.
@@ -117,7 +117,7 @@ Shortest path (4 hops):
117
117
  ```
118
118
 
119
119
  **Every edge carries its confidence.** `EXTRACTED` means the relationship was
120
- read literally out of the syntax tree — an import names its own target, so
120
+ read literally out of the syntax tree. An import names its own target, so
121
121
  nothing is guessed. `INFERRED` means the target was matched by name across
122
122
  files, which is wrong when two files export the same identifier, and carries a
123
123
  score saying how sure the match was. Name matching is the one guess this makes,
@@ -131,7 +131,7 @@ have been scanned, but correctness does not depend on it having run.
131
131
 
132
132
  Traversal is keyed on symbol id rather than name. Keying by name would merge
133
133
  every same-named symbol into one node, and a repository with a `run` in each
134
- test file would then grow shortcuts between unrelated code — making the
134
+ test file would then grow shortcuts between unrelated code, making the
135
135
  shortest path a route nothing can actually take.
136
136
 
137
137
  Languages: TypeScript, TSX, JavaScript, Python, Go and Rust. The parser is
@@ -141,8 +141,8 @@ nothing compiles at install and nothing else has to be installed.
141
141
  ## The `/cdb-scan` skill
142
142
 
143
143
  Installed alongside the hooks, it runs two passes: `claude-db scan` for the
144
- graph, then five written notes — stack, layout, conventions, workflows,
145
- architecture — stored under stable keys so a re-run updates them in place.
144
+ graph, then five written notes (stack, layout, conventions, workflows,
145
+ architecture) stored under stable keys so a re-run updates them in place.
146
146
 
147
147
  The graph records what the code _is_; the notes record why it is built that
148
148
  way. Those notes are tagged `inferred`, because they are Claude's reading of
@@ -154,7 +154,7 @@ database is testimony, and a search result must not blur the two.
154
154
  SQLite by default, at `~/.claude-memory/memory.db`. The connection string picks
155
155
  the backend, and `CLAUDE_DB_URL` overrides the config file.
156
156
 
157
- Search is hybrid — keyword plus vector — on all three backends. Ranking, fusion
157
+ Search is hybrid, keyword plus vector, on all three backends. Ranking, fusion
158
158
  and token budgeting live in `src/search` rather than in the adapters, so recall
159
159
  behaves identically no matter which database is plugged in; only retrieval cost
160
160
  changes. Memory is partitioned by project path, so one database serves every
@@ -179,5 +179,5 @@ Atlas indexes are not created by this tool. Add one by hand on the
179
179
  ```
180
180
 
181
181
  `numDimensions` is 256 for the builtin embedder, 384 once
182
- `@xenova/transformers` is installed. Without this index Mongo still works —
182
+ `@xenova/transformers` is installed. Without this index Mongo still works,
183
183
  vector search falls back to scoring candidates in process.
@@ -0,0 +1,123 @@
1
+ # With claude-db and without it
2
+
3
+ Does it actually save tokens? Here is the same work measured both ways, so you
4
+ can decide before you install.
5
+
6
+ Run `npm run bench:ab` from a clone to reproduce all of it on your own
7
+ codebase. Tokens are approximated at 4 characters each.
8
+
9
+ ## The short answer
10
+
11
+ **One lookup pays for about three prompts of recall.**
12
+
13
+ Recall costs ~180 tokens on every prompt. A symbol lookup saves ~600 tokens
14
+ against doing the same work by hand. Ask your codebase something once every few
15
+ prompts and you are ahead. Never ask it anything and you are paying for context
16
+ you did not use.
17
+
18
+ ## Looking up a symbol
19
+
20
+ The question is _who uses this, and how?_ Without claude-db that means a grep,
21
+ then opening the file it points into to see which hits are definitions, which
22
+ are calls, and which are noise. With it, one command returns the same answer
23
+ already classified.
24
+
25
+ Measured on eight real symbols in this repository:
26
+
27
+ ```
28
+ symbol WITH grep +read WITHOUT
29
+ ---------------------------------------------------------
30
+ isSearchable 1734 1228 1153 2381
31
+ observationsFromTurns 2042 2362 7529 9891
32
+ closeObservations 3209 1354 6597 7951
33
+ flushSession 1786 818 4442 5260
34
+ refreshGraph 2640 1143 961 2104
35
+ observationId 2020 2418 572 2990
36
+ toSnippet 1994 1789 704 2493
37
+ openWork 1166 1294 1305 2599
38
+ ---------------------------------------------------------
39
+ TOTAL chars 16591 35669
40
+ TOTAL tokens 4148 8917
41
+ 2.1x
42
+ ```
43
+
44
+ **518 tokens per lookup instead of 1,115.**
45
+
46
+ The average hides something useful. `refreshGraph` and `observationId` are
47
+ cheaper _without_ claude-db, because their defining files are small and grep
48
+ answers them fine. `observationsFromTurns` and `closeObservations` are four to
49
+ five times cheaper with it, because answering those by hand means reading a
50
+ 200-line file, or three of them spread across different modules.
51
+
52
+ The win concentrates on questions that span files, which is also where a wrong
53
+ answer costs you the most.
54
+
55
+ ## Asking why something is the way it is
56
+
57
+ Some questions have no grep equivalent at all. _Why does capture read the
58
+ transcript instead of hooking the tools?_ leaves no trace in the code. The
59
+ closest substitute is `git log -S` plus reading diffs, and that tells you what
60
+ changed, never why.
61
+
62
+ Measured against that substitute the two come out roughly level, but they are
63
+ not answering the same question. The real cost without stored memory is
64
+ explaining it to Claude again yourself, which no benchmark can price.
65
+
66
+ ## What it costs
67
+
68
+ Recall arrives automatically on every prompt, so it has a standing cost. What
69
+ arrives is index lines, never full bodies: an id, a kind, a date, a title, and
70
+ the line that matched. Claude pulls a full body only when a title earns it.
71
+
72
+ ```
73
+ every prompt costs 180 tokens of recall
74
+ every lookup refunds 597 tokens (1,115 by hand, 518 with)
75
+
76
+ so one lookup pays for 3.3 prompts of recall
77
+ ```
78
+
79
+ On 28% of prompts nothing is injected at all, because everything matching is
80
+ already in the conversation.
81
+
82
+ ```
83
+ a session of recall costs lookups to break even
84
+ ------------------------------------------------------
85
+ 1 prompt 180 0.3
86
+ 5 prompts 900 1.5
87
+ 10 prompts 1,800 3.0
88
+ 20 prompts 3,600 6.0
89
+ 60 prompts 10,800 18.1
90
+ ```
91
+
92
+ ## When it does not pay off
93
+
94
+ Worth saying plainly, because it is a real case: a session where you never ask
95
+ anything about the codebase pays for recall and gets nothing back for it.
96
+
97
+ Three things push you the other way. Refactoring, where every rename wants a
98
+ blast-radius check. Returning to a project after a break, where the stored
99
+ reasoning is the point. And any codebase large enough that "who calls this"
100
+ means opening several files rather than one.
101
+
102
+ If your sessions are short and mostly conversational, turn the per-prompt
103
+ recall off and keep the code graph:
104
+
105
+ ```json
106
+ { "inject": { "perPrompt": false } }
107
+ ```
108
+
109
+ Session-start context still arrives, lookups still work, and the standing cost
110
+ goes to zero.
111
+
112
+ ## Reproducing this
113
+
114
+ ```bash
115
+ git clone https://github.com/Avijit07x/claude-db && cd claude-db
116
+ npm install && npm run build
117
+
118
+ npm run bench:ab # this document, on your own repo
119
+ npm run bench:tokens # where the injected tokens go
120
+ ```
121
+
122
+ The grep side excludes markdown, so both sides see the same code rather than
123
+ counting prose that happens to mention a symbol name.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-db",
3
- "version": "0.5.3",
3
+ "version": "0.5.4",
4
4
  "description": "Persistent memory for Claude Code. 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",
@@ -35,6 +35,8 @@
35
35
  "local": "node scripts/local.mjs",
36
36
  "try": "node scripts/try.mjs",
37
37
  "bench": "node scripts/bench.mjs",
38
+ "bench:tokens": "node scripts/bench-tokens.mjs",
39
+ "bench:ab": "node scripts/bench-ab.mjs",
38
40
  "postinstall": "node -e \"const v=process.versions.node.split('.').map(Number); if(v[0]<22||(v[0]===22&&v[1]<5)){console.error('\\n claude-db needs Node >= 22.5 (node:sqlite is builtin from there). You have '+process.versions.node+'.\\n');process.exit(1)}\"",
39
41
  "prepublishOnly": "npm run build && npm test",
40
42
  "format": "prettier --write .",
@@ -1,391 +0,0 @@
1
- # Memory MCP — test findings
2
-
3
- Tested 2026-08-19 against `/Users/user/Personal/claude-db` at `654a854`, using the
4
- installed MCP server plus the `claude-db` CLI. All six tools exercised except the
5
- `remember` / `forget` write path.
6
-
7
- Four findings: one total feature outage, one that returns confidently wrong
8
- answers, two that erode trust in output the caller cannot cross-check.
9
-
10
- **All four are fixed in 0.5.3**, each with a regression test. The mechanisms are
11
- kept below because they explain _why_ the graph was wrong, which the changelog
12
- cannot. One correction: the fix proposed for finding 4 was backwards — see the
13
- note at the end of that section.
14
-
15
- | # | Tool | Severity | Summary |
16
- | --- | ---------------------------- | ----------------- | ----------------------------------------------------------------------- |
17
- | 1 | `timeline` | **Broken** | Cannot accept the ids the MCP itself displays |
18
- | 2 | `find_usages --mode usages` | **Wrong answers** | `Class.method()` is not counted as a reference to `Class` |
19
- | 3 | `find_usages --mode usages` | Misleading | Callers inside anonymous functions are named after a variable or a file |
20
- | 4 | `find_usages --mode explain` | Noise | Same call listed twice; destructuring patterns listed as symbols |
21
-
22
- ## What works
23
-
24
- No changes needed here, recorded so a later pass does not re-test it.
25
-
26
- - **`search`** — snippet, `kind` filter, relevance ordering and short ids all behave.
27
- The layer-1 gaps raised in observation `fc7fc5c9-e078` (matched snippet, `chars`
28
- cap, relevance score) have all shipped.
29
- - **`get_observations`** — batches, accepts short ids, honours `chars`, marks truncation.
30
- - **`find_usages --mode text`** — live grep, never stale, `[definition?]` marker and
31
- `path` scoping all correct.
32
- - **`find_usages --mode explain`** — rich and useful, modulo finding 4.
33
-
34
- ---
35
-
36
- ## 1. `timeline` cannot accept the ids the MCP shows
37
-
38
- **Severity: broken.** Not degraded — the tool cannot succeed through the documented
39
- workflow, because the only ids a caller ever sees are ids it rejects.
40
-
41
- ### The mechanism
42
-
43
- `src/mcp/render.ts:10` renders every search row's id through `toShortId()`, which
44
- slices a 36-char UUID down to 13 characters:
45
-
46
- ```ts
47
- const head = `${toShortId(entry.id)} ${entry.kind} ${date} ${entry.title}`;
48
- ```
49
-
50
- `src/hooks/relevance.ts:18,27` does the same for the memory injected at session
51
- start. So a short id is the _only_ form of an id that reaches the model.
52
-
53
- `get_observations` compensates — it routes ids through `partitionIds()`
54
- (`src/util/shortid.ts:11`) and matches short ones with a `GLOB prefix*`.
55
-
56
- `timeline` does not. Its anchor lookup is an exact match in all three adapters:
57
-
58
- - `src/store/sqlite/search.ts:98` — `SELECT project, created_at FROM observations WHERE id = ?`
59
- - `src/store/postgres/observations.ts:144` — `... WHERE id = $1`
60
- - `src/store/mongo/search.ts:39` — `findOne({ _id: query.observationId })`
61
-
62
- Every one is followed by `if (!anchor) return []`, so the failure surfaces as the
63
- empty, plausible-looking message **"No matching observations."** rather than an error.
64
-
65
- ### Reproduce — via the MCP tools
66
-
67
- ```
68
- search({ query: "turn extractor", limit: 5 })
69
- -> 62bdadf3-d472 decision 08-15 The instruction only fires ...
70
-
71
- get_observations({ ids: ["62bdadf3-d472"] })
72
- -> returns the full observation OK
73
-
74
- timeline({ observation_id: "62bdadf3-d472", before: 2, after: 2 })
75
- -> "No matching observations." BUG
76
- ```
77
-
78
- ### Reproduce — as a script
79
-
80
- There is no `timeline` CLI subcommand (`src/cli/index.ts` registers 22 commands;
81
- `timeline` is MCP-only), so this drives the library directly. Save at the repo root
82
- (the relative imports resolve from the file, not the cwd) and run after `npm run build`:
83
-
84
- ```js
85
- // repro-timeline.mjs
86
- import { createContext } from './dist/context.js';
87
- import { toShortId } from './dist/util/shortid.js';
88
-
89
- const ctx = await createContext();
90
- try {
91
- const [hit] = await ctx.search.search({
92
- text: 'turn extractor',
93
- project: '/Users/user/Personal/claude-db',
94
- limit: 1,
95
- });
96
- if (!hit) {
97
- console.log('no observations stored');
98
- process.exit(0);
99
- }
100
-
101
- const full = hit.id;
102
- const short = toShortId(full); // exactly what src/mcp/render.ts:10 shows the model
103
-
104
- console.log('full id :', full);
105
- console.log('id the MCP shows :', short);
106
- console.log(
107
- 'get_observations(short) ->',
108
- (await ctx.search.getObservations([short])).length,
109
- 'row(s) OK',
110
- );
111
- console.log(
112
- 'timeline(full) ->',
113
- (await ctx.search.timeline({ observationId: full, before: 2, after: 2 })).length,
114
- 'row(s) OK',
115
- );
116
- console.log(
117
- 'timeline(short) ->',
118
- (await ctx.search.timeline({ observationId: short, before: 2, after: 2 })).length,
119
- 'row(s) <-- BUG',
120
- );
121
- } finally {
122
- await ctx.close();
123
- }
124
- ```
125
-
126
- Observed:
127
-
128
- ```
129
- full id : 9fff1197-19dc-a62c-16ad-0699071b2191
130
- id the MCP shows : 9fff1197-19dc
131
-
132
- get_observations(short) -> 1 row(s) OK
133
- timeline(full) -> 5 row(s) OK
134
- timeline(short) -> 0 row(s) <-- BUG
135
- ```
136
-
137
- ### Why it was never caught
138
-
139
- The single test at `scripts/smoke/retrieval.mjs:60` passes a full id read straight
140
- back out of the store:
141
-
142
- ```js
143
- const tl = await search.timeline({ observationId: observations[2].id, before: 2, after: 2 });
144
- ```
145
-
146
- That is the one input shape no real caller ever produces. The test passes and the
147
- feature has never worked over MCP.
148
-
149
- ### Fix
150
-
151
- Resolve the id at the chokepoint. `src/search/service.ts:49` is the single point
152
- both the MCP server (`src/mcp/server.ts:129`) and any future CLI route through, and
153
- `getObservations` already implements correct prefix matching in all three adapters:
154
-
155
- ```ts
156
- async timeline(query: TimelineQuery): Promise<ObservationIndexEntry[]> {
157
- const [anchor] = await this.store.getObservations([query.observationId]);
158
- if (!anchor) return [];
159
- return this.store.timeline({ ...query, observationId: anchor.id });
160
- }
161
- ```
162
-
163
- One file, three adapters fixed, no adapter-specific SQL touched. Then change
164
- `scripts/smoke/retrieval.mjs:60` to feed `toShortId(observations[2].id)` so the
165
- regression cannot come back.
166
-
167
- ---
168
-
169
- ## 2. `Class.method()` does not register as a reference to `Class`
170
-
171
- **Severity: wrong answers.** This is worse than finding 1, because finding 1 fails
172
- loudly-ish and this one silently under-reports a blast radius.
173
-
174
- ### The mechanism
175
-
176
- A member call `X.method()` creates a graph edge to `method` (and to the qualified
177
- name `X.method`), but never to `X`. So a class only ever constructed through a
178
- static factory looks unreferenced.
179
-
180
- This is precisely how every store backend in this project is wired, which makes it
181
- the worst possible blind spot here: the pluggable-store seam is the product's
182
- headline feature ("Bring your own database: SQLite, MongoDB or Postgres").
183
-
184
- ### Reproduce
185
-
186
- ```sh
187
- node dist/cli/index.js usages --mode usages SqliteStore
188
- node dist/cli/index.js usages --mode usages PostgresStore
189
- ```
190
-
191
- Observed:
192
-
193
- ```
194
- SqliteStore [class]
195
- Source: src/store/sqlite/index.ts:40
196
- Referenced by (1):
197
- <-- create [calls] [EXTRACTED] src/store/sqlite/index.ts:48
198
- ```
199
-
200
- The single reference is `new SqliteStore(...)` _inside the class's own static
201
- `create`_. The real external caller is missed:
202
-
203
- ```sh
204
- grep -rn "SqliteStore" src/
205
- # src/store/index.ts:22: const { SqliteStore } = await import('./sqlite/index.js');
206
- # src/store/index.ts:23: return SqliteStore.create(uri); <-- never appears in the graph
207
- ```
208
-
209
- So `find_usages --mode usages SqliteStore` answers **"nothing but itself"** when the
210
- truth is that this line is the only thing that ever constructs it. Rename or delete
211
- the class on that basis and the store factory breaks.
212
-
213
- ### Not the dynamic import
214
-
215
- Worth recording, because it is the obvious wrong diagnosis. Dynamic `await import()`
216
- is handled fine — both of these are found:
217
-
218
- ```sh
219
- node dist/cli/index.js usages --mode usages LocalEmbedder
220
- # <-- loadLocal src/embed/index.ts:26 (behind `await import('./local.js')`)
221
- node dist/cli/index.js usages --mode usages refreshGraph
222
- # <-- refreshGraphQuietly src/hooks/session-start.ts:24 (behind `await import(...)`)
223
- ```
224
-
225
- The discriminator is the call shape, not the import:
226
-
227
- | Call site | Shape | Found? |
228
- | ------------------------------- | ------------------------- | ------ |
229
- | `src/embed/index.ts:26` | `new LocalEmbedder()` | yes |
230
- | `src/hooks/session-start.ts:24` | `refreshGraph(...)` | yes |
231
- | `src/store/index.ts:23` | `SqliteStore.create(uri)` | **no** |
232
-
233
- Bare constructor and bare call resolve; member call does not.
234
-
235
- ### Fix
236
-
237
- When extracting a call whose callee is a member expression, emit an edge to the
238
- object as well as to the property — `SqliteStore.create(uri)` should yield a
239
- `calls` edge to `create` _and_ a `references` edge to `SqliteStore`. Confirm against
240
- all three store classes, since all three use the same `X.create(uri)` shape.
241
-
242
- ---
243
-
244
- ## 3. Callers inside anonymous functions are named after a variable or a file
245
-
246
- **Severity: misleading, not wrong.** The file and line are correct; the caller
247
- _name_ is not a caller.
248
-
249
- ### Reproduce
250
-
251
- ```sh
252
- node dist/cli/index.js usages --mode usages createContext
253
- ```
254
-
255
- Observed:
256
-
257
- ```
258
- Referenced by (23):
259
- <-- cmdDoctor src/cli/commands/doctor.ts:12 correct
260
- <-- ctx src/hooks/session-end.ts:20 variable name
261
- <-- ctx src/hooks/session-start.ts:54 variable name
262
- <-- ctx src/hooks/user-prompt.ts:18 variable name
263
- <-- ctx src/mcp/server.ts:30 variable name
264
- ```
265
-
266
- And on another symbol, the degradation goes one step further, to a filename:
267
-
268
- ```sh
269
- node dist/cli/index.js usages --mode usages flushSession
270
- ```
271
-
272
- ```
273
- <-- cmdFlush src/cli/commands/maintain.ts:56 correct
274
- <-- result src/hooks/session-end.ts:23 assignment target
275
- <-- src/hooks/user-prompt.ts src/hooks/user-prompt.ts:23 filename
276
- ```
277
-
278
- ### The mechanism
279
-
280
- Attribution walks up to the nearest **named** enclosing function. When there is one
281
- it is correct:
282
-
283
- ```ts
284
- // src/cli/commands/doctor.ts:10 -> attributed to cmdDoctor, correct
285
- export async function cmdDoctor(argv: (string | undefined)[]): Promise<void> {
286
- const ctx = await createContext({ ... });
287
- ```
288
-
289
- When the enclosing scope is an anonymous callback there is no name to find, so it
290
- falls back to the assigned variable, and with no assignment at all, to the file:
291
-
292
- ```ts
293
- // src/hooks/session-end.ts:14 -> anonymous arrow, no name to walk up to
294
- await runHook(async () => {
295
- const ctx = await createContext(); // :20 -> attributed to `ctx`
296
- const result = await flushSession(...); // :23 -> attributed to `result`
297
- });
298
-
299
- // src/hooks/user-prompt.ts:23 -> no assignment either
300
- await flushSession(ctx, sessionId, project, payload.transcript_path);
301
- ```
302
-
303
- Every hook entry point in this codebase is an anonymous callback passed to
304
- `runHook`, so the four most important call sites in the project — the actual
305
- process entry points — are exactly the ones with meaningless caller names.
306
-
307
- ### Fix
308
-
309
- When no named enclosing function exists, fall back to the enclosing _call_ being
310
- passed to (`runHook`) or to a `file:scope` label, rather than to whatever binding
311
- happens to be nearest. `<-- runHook` or `<-- session-end:hook` would both be honest;
312
- `<-- ctx` is not.
313
-
314
- ---
315
-
316
- ## 4. `explain` lists the same call twice and lists non-symbols
317
-
318
- **Severity: noise.** Inflates edge counts and makes the output harder to scan.
319
-
320
- ### Reproduce
321
-
322
- ```sh
323
- node dist/cli/index.js usages --mode explain flushSession
324
- ```
325
-
326
- Observed — one call, two rows, twice over:
327
-
328
- ```
329
- --> ctx.store.insertObservations [calls] [EXTRACTED] src/capture/flush.ts:39
330
- --> insertObservations [calls] [INFERRED 0.85] src/capture/flush.ts:39 same call
331
- --> Date.now [calls] [EXTRACTED] src/capture/flush.ts:46
332
- --> now [calls] [INFERRED 0.85] src/capture/flush.ts:46 same call
333
- ```
334
-
335
- Same file, same line, same call — counted once as the qualified member expression
336
- and again as a lower-confidence bare-name inference. `ctx.store.getSession` /
337
- `getSession` and `ctx.store.upsertSession` / `upsertSession` duplicate the same way.
338
-
339
- Separately, destructuring patterns are stored as symbol names:
340
-
341
- ```
342
- --> { turns, nextOffset } [defines] [EXTRACTED] src/capture/flush.ts:25
343
- ```
344
-
345
- Between them these inflate the reported `Reaches (24)` to roughly 18 genuine edges.
346
-
347
- ### Fix — as shipped, and why not as proposed
348
-
349
- The proposal below was to drop the INFERRED row because "the qualified name is
350
- strictly better information". Checked before applying:
351
-
352
- ```
353
- EXTRACTED ctx.store.insertObservations resolves to a symbol: no
354
- INFERRED insertObservations resolves to a symbol: YES
355
- ```
356
-
357
- Nothing defines a symbol named `ctx.store.insertObservations`, so the qualified
358
- row is a dead label and the bare row is the only traversable one. Dropping it
359
- would have severed every `path` crossing a method call. 0.5.3 **merges** the
360
- pair — qualified name kept for reading, resolved id adopted for traversal.
361
-
362
- Original proposal, kept for the record:
363
-
364
- - Drop an INFERRED edge when an EXTRACTED edge already exists for the same
365
- `(file, line, target)`. The qualified name is strictly better information.
366
- - Expand a destructuring pattern into one `defines` edge per bound name
367
- (`turns`, `nextOffset`), or skip it — storing the pattern source text as a symbol
368
- helps nobody.
369
-
370
- ---
371
-
372
- ## Suggested order
373
-
374
- 1. **Finding 1** — smallest fix (~6 lines, one file), restores a tool that has never worked over MCP.
375
- 2. **Finding 2** — quietly wrong blast-radius answers are more dangerous than no answer; a rename based on this output breaks the store factory.
376
- 3. **Findings 3 and 4** — cosmetic individually, but together they are most of what makes graph output hard to trust when you cannot cross-check it.
377
-
378
- ## Not covered
379
-
380
- `remember` and `forget` were not exercised, since both write to the live memory
381
- database and `forget` is irreversible by its own contract. Worth a round-trip test
382
- against a scratch database before the next release.
383
-
384
- ---
385
-
386
- ## See also
387
-
388
- [token-economics.md](./token-economics.md) — measured token cost of this MCP,
389
- where it is spent without being asked, and four changes that cut it. Findings 1-4
390
- above are also token findings: each one is a reason to re-verify output by hand,
391
- and hand-verification is where the tokens go.
@@ -1,216 +0,0 @@
1
- # Memory MCP — token economics
2
-
3
- Measured 2026-08-19 on this session's own transcript
4
- (`~/.claude/projects/-Users-user-Personal-claude-db/b7603c72….jsonl`), so these are
5
- observed numbers rather than estimates. Token figures are `chars / 4`.
6
-
7
- Companion to [mcp-findings.md](./mcp-findings.md), which covers the four
8
- correctness bugs. The last section here explains why those two documents are the
9
- same problem.
10
-
11
- ## Summary
12
-
13
- | | Change | Saving | Status |
14
- | --- | ---------------------------------------------------- | ------------------------------ | -------------------------------------------- |
15
- | 0 | Skip observations the session has already been shown | **56% of injection, measured** | shipped 0.5.3 |
16
- | 1 | Gate injection on a `minScore` threshold | — | **cannot work as specified, see below** |
17
- | 2 | Default `expandTop: 0`, render the snippet instead | **67% of the block, measured** | shipped 0.5.3 |
18
- | 3 | Drop duplicate graph edges | 13% of every `explain` | shipped 0.5.3, **in the opposite direction** |
19
- | 4 | `get_observations` default `chars` 2000 → ~800 | priciest call, 539 avg | open |
20
-
21
- Both **0** and **2** shipped in 0.5.3. Measured on four real prompts:
22
-
23
- ```
24
- 1499 -> 520 "so now how we are saving tokens"
25
- 1604 -> 577 "why does capture read the transcript"
26
- 1541 -> 510 "postgres status column bug"
27
- 1596 -> 480 "fix the compaction summary bug"
28
- ----------------------------------------------
29
- 6240 -> 2087 67% cut
30
- ```
31
-
32
- The index line now carries the matched snippet (110 chars, capped) in place of
33
- the full body (900), so the block still shows _why_ something matched and still
34
- names the id to expand. One caveat found while shipping it: existing installs
35
- write every config value to disk, so changing a schema default reaches nobody
36
- who already installed. A saved `inject` block still holding both old defaults
37
- exactly is now treated as untouched.
38
-
39
- ### Cross-session numbers
40
-
41
- The single-session figures below are a small sample. Replaying all 25 transcripts
42
- for this project (`node scripts/bench-tokens.mjs`):
43
-
44
- ```
45
- project-memory 51x 20,267 chars avg 397
46
- recalled-memory 142x 166,325 chars avg 1,171
47
- TOTAL 193x 186,592 chars ~46,600 tokens
48
- ~1,866 tokens/session (pre-0.5.3)
49
- ```
50
-
51
- Of the per-prompt block, **56% was content the conversation already held** —
52
- the same observations re-injected prompt after prompt, because the best match
53
- for one prompt is usually the best match for the next. Replaying the 0.5.3
54
- filter over the same history: 39 of 141 blocks suppressed entirely, 94,944 chars
55
- saved, per-session cost `1,866 -> ~940`.
56
-
57
- ## Where the tokens went
58
-
59
- 53 tool calls, ~9,638 tokens of tool results:
60
-
61
- | Tool | Calls | Total tok | Avg tok/call |
62
- | ------------------ | ----: | --------: | -----------: |
63
- | Bash | 33 | 5,351 | 162 |
64
- | `find_usages` | 11 | 2,053 | 187 |
65
- | `get_observations` | 3 | 1,618 | **539** |
66
- | `search` | 3 | 604 | 201 |
67
- | `timeline` | 2 | 13 | 6 |
68
-
69
- Memory MCP was 19 of 53 calls (35.8%). That number is not representative — testing
70
- the MCP _was_ the task. The prior measurement in observation `3f97c5fc-89bd` found
71
- **6 of 564 calls (1.1%)** on a normal working session, against 148 hand-run greps.
72
- Treat 1.1% as the realistic baseline and 35.8% as a ceiling.
73
-
74
- ## The largest cost is the injection nobody asked for
75
-
76
- Per-call costs above are modest. The bigger line item is what the tool spends
77
- **without being called**:
78
-
79
- ```
80
- <recalled-memory> injections : 9
81
- total : ~3,589 tokens
82
- average : ~399 tokens per prompt
83
- ```
84
-
85
- That is ~84% of what all 19 explicit MCP calls cost combined, spent automatically.
86
-
87
- **How much of it was used.** Four observations were expanded this session:
88
- `62bdadf3`, `3df47f53`, `fc7fc5c9` came from searches deliberately run; only
89
- `3f97c5fc` came from an injection. So **1 of 9 injections (~11%) produced context
90
- that was actually used** — roughly 3,190 tokens spent to deliver ~400 useful ones.
91
-
92
- ### Why: there is no relevance gate
93
-
94
- `src/hooks/user-prompt.ts:26-44` filters on prompt shape and on
95
- already-shown ids, and never on score:
96
-
97
- ```ts
98
- if (!ctx.config.inject.perPrompt || !isSearchable(prompt)) return;
99
- const shown = readShown(sessionId);
100
- const found = await ctx.search.search({ text: prompt, project, limit: ... });
101
- const entries = found.filter((entry) => !shown.has(entry.id));
102
- if (entries.length === 0) return;
103
- const toExpand = entries.slice(0, ctx.config.inject.expandTop);
104
- ```
105
-
106
- `entry.score` is never consulted. Whatever fuse ranking returns gets injected, and
107
- the top hit gets its body expanded, however weak the match. Prompts like
108
- _"write these in a md file"_ still retrieve something and still pay full price.
109
-
110
- Defaults (`src/config/schema.ts:30-33`) put the ceiling at ~1,400 chars ≈ 350 tokens
111
- per prompt, which matches the measured 399:
112
-
113
- ```ts
114
- promptResults: 4; // index lines retrieved
115
- promptMaxChars: 500; // budget for those lines
116
- expandTop: 1; // bodies fully expanded
117
- expandMaxChars: 900; // chars per expanded body
118
- ```
119
-
120
- ### The `shown` dedup makes quality fall over a session
121
-
122
- _(This critique lands. It is the strongest argument for pairing the dedup with a
123
- real relevance gate — see 1 below for why the obvious gate does not work.)_
124
-
125
- `entries.filter((entry) => !shown.has(entry.id))` excludes anything already injected.
126
- Once the genuinely relevant observations have been shown, later prompts necessarily
127
- inject **weaker** matches — while the token cost stays flat. The longer the session,
128
- the worse the value, which is the opposite of what you want.
129
-
130
- ## Savings, in order of size
131
-
132
- **1. Gate injection on score — does not work as written.** The instinct is right
133
- and the saving would be real, but `entry.score` cannot carry the threshold.
134
-
135
- `src/search/rank.ts:11` fuses with RRF, whose contribution is `1 / (60 + rank)` —
136
- a function of **rank position only**, never of match quality. There is always a
137
- rank 1, so the top hit always scores about `1/61` no matter how bad it is.
138
-
139
- Measured, same database, `limit: 4`:
140
-
141
- ```
142
- 0.029483 "why does capture read the transcript" <- highly relevant
143
- 0.029787 "write these in a md file" <- irrelevant, scores HIGHER
144
- 0.031535 "postgres status column bug" <- relevant
145
- 0.000000 "zqxjv wombat parasol ngmi" <- no hits at all
146
- ```
147
-
148
- The irrelevant prompt outscores the relevant one. Any `minScore` on this number
149
- keeps the junk and drops the good, or suppresses everything. The one case it
150
- does handle — total nonsense — already self-suppresses by returning zero rows.
151
-
152
- A working gate has to read a signal that _is_ a relevance measure: the
153
- pre-fusion bm25 or cosine score, or plain term overlap between the prompt and
154
- the matched title. `src/search/service.ts:43` already thresholds vector
155
- candidates on `embedder.minRelevance`, which is a real cosine cutoff — threading
156
- that signal through the fuse is the shape of the fix. Calibration is the work;
157
- the config knob is the easy part.
158
-
159
- **2. Make `expandTop: 0` the default.** The expanded body is the bulk of the 399
160
- (up to 900 of ~1,400 chars). The index line alone — id, kind, date, title, snippet —
161
- is enough to decide whether to call `get_observations`, which is exactly the
162
- three-layer design the tool already documents. Expanding by default pre-pays layer 3
163
- on every prompt for a 1-in-9 chance of needing it. Roughly **halves** injection cost
164
- on its own, and unlike (1) it is a one-line config change.
165
-
166
- **3. Duplicate graph edges — fixed, but not by dropping the INFERRED row.**
167
- Finding 4 above, measured:
168
-
169
- ```
170
- explain flushSession : 523 tokens
171
- duplicate INFERRED-0.85 rows: 4 rows, 70 tokens = 13% of output
172
- ```
173
-
174
- 13% of every `explain` result is the same call listed a second time under a
175
- lower-confidence bare name. The waste is real; the proposed fix was backwards.
176
-
177
- Checking which of the pair actually resolves:
178
-
179
- ```
180
- EXTRACTED ctx.store.insertObservations resolves to a symbol: no
181
- INFERRED insertObservations resolves to a symbol: YES
182
- ```
183
-
184
- The qualified name is a dead label — no store defines a symbol called
185
- `ctx.store.insertObservations`. The bare INFERRED row is the only one carrying a
186
- traversable target, so dropping it would have severed every `path` that crosses a
187
- method call. 0.5.3 **merges** the pair instead: the qualified name is kept for
188
- reading, the resolved id adopted for traversal. One row, honest label, working
189
- `path`.
190
-
191
- **4. Lower the `get_observations` default.** At 539 avg tokens it is the most
192
- expensive call in the set, driven by `chars: 2000`. Most expansions need a paragraph.
193
- Dropping the default to ~800 with the existing `… N more characters` marker keeps
194
- the escape hatch and cuts the common case; the marker already tells the caller when
195
- to ask for more.
196
-
197
- ## The other direction: what it saves when actually used
198
-
199
- Worth stating plainly, because the items above are all about cost and the tool's
200
- value is real.
201
-
202
- `find_usages --mode usages` costs ~187 tokens and returns the definition, every
203
- reference, and the relation type per reference, in one call. Reconstructing that with
204
- grep takes several calls — the grep, then reading each site to classify whether it is
205
- a call, an import, or an inherit. Establishing the finding-2 result by hand in this
206
- session (`grep`, then `sed` over three call sites) cost roughly 500 tokens to reach
207
- an answer one `usages` call would have given for 187 — except that in this instance
208
- the graph had the wrong answer, which is why finding 2 matters for token cost too:
209
- **a tool that is cheaper per call only saves tokens if its answer is trusted enough
210
- not to be re-verified.**
211
-
212
- That is the real relationship between the two halves of this document. The prior
213
- session's 1.1% usage rate traced back to a single early failure
214
- (observation `3f97c5fc-89bd`: one `is not inside a git working tree` error, then 392
215
- consecutive calls without touching the tool). Findings 1-4 are each a reason to
216
- re-verify output by hand, and hand-verification is where the tokens actually go.