claude-db 0.5.3 → 0.6.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/CHANGELOG.md +96 -0
- package/README.md +74 -45
- package/dist/capture/flush.js +16 -8
- package/dist/cli/commands/graph.js +14 -2
- package/dist/cli/commands/transfer.d.ts +1 -1
- package/dist/cli/commands/transfer.js +4 -2
- package/dist/cli/index.js +1 -1
- package/dist/cli/install.js +1 -0
- package/dist/cli/usage.js +1 -1
- package/dist/config/schema.d.ts +2 -1
- package/dist/config/schema.js +2 -1
- package/dist/graph/index.d.ts +2 -2
- package/dist/graph/index.js +2 -2
- package/dist/graph/query/format.js +7 -3
- package/dist/graph/query/index.d.ts +1 -0
- package/dist/graph/query/index.js +1 -0
- package/dist/graph/query/lookup.d.ts +1 -0
- package/dist/graph/query/lookup.js +6 -0
- package/dist/graph/query/suggest.d.ts +5 -0
- package/dist/graph/query/suggest.js +65 -0
- package/dist/graph/scan/files.d.ts +1 -0
- package/dist/graph/scan/files.js +8 -2
- package/dist/graph/scan/index.d.ts +1 -1
- package/dist/graph/scan/index.js +1 -1
- package/dist/hooks/grep-symbols.d.ts +3 -0
- package/dist/hooks/grep-symbols.js +22 -0
- package/dist/hooks/prefer-usages.d.ts +2 -0
- package/dist/hooks/prefer-usages.js +58 -0
- package/dist/mcp/server.js +6 -170
- package/dist/mcp/tools/kinds.d.ts +1 -0
- package/dist/mcp/tools/kinds.js +1 -0
- package/dist/mcp/tools/memory.d.ts +3 -0
- package/dist/mcp/tools/memory.js +44 -0
- package/dist/mcp/tools/observations.d.ts +3 -0
- package/dist/mcp/tools/observations.js +55 -0
- package/dist/mcp/tools/search.d.ts +3 -0
- package/dist/mcp/tools/search.js +54 -0
- package/dist/mcp/tools/usages.d.ts +3 -0
- package/dist/mcp/tools/usages.js +79 -0
- package/dist/search/service.js +3 -0
- package/dist/search/stopwords.d.ts +2 -0
- package/dist/search/stopwords.js +137 -0
- package/dist/store/sqlite/filters.js +3 -5
- package/dist/usages/find.d.ts +1 -1
- package/dist/usages/find.js +5 -3
- package/docs/how-it-works.md +12 -12
- package/docs/with-and-without.md +123 -0
- package/package.json +3 -1
- package/docs/mcp-findings.md +0 -391
- package/docs/token-economics.md +0 -216
package/docs/mcp-findings.md
DELETED
|
@@ -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.
|
package/docs/token-economics.md
DELETED
|
@@ -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.
|