claude-db 0.5.1 → 0.5.3

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,90 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.5.3
4
+
5
+ ### Fixed
6
+
7
+ - **`timeline` could not accept the ids it was shown.** Every id that reaches a
8
+ caller is shortened to 13 characters for display, and `get_observations`
9
+ resolves those by prefix — but `timeline` matched exactly, in all three
10
+ adapters, and its miss surfaced as the plausible "No matching observations."
11
+ rather than an error. The tool had never worked over MCP. It now resolves the
12
+ anchor the same way `get_observations` does; the smoke test that missed this
13
+ fed it a full id straight from the store, the one input shape no real caller
14
+ produces, and now feeds a short one.
15
+ - **`Class.method()` did not count as a reference to `Class`.** A member call
16
+ produced edges to the method and to the qualified name, never to the object,
17
+ so a class only ever built through a static factory looked unreferenced —
18
+ including every store backend in this project, where `SqliteStore.create(uri)`
19
+ is the sole construction site. A blast-radius check would have reported one
20
+ caller (itself) and a rename on that basis breaks the store factory.
21
+ - **Callers inside anonymous functions were named after a nearby variable.**
22
+ `const ctx = await createContext()` attributed the call to `ctx`, and
23
+ `const result = await flushSession(...)` to `result` — assignment targets, not
24
+ callers, and every hook entry point in this codebase is an anonymous callback.
25
+ A variable declared on the line making the call is no longer treated as the
26
+ enclosing scope; those sites now name the file, which is at least true.
27
+ - **One call was reported as two edges, and destructuring patterns as symbols.**
28
+ `ctx.store.insertObservations()` appeared once qualified and once bare, and
29
+ `const { turns, nextOffset } = ...` stored the pattern text as a symbol name.
30
+ The two edges are now merged into one, keeping the qualified name for reading
31
+ and the resolved target for traversal — the qualified edge resolves to nothing
32
+ on its own, so dropping the bare one instead would have severed the only
33
+ working link.
34
+
35
+ ### Changed
36
+
37
+ - **Stopped pre-expanding a full observation body on every prompt.** The
38
+ per-prompt block pasted in the top hit's entire body, up to 900 characters,
39
+ before anything had asked for it — layer 3 of a three-layer disclosure design,
40
+ paid unconditionally for a roughly 1-in-9 chance of being used. `expandTop`
41
+ now defaults to `0`, and the index line carries the matched snippet instead,
42
+ which is capped at 110 characters and shows *why* a result matched. Measured
43
+ across four real prompts, the block goes from ~1,560 to ~520 characters, a 67%
44
+ cut, and still names the id to expand on demand. `promptMaxChars` rises 500 ->
45
+ 700 so the budget fits the four results `promptResults` asks for.
46
+
47
+ Existing installs materialise every config value to disk, so a schema default
48
+ alone would have reached nobody. A saved `inject` block still holding both old
49
+ defaults exactly is now treated as untouched and picks up the new ones; anyone
50
+ who tuned either value keeps what they set.
51
+ - **Stopped re-injecting what a session had already been shown.** Every prompt
52
+ got a `<recalled-memory>` block from a fresh search, and because the best
53
+ match for one prompt is usually the best match for the next, the same
54
+ observations were pasted in over and over. Measured across 25 real sessions,
55
+ **56% of everything injected was already in the conversation** — roughly 950
56
+ wasted tokens per session. Each session now tracks which observations it has
57
+ surfaced and skips them; when every match is already in context it injects
58
+ nothing at all, which happened on 28% of prompts in the replay. Nothing is
59
+ lost: the content was in the transcript either way.
60
+
61
+ ## 0.5.2
62
+
63
+ ### Fixed
64
+
65
+ - **A turn that answered a question was never stored.** Capture kept a turn only
66
+ if it edited a file or ran a command, so an entire session spent explaining a
67
+ design, weighing an approach, or answering "why is it like this" left nothing
68
+ behind — the reasoning most worth recalling was the reasoning most reliably
69
+ dropped. A turn with no files and no commands is now kept when the question
70
+ was a real one and the answer reports something concrete. Re-reading this
71
+ project's own transcripts recovers 66 observations that were silently
72
+ discarded; `claude-db flush` backfills them, since ids are content-derived and
73
+ a re-read rewrites rather than duplicates.
74
+ - **A compaction summary was read as your prompt.** When a session is compacted,
75
+ Claude Code writes an 18,000-character recap into the transcript as a user
76
+ entry. Capture treated it as a real prompt, so every turn after a compaction
77
+ was filed under `Asked: This session is being continued from a previous
78
+ conversation…` and that recap was indexed as if it were a memory. Those
79
+ entries are now skipped by the flag the transcript already carries.
80
+ - **`scan` was missing from `claude-db --help`.** The command shipped in 0.5.0
81
+ and worked, but nothing in the help text mentioned it, and the `usages` line
82
+ still described the old grep-only behaviour with no sign of `--mode`.
83
+ - **Underscores were stripped out of titles.** Title generation treated `_` as
84
+ markdown emphasis, so `find_usages` was stored as `findusages` and every other
85
+ snake_case identifier was mangled. Snippets stopped doing this in 0.3.0;
86
+ titles now match.
87
+
3
88
  ## 0.5.1
4
89
 
5
90
  ### Fixed
package/LICENSE CHANGED
@@ -186,7 +186,7 @@
186
186
  same "printed page" as the copyright notice for easier
187
187
  identification within third-party archives.
188
188
 
189
- Copyright 2026 Kishan Lal Rai
189
+ Copyright 2026 Avijit Dey
190
190
 
191
191
  Licensed under the Apache License, Version 2.0 (the "License");
192
192
  you may not use this file except in compliance with the License.
@@ -96,6 +96,7 @@ export function resetCursor(sessionId) {
96
96
  }
97
97
  export function clearCursor(sessionId) {
98
98
  rmSync(cursorPath(sessionId), { force: true });
99
+ rmSync(cursorPath(sessionId).replace(/\.offset$/, '.shown'), { force: true });
99
100
  }
100
101
  export function sweepCursors() {
101
102
  const dir = join(CONFIG_DIR, 'cursors');
@@ -106,10 +107,11 @@ export function sweepCursors() {
106
107
  catch {
107
108
  return 0;
108
109
  }
109
- const live = new Set(sessionIdsOnDisk().map(cursorName));
110
+ const live = new Set(sessionIdsOnDisk().map((id) => id.replace(/[^\w-]/g, '_')));
110
111
  let removed = 0;
111
112
  for (const file of files) {
112
- if (!file.endsWith('.offset') || live.has(file))
113
+ const match = /^(.+)\.(offset|shown)$/.exec(file);
114
+ if (!match?.[1] || live.has(match[1]))
113
115
  continue;
114
116
  rmSync(join(dir, file), { force: true });
115
117
  removed += 1;
@@ -46,7 +46,7 @@ function groupIntoTurns(entries) {
46
46
  const timestamp = Date.parse(entry.timestamp ?? '') || Date.now();
47
47
  if (entry.type === 'user') {
48
48
  const text = extractText(entry.message?.content);
49
- if (!text || isSyntheticPrompt(text))
49
+ if (!text || entry.isCompactSummary || isSyntheticPrompt(text))
50
50
  continue;
51
51
  if (current)
52
52
  turns.push(current);
@@ -1,4 +1,5 @@
1
1
  import { classifyCommand } from './command.js';
2
+ import { isSearchable } from '../util/prompt.js';
2
3
  import { currentAuthor, observationId } from './identity.js';
3
4
  export function observationsFromTurns(turns, sessionId, project, config) {
4
5
  return turns
@@ -8,7 +9,13 @@ export function observationsFromTurns(turns, sessionId, project, config) {
8
9
  function isSubstantive(turn, config) {
9
10
  const files = turn.files.filter((file) => !isExcluded(file, config.capture.exclude));
10
11
  const commands = turn.commands.filter((command) => classifyCommand(command) !== null);
11
- return files.length > 0 || commands.length > 0;
12
+ if (files.length > 0 || commands.length > 0)
13
+ return true;
14
+ return isSearchable(turn.prompt) && answers(turn.reasoning);
15
+ }
16
+ function answers(reasoning) {
17
+ const scored = scoreSentences(stripMarkdown(redact(reasoning)));
18
+ return scored.length >= 2 && scored.some(([, score]) => score > 0);
12
19
  }
13
20
  function buildObservation(turn, sessionId, project, config) {
14
21
  const files = [...new Set(turn.files.filter((f) => !isExcluded(f, config.capture.exclude)))];
@@ -61,10 +68,7 @@ function reports(sentence) {
61
68
  }
62
69
  function buildTitle(turn, files) {
63
70
  const prose = stripMarkdown(redact(turn.reasoning));
64
- const scored = sentences(prose)
65
- .slice(0, 6)
66
- .filter((sentence) => sentence.length >= 15)
67
- .map((sentence) => [sentence, reports(sentence)]);
71
+ const scored = scoreSentences(prose);
68
72
  const best = scored.find(([, score]) => score > 0) ?? scored.find(([, score]) => score === 0);
69
73
  if (best)
70
74
  return headline(best[0]);
@@ -76,6 +80,12 @@ function buildTitle(turn, files) {
76
80
  return headline(opening);
77
81
  return files.length > 0 ? `Changed ${shortPath(files[0] ?? '')}` : 'Session work';
78
82
  }
83
+ function scoreSentences(prose) {
84
+ return sentences(prose)
85
+ .slice(0, 6)
86
+ .filter((sentence) => sentence.length >= 15)
87
+ .map((sentence) => [sentence, reports(sentence)]);
88
+ }
79
89
  function sentences(text) {
80
90
  return text
81
91
  .split(/(?<=[.!?])\s+|\n+/)
@@ -131,7 +141,7 @@ function firstSentence(text) {
131
141
  function stripMarkdown(text) {
132
142
  return text
133
143
  .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
134
- .replace(/[*_`#]/g, '')
144
+ .replace(/[*`#]/g, '')
135
145
  .trim();
136
146
  }
137
147
  function shortPath(path) {
package/dist/cli/usage.js CHANGED
@@ -17,8 +17,10 @@ export function usage() {
17
17
  stats What this project's memory is made of
18
18
  flush Re-ingest every transcript for this project
19
19
  seed --from-git [--limit n] Fill a cold memory from this repo's history
20
- usages [--regex] <symbol> Find real usages via git grep, current source only
21
- [--context n] [--path <dir>] [--limit n]
20
+ scan [--force] Map this repo's symbols and how they connect
21
+ usages [--mode m] <symbol> Who uses a symbol; --mode usages|explain|path
22
+ [--target <symbol>] ...the second symbol, for --mode path
23
+ [--regex] [--context n] [--path <dir>] [--limit n]
22
24
  export [--all] > out.jsonl Dump memory as JSONL, for backup or migration
23
25
  import <file.jsonl> Load a dump back in (safe to repeat)
24
26
  sync <url> [--yes] Two-way merge with another database
@@ -5,13 +5,27 @@ import { ConfigSchema } from './schema.js';
5
5
  export const CONFIG_DIR = join(homedir(), '.claude-memory');
6
6
  export const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
7
7
  export const DEFAULT_DB_PATH = join(CONFIG_DIR, 'memory.db');
8
+ const SUPERSEDED_INJECT = { expandTop: 1, promptMaxChars: 500 };
9
+ function dropSupersededDefaults(raw) {
10
+ const file = raw;
11
+ const inject = file?.inject;
12
+ if (!inject)
13
+ return raw;
14
+ const untouched = Object.entries(SUPERSEDED_INJECT).every(([key, value]) => inject[key] === value);
15
+ if (!untouched)
16
+ return raw;
17
+ const trimmed = { ...inject };
18
+ for (const key of Object.keys(SUPERSEDED_INJECT))
19
+ delete trimmed[key];
20
+ return { ...file, inject: trimmed };
21
+ }
8
22
  export function loadConfig() {
9
23
  let fileConfig = {};
10
24
  try {
11
25
  fileConfig = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
12
26
  }
13
27
  catch { }
14
- const config = ConfigSchema.parse(fileConfig);
28
+ const config = ConfigSchema.parse(dropSupersededDefaults(fileConfig));
15
29
  const envUrl = process.env['CLAUDE_DB_URL']?.trim();
16
30
  return {
17
31
  ...config,
@@ -22,8 +22,8 @@ export const ConfigSchema = z.object({
22
22
  maxChars: z.number().int().positive().default(6000),
23
23
  perPrompt: z.boolean().default(true),
24
24
  promptResults: z.number().int().positive().max(10).default(4),
25
- promptMaxChars: z.number().int().positive().default(500),
26
- expandTop: z.number().int().min(0).max(3).default(1),
25
+ promptMaxChars: z.number().int().positive().default(700),
26
+ expandTop: z.number().int().min(0).max(3).default(0),
27
27
  expandMaxChars: z.number().int().positive().default(900),
28
28
  })
29
29
  .prefault({}),
@@ -7,6 +7,7 @@ const SHARED_DEFINITIONS = [
7
7
  const SHARED_REFERENCES = [
8
8
  { kind: 'call_expression', field: ['function'], relation: 'calls' },
9
9
  { kind: 'call_expression', field: ['function', 'property'], relation: 'calls' },
10
+ { kind: 'call_expression', field: ['function', 'object'], relation: 'references' },
10
11
  { kind: 'new_expression', field: ['constructor'], relation: 'calls' },
11
12
  { kind: 'import_statement', field: ['source'], relation: 'imports' },
12
13
  { kind: 'export_statement', field: ['source'], relation: 'imports' },
@@ -2,6 +2,7 @@ import { observationId } from '../../capture/identity.js';
2
2
  import { redact } from '../../capture/turn-extractor.js';
3
3
  import { languageHandle, loadParser } from '../parser.js';
4
4
  const CALLABLE = new Set(['function', 'method', 'class']);
5
+ const IDENTIFIER = /^[\w$]+$/;
5
6
  export function symbolId(project, file, name, kind) {
6
7
  return observationId('graph', 0, `${project}\0${file}\0${name}\0${kind}`);
7
8
  }
@@ -27,10 +28,12 @@ function enclosing(line, spans) {
27
28
  if (CALLABLE.has(span.symbol.kind)) {
28
29
  if (!best || width < best.end - best.start)
29
30
  best = span;
31
+ continue;
30
32
  }
31
- else if (!fallback || width < fallback.end - fallback.start) {
33
+ if (span.start === line)
34
+ continue;
35
+ if (!fallback || width < fallback.end - fallback.start)
32
36
  fallback = span;
33
- }
34
37
  }
35
38
  return (best ?? fallback)?.symbol ?? null;
36
39
  }
@@ -44,7 +47,7 @@ export function extractFile(file, project) {
44
47
  for (const node of root.findAll({ rule: { kind: rule.kind } })) {
45
48
  const named = resolveField(node, rule.field);
46
49
  const name = named?.text();
47
- if (!named || !name)
50
+ if (!named || !name || !IDENTIFIER.test(name))
48
51
  continue;
49
52
  const line = named.range().start.line + 1;
50
53
  const symbol = {
@@ -87,6 +90,8 @@ export function extractFile(file, project) {
87
90
  const name = unquote(raw.trim());
88
91
  if (!name || /\s/.test(name))
89
92
  continue;
93
+ if (rule.relation === 'references' && name.includes('.'))
94
+ continue;
90
95
  const line = target.range().start.line + 1;
91
96
  references.push({
92
97
  file: file.path,
@@ -44,5 +44,38 @@ export function resolveEdges(project, symbols, references) {
44
44
  line: reference.line,
45
45
  });
46
46
  }
47
- return edges;
47
+ return mergeMemberCalls(edges);
48
+ }
49
+ function mergeMemberCalls(edges) {
50
+ const byLine = new Map();
51
+ for (const edge of edges) {
52
+ const key = `${edge.file}\0${edge.line}`;
53
+ const bucket = byLine.get(key);
54
+ if (bucket)
55
+ bucket.push(edge);
56
+ else
57
+ byLine.set(key, [edge]);
58
+ }
59
+ const merged = new Set();
60
+ for (const bucket of byLine.values()) {
61
+ for (const qualified of bucket) {
62
+ const dot = qualified.dstName.lastIndexOf('.');
63
+ if (dot < 0)
64
+ continue;
65
+ const tail = qualified.dstName.slice(dot + 1);
66
+ for (const bare of bucket) {
67
+ if (bare === qualified)
68
+ continue;
69
+ if (bare.dstName !== tail || bare.relation !== qualified.relation)
70
+ continue;
71
+ if (!qualified.dstId && bare.dstId) {
72
+ qualified.dstId = bare.dstId;
73
+ qualified.confidence = bare.confidence;
74
+ qualified.score = bare.score;
75
+ }
76
+ merged.add(bare.id);
77
+ }
78
+ }
79
+ }
80
+ return edges.filter((edge) => !merged.has(edge.id));
48
81
  }
@@ -1,3 +1,2 @@
1
1
  import type { Observation, ObservationIndexEntry } from '../types.js';
2
- export declare function isSearchable(prompt: string): boolean;
3
2
  export declare function renderPromptContext(entries: ObservationIndexEntry[], maxChars: number, expanded?: Observation[], expandMaxChars?: number): string | null;
@@ -1,76 +1,4 @@
1
1
  import { toShortId } from '../util/shortid.js';
2
- const TRIVIAL = new Set([
3
- 'ok',
4
- 'okay',
5
- 'yes',
6
- 'no',
7
- 'yep',
8
- 'nope',
9
- 'sure',
10
- 'thanks',
11
- 'thank you',
12
- 'continue',
13
- 'go on',
14
- 'go ahead',
15
- 'next',
16
- 'stop',
17
- 'wait',
18
- 'done',
19
- 'good',
20
- 'nice',
21
- 'perfect',
22
- 'great',
23
- 'do it',
24
- 'proceed',
25
- 'retry',
26
- 'again',
27
- 'fix it',
28
- ]);
29
- const NOISE = new Set([
30
- 'the',
31
- 'and',
32
- 'for',
33
- 'this',
34
- 'that',
35
- 'with',
36
- 'you',
37
- 'can',
38
- 'please',
39
- 'now',
40
- 'what',
41
- 'why',
42
- 'how',
43
- 'when',
44
- 'where',
45
- 'are',
46
- 'was',
47
- 'were',
48
- 'have',
49
- 'has',
50
- 'not',
51
- 'let',
52
- 'make',
53
- 'get',
54
- 'add',
55
- 'use',
56
- 'need',
57
- 'want',
58
- 'should',
59
- ]);
60
- const DENSE_SCRIPT = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/gu;
61
- export function isSearchable(prompt) {
62
- const normalized = prompt.trim().toLowerCase();
63
- if (TRIVIAL.has(normalized.replace(/[.!?]+$/, '')))
64
- return false;
65
- if ((normalized.match(DENSE_SCRIPT)?.length ?? 0) >= 4)
66
- return true;
67
- if (normalized.length < 8)
68
- return false;
69
- const content = normalized
70
- .split(/[^\p{L}\p{N}_]+/u)
71
- .filter((word) => word.length > 2 && !NOISE.has(word));
72
- return content.length >= 2;
73
- }
74
2
  export function renderPromptContext(entries, maxChars, expanded = [], expandMaxChars = 900) {
75
3
  if (entries.length === 0)
76
4
  return null;
@@ -86,7 +14,8 @@ export function renderPromptContext(entries, maxChars, expanded = [], expandMaxC
86
14
  if (expandedIds.has(entry.id))
87
15
  continue;
88
16
  const date = new Date(entry.createdAt).toISOString().slice(0, 7);
89
- const line = `${toShortId(entry.id)} ${entry.kind} ${date} ${entry.title}`;
17
+ const head = `${toShortId(entry.id)} ${entry.kind} ${date} ${entry.title}`;
18
+ const line = entry.snippet ? `${head}\n ${entry.snippet}` : head;
90
19
  if (line.length > budget)
91
20
  break;
92
21
  budget -= line.length + 1;
@@ -0,0 +1,2 @@
1
+ export declare function readShown(sessionId: string): Set<string>;
2
+ export declare function markShown(sessionId: string, ids: string[]): void;
@@ -0,0 +1,26 @@
1
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
+ import { dirname, join } from 'node:path';
3
+ import { CONFIG_DIR } from '../config/index.js';
4
+ const LIMIT = 300;
5
+ function shownPath(sessionId) {
6
+ return join(CONFIG_DIR, 'cursors', `${sessionId.replace(/[^\w-]/g, '_')}.shown`);
7
+ }
8
+ export function readShown(sessionId) {
9
+ try {
10
+ return new Set(readFileSync(shownPath(sessionId), 'utf8').split('\n').filter(Boolean));
11
+ }
12
+ catch {
13
+ return new Set();
14
+ }
15
+ }
16
+ export function markShown(sessionId, ids) {
17
+ if (ids.length === 0)
18
+ return;
19
+ const path = shownPath(sessionId);
20
+ const kept = [...readShown(sessionId), ...ids].slice(-LIMIT);
21
+ try {
22
+ mkdirSync(dirname(path), { recursive: true });
23
+ writeFileSync(path, `${[...new Set(kept)].join('\n')}\n`, 'utf8');
24
+ }
25
+ catch { }
26
+ }
@@ -2,7 +2,9 @@
2
2
  import { flushSession } from '../capture/index.js';
3
3
  import { createContext } from '../context.js';
4
4
  import { emitContext, readPayload, runHook } from './payload.js';
5
- import { isSearchable, renderPromptContext } from './relevance.js';
5
+ import { markShown, readShown } from './shown.js';
6
+ import { renderPromptContext } from './relevance.js';
7
+ import { isSearchable } from '../util/prompt.js';
6
8
  import { resolveProject } from '../util/project.js';
7
9
  import { silenceSqliteWarning } from '../util/warnings.js';
8
10
  silenceSqliteWarning();
@@ -19,18 +21,24 @@ await runHook(async () => {
19
21
  const prompt = payload.prompt ?? '';
20
22
  if (!ctx.config.inject.perPrompt || !isSearchable(prompt))
21
23
  return;
22
- const entries = await ctx.search.search({
24
+ const shown = readShown(sessionId);
25
+ const found = await ctx.search.search({
23
26
  text: prompt,
24
27
  project,
25
28
  limit: ctx.config.inject.promptResults,
26
29
  });
30
+ const entries = found.filter((entry) => !shown.has(entry.id));
31
+ if (entries.length === 0)
32
+ return;
27
33
  const toExpand = entries.slice(0, ctx.config.inject.expandTop);
28
34
  const expanded = toExpand.length > 0
29
35
  ? await ctx.search.getObservations(toExpand.map((entry) => entry.id))
30
36
  : [];
31
37
  const block = renderPromptContext(entries, ctx.config.inject.promptMaxChars, expanded, ctx.config.inject.expandMaxChars);
32
- if (block)
33
- emitContext(`${block}\n`);
38
+ if (!block)
39
+ return;
40
+ markShown(sessionId, entries.map((entry) => entry.id));
41
+ emitContext(`${block}\n`);
34
42
  }
35
43
  finally {
36
44
  await ctx.close();
@@ -38,7 +38,10 @@ export class SearchService {
38
38
  }
39
39
  }
40
40
  async timeline(query) {
41
- return this.store.timeline(query);
41
+ const [anchor] = await this.store.getObservations([query.observationId]);
42
+ if (!anchor)
43
+ return [];
44
+ return this.store.timeline({ ...query, observationId: anchor.id });
42
45
  }
43
46
  async getObservations(ids) {
44
47
  return this.store.getObservations(ids);
@@ -0,0 +1 @@
1
+ export declare function isSearchable(prompt: string): boolean;
@@ -0,0 +1,72 @@
1
+ const TRIVIAL = new Set([
2
+ 'ok',
3
+ 'okay',
4
+ 'yes',
5
+ 'no',
6
+ 'yep',
7
+ 'nope',
8
+ 'sure',
9
+ 'thanks',
10
+ 'thank you',
11
+ 'continue',
12
+ 'go on',
13
+ 'go ahead',
14
+ 'next',
15
+ 'stop',
16
+ 'wait',
17
+ 'done',
18
+ 'good',
19
+ 'nice',
20
+ 'perfect',
21
+ 'great',
22
+ 'do it',
23
+ 'proceed',
24
+ 'retry',
25
+ 'again',
26
+ 'fix it',
27
+ ]);
28
+ const NOISE = new Set([
29
+ 'the',
30
+ 'and',
31
+ 'for',
32
+ 'this',
33
+ 'that',
34
+ 'with',
35
+ 'you',
36
+ 'can',
37
+ 'please',
38
+ 'now',
39
+ 'what',
40
+ 'why',
41
+ 'how',
42
+ 'when',
43
+ 'where',
44
+ 'are',
45
+ 'was',
46
+ 'were',
47
+ 'have',
48
+ 'has',
49
+ 'not',
50
+ 'let',
51
+ 'make',
52
+ 'get',
53
+ 'add',
54
+ 'use',
55
+ 'need',
56
+ 'want',
57
+ 'should',
58
+ ]);
59
+ const DENSE_SCRIPT = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/gu;
60
+ export function isSearchable(prompt) {
61
+ const normalized = prompt.trim().toLowerCase();
62
+ if (TRIVIAL.has(normalized.replace(/[.!?]+$/, '')))
63
+ return false;
64
+ if ((normalized.match(DENSE_SCRIPT)?.length ?? 0) >= 4)
65
+ return true;
66
+ if (normalized.length < 8)
67
+ return false;
68
+ const content = normalized
69
+ .split(/[^\p{L}\p{N}_]+/u)
70
+ .filter((word) => word.length > 2 && !NOISE.has(word));
71
+ return content.length >= 2;
72
+ }
@@ -0,0 +1,391 @@
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.
@@ -0,0 +1,216 @@
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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-db",
3
- "version": "0.5.1",
3
+ "version": "0.5.3",
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",
@@ -101,7 +101,7 @@
101
101
  "url": "https://github.com/Avijit07x/claude-db/issues"
102
102
  },
103
103
  "homepage": "https://github.com/Avijit07x/claude-db#readme",
104
- "author": "Kishan Lal Rai",
104
+ "author": "Avijit Dey",
105
105
  "publishConfig": {
106
106
  "access": "public"
107
107
  }