claude-db 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (203) hide show
  1. package/CHANGELOG.md +399 -0
  2. package/README.md +62 -94
  3. package/dist/capture/command.d.ts +0 -14
  4. package/dist/capture/command.js +0 -23
  5. package/dist/capture/flush.d.ts +1 -50
  6. package/dist/capture/flush.js +4 -63
  7. package/dist/capture/git.js +0 -20
  8. package/dist/capture/identity.d.ts +0 -17
  9. package/dist/capture/identity.js +1 -21
  10. package/dist/capture/index.d.ts +1 -0
  11. package/dist/capture/index.js +1 -0
  12. package/dist/capture/manual.d.ts +0 -19
  13. package/dist/capture/manual.js +0 -0
  14. package/dist/capture/progress.d.ts +4 -0
  15. package/dist/capture/progress.js +33 -0
  16. package/dist/capture/transcript.d.ts +0 -45
  17. package/dist/capture/transcript.js +4 -70
  18. package/dist/capture/turn-extractor.d.ts +0 -15
  19. package/dist/capture/turn-extractor.js +1 -104
  20. package/dist/cli/args.d.ts +4 -0
  21. package/dist/cli/args.js +16 -0
  22. package/dist/cli/commands/doctor.d.ts +1 -0
  23. package/dist/cli/commands/doctor.js +76 -0
  24. package/dist/cli/commands/graph.d.ts +2 -0
  25. package/dist/cli/commands/graph.js +93 -0
  26. package/dist/cli/commands/insight.d.ts +3 -0
  27. package/dist/cli/commands/insight.js +129 -0
  28. package/dist/cli/commands/maintain.d.ts +3 -0
  29. package/dist/cli/commands/maintain.js +77 -0
  30. package/dist/cli/commands/memory.d.ts +3 -0
  31. package/dist/cli/commands/memory.js +77 -0
  32. package/dist/cli/commands/seed.d.ts +1 -0
  33. package/dist/cli/commands/seed.js +43 -0
  34. package/dist/cli/commands/setup.d.ts +4 -0
  35. package/dist/cli/commands/setup.js +156 -0
  36. package/dist/cli/commands/sync.d.ts +1 -0
  37. package/dist/cli/commands/sync.js +95 -0
  38. package/dist/cli/commands/transfer.d.ts +9 -0
  39. package/dist/cli/commands/transfer.js +129 -0
  40. package/dist/cli/commands/use.d.ts +1 -0
  41. package/dist/cli/commands/use.js +90 -0
  42. package/dist/cli/constants.d.ts +2 -0
  43. package/dist/cli/constants.js +4 -0
  44. package/dist/cli/files.d.ts +4 -0
  45. package/dist/cli/files.js +33 -0
  46. package/dist/cli/index.js +15 -1080
  47. package/dist/cli/install.d.ts +1 -59
  48. package/dist/cli/install.js +5 -194
  49. package/dist/cli/instructions.d.ts +5 -0
  50. package/dist/cli/instructions.js +55 -0
  51. package/dist/cli/paths.d.ts +5 -0
  52. package/dist/cli/paths.js +19 -0
  53. package/dist/cli/refresh.d.ts +1 -0
  54. package/dist/cli/refresh.js +25 -0
  55. package/dist/cli/usage.d.ts +1 -0
  56. package/dist/cli/usage.js +39 -0
  57. package/dist/config/load.d.ts +0 -5
  58. package/dist/config/load.js +1 -8
  59. package/dist/config/schema.js +2 -58
  60. package/dist/context.d.ts +0 -10
  61. package/dist/context.js +0 -16
  62. package/dist/embed/builtin.d.ts +0 -12
  63. package/dist/embed/builtin.js +0 -20
  64. package/dist/embed/embedder.d.ts +0 -14
  65. package/dist/embed/embedder.js +0 -1
  66. package/dist/embed/index.d.ts +0 -9
  67. package/dist/embed/index.js +0 -9
  68. package/dist/embed/local.d.ts +0 -8
  69. package/dist/embed/local.js +0 -12
  70. package/dist/graph/index.d.ts +7 -0
  71. package/dist/graph/index.js +4 -0
  72. package/dist/graph/languages/ecmascript.d.ts +4 -0
  73. package/dist/graph/languages/ecmascript.js +47 -0
  74. package/dist/graph/languages/go.d.ts +2 -0
  75. package/dist/graph/languages/go.js +15 -0
  76. package/dist/graph/languages/index.d.ts +6 -0
  77. package/dist/graph/languages/index.js +20 -0
  78. package/dist/graph/languages/python.d.ts +2 -0
  79. package/dist/graph/languages/python.js +15 -0
  80. package/dist/graph/languages/rules.d.ts +18 -0
  81. package/dist/graph/languages/rules.js +1 -0
  82. package/dist/graph/languages/rust.d.ts +2 -0
  83. package/dist/graph/languages/rust.js +16 -0
  84. package/dist/graph/parser.d.ts +31 -0
  85. package/dist/graph/parser.js +29 -0
  86. package/dist/graph/query/format.d.ts +2 -0
  87. package/dist/graph/query/format.js +41 -0
  88. package/dist/graph/query/index.d.ts +5 -0
  89. package/dist/graph/query/index.js +4 -0
  90. package/dist/graph/query/lookup.d.ts +21 -0
  91. package/dist/graph/query/lookup.js +35 -0
  92. package/dist/graph/query/path.d.ts +2 -0
  93. package/dist/graph/query/path.js +48 -0
  94. package/dist/graph/query/refresh.d.ts +2 -0
  95. package/dist/graph/query/refresh.js +21 -0
  96. package/dist/graph/scan/extract.d.ts +15 -0
  97. package/dist/graph/scan/extract.js +101 -0
  98. package/dist/graph/scan/files.d.ts +12 -0
  99. package/dist/graph/scan/files.js +51 -0
  100. package/dist/graph/scan/index.d.ts +18 -0
  101. package/dist/graph/scan/index.js +44 -0
  102. package/dist/graph/scan/resolve.d.ts +3 -0
  103. package/dist/graph/scan/resolve.js +48 -0
  104. package/dist/hooks/payload.d.ts +0 -8
  105. package/dist/hooks/payload.js +0 -6
  106. package/dist/hooks/relevance.d.ts +0 -17
  107. package/dist/hooks/relevance.js +55 -38
  108. package/dist/hooks/session-end.js +0 -11
  109. package/dist/hooks/session-start.js +33 -14
  110. package/dist/hooks/user-prompt.js +0 -18
  111. package/dist/mcp/render.d.ts +0 -20
  112. package/dist/mcp/render.js +0 -39
  113. package/dist/mcp/server.js +46 -25
  114. package/dist/search/rank.d.ts +0 -14
  115. package/dist/search/rank.js +0 -16
  116. package/dist/search/service.d.ts +1 -32
  117. package/dist/search/service.js +1 -36
  118. package/dist/store/adapter.d.ts +11 -44
  119. package/dist/store/adapter.js +1 -12
  120. package/dist/store/index.d.ts +0 -11
  121. package/dist/store/index.js +0 -11
  122. package/dist/store/mongo/docs.d.ts +61 -0
  123. package/dist/store/mongo/docs.js +106 -0
  124. package/dist/store/mongo/driver.d.ts +1 -15
  125. package/dist/store/mongo/driver.js +0 -15
  126. package/dist/store/mongo/filters.d.ts +6 -0
  127. package/dist/store/mongo/filters.js +18 -0
  128. package/dist/store/mongo/graph.d.ts +12 -0
  129. package/dist/store/mongo/graph.js +61 -0
  130. package/dist/store/mongo/helpers.d.ts +2 -0
  131. package/dist/store/mongo/helpers.js +8 -0
  132. package/dist/store/mongo/index.d.ts +16 -13
  133. package/dist/store/mongo/index.js +52 -295
  134. package/dist/store/mongo/observations.d.ts +10 -0
  135. package/dist/store/mongo/observations.js +97 -0
  136. package/dist/store/mongo/search.d.ts +6 -0
  137. package/dist/store/mongo/search.js +51 -0
  138. package/dist/store/mongo/sessions.d.ts +6 -0
  139. package/dist/store/mongo/sessions.js +24 -0
  140. package/dist/store/mongo/vectorSearch.d.ts +5 -0
  141. package/dist/store/mongo/vectorSearch.js +57 -0
  142. package/dist/store/postgres/driver.d.ts +19 -0
  143. package/dist/store/postgres/driver.js +13 -0
  144. package/dist/store/postgres/filters.d.ts +2 -0
  145. package/dist/store/postgres/filters.js +22 -0
  146. package/dist/store/postgres/graph.d.ts +11 -0
  147. package/dist/store/postgres/graph.js +115 -0
  148. package/dist/store/postgres/index.d.ts +20 -33
  149. package/dist/store/postgres/index.js +43 -428
  150. package/dist/store/postgres/insert.d.ts +3 -0
  151. package/dist/store/postgres/insert.js +59 -0
  152. package/dist/store/postgres/meta.d.ts +10 -0
  153. package/dist/store/postgres/meta.js +54 -0
  154. package/dist/store/postgres/observations.d.ts +10 -0
  155. package/dist/store/postgres/observations.js +139 -0
  156. package/dist/store/postgres/rows.d.ts +6 -0
  157. package/dist/store/postgres/rows.js +74 -0
  158. package/dist/store/postgres/schema.d.ts +3 -0
  159. package/dist/store/postgres/schema.js +84 -0
  160. package/dist/store/postgres/search.d.ts +3 -0
  161. package/dist/store/postgres/search.js +20 -0
  162. package/dist/store/postgres/sessions.d.ts +5 -0
  163. package/dist/store/postgres/sessions.js +26 -0
  164. package/dist/store/postgres/vectorSearch.d.ts +3 -0
  165. package/dist/store/postgres/vectorSearch.js +21 -0
  166. package/dist/store/sqlite/filters.d.ts +9 -0
  167. package/dist/store/sqlite/filters.js +77 -0
  168. package/dist/store/sqlite/graph.d.ts +11 -0
  169. package/dist/store/sqlite/graph.js +100 -0
  170. package/dist/store/sqlite/index.d.ts +12 -10
  171. package/dist/store/sqlite/index.js +41 -379
  172. package/dist/store/sqlite/observations.d.ts +10 -0
  173. package/dist/store/sqlite/observations.js +128 -0
  174. package/dist/store/sqlite/rows.d.ts +8 -0
  175. package/dist/store/sqlite/rows.js +84 -0
  176. package/dist/store/sqlite/schema.sql +42 -2
  177. package/dist/store/sqlite/search.d.ts +5 -0
  178. package/dist/store/sqlite/search.js +86 -0
  179. package/dist/store/sqlite/sessions.d.ts +5 -0
  180. package/dist/store/sqlite/sessions.js +21 -0
  181. package/dist/types.d.ts +47 -40
  182. package/dist/types.js +0 -4
  183. package/dist/update.d.ts +0 -20
  184. package/dist/update.js +4 -29
  185. package/dist/usages/find.d.ts +2 -8
  186. package/dist/usages/find.js +51 -54
  187. package/dist/usages/index.d.ts +1 -1
  188. package/dist/usages/index.js +1 -1
  189. package/dist/util/project.d.ts +0 -12
  190. package/dist/util/project.js +0 -24
  191. package/dist/util/scope.d.ts +0 -9
  192. package/dist/util/scope.js +0 -9
  193. package/dist/util/shortid.d.ts +0 -5
  194. package/dist/util/shortid.js +1 -19
  195. package/dist/util/snippet.d.ts +0 -26
  196. package/dist/util/snippet.js +0 -30
  197. package/dist/util/vector.d.ts +0 -12
  198. package/dist/util/vector.js +0 -12
  199. package/dist/util/warnings.d.ts +0 -11
  200. package/dist/util/warnings.js +0 -11
  201. package/docs/how-it-works.md +183 -0
  202. package/package.json +14 -3
  203. package/skills/cdb-scan/SKILL.md +31 -6
@@ -1,31 +1,11 @@
1
1
  import { execFileSync } from 'node:child_process';
2
- import { realpathSync } from 'node:fs';
3
- import { relative, resolve } from 'node:path';
4
- // A hit here means the term is too generic to be a symbol lookup at all; the
5
- // fix is a narrower query, not a bigger buffer.
2
+ import { readFileSync, realpathSync, statSync } from 'node:fs';
3
+ import { dirname, join, relative, resolve } from 'node:path';
6
4
  const MAX_BUFFER = 16 * 1024 * 1024;
7
- /**
8
- * Live `git grep`, never a persisted index.
9
- *
10
- * A symbol index that drifts from an edit is the same failure shape as every
11
- * silent-staleness bug this project has already shipped and fixed. This
12
- * re-derives the answer from the current source on every call, so there is
13
- * nothing to invalidate.
14
- */
15
5
  export function findUsages(input) {
16
- // realpath'd up front: git's own --show-toplevel always resolves symlinks
17
- // (on macOS, tmpdir()'s /var/folders/... is itself a symlink to
18
- // /private/var/folders/...), so comparing an un-resolved `start` against it
19
- // below would produce a bogus, always-".."-prefixed relative path and
20
- // silently disable scoping rather than apply it.
21
6
  const start = realpathSync(resolve(input.path ?? process.cwd()));
22
7
  const root = repoRootFor(start);
23
8
  const args = buildArgs(input);
24
- // An explicit path narrows the search to that subtree; omitting it searches
25
- // the whole repository. Defaulting to cwd's subtree would silently hide a
26
- // usage that lives elsewhere in the repo — exactly the case this tool
27
- // exists to catch — so only a caller who deliberately asked to narrow gets
28
- // narrowed. git accepts a file or a directory here equally.
29
9
  if (input.path) {
30
10
  const scope = relative(root, start);
31
11
  if (scope && !scope.startsWith('..'))
@@ -37,7 +17,6 @@ export function findUsages(input) {
37
17
  }
38
18
  catch (error) {
39
19
  const err = error;
40
- // git grep exits 1 for "ran fine, found nothing" — not an error.
41
20
  if (err.status === 1)
42
21
  return { root, matches: [], total: 0, truncated: false };
43
22
  if (/maxBuffer/i.test(err.message)) {
@@ -49,25 +28,20 @@ export function findUsages(input) {
49
28
  const parsed = parseGrepOutput(raw).map((row) => ({
50
29
  ...row,
51
30
  isDefinition: isDefinitionLike(input.symbol, row.text),
31
+ isMatch: true,
52
32
  }));
33
+ const kept = parsed.slice(0, input.limit);
53
34
  return {
54
35
  root,
55
- matches: parsed.slice(0, input.limit),
36
+ matches: input.context > 0 ? withContext(root, kept, input.context) : kept,
56
37
  total: parsed.length,
57
38
  truncated: parsed.length > input.limit,
58
39
  };
59
40
  }
60
- /**
61
- * Deliberately not resolveProject(): that widens to the repository root for
62
- * MEMORY partitioning, and inside a workspace pooling several sibling repos
63
- * it can resolve to a directory that is not itself a git working tree, which
64
- * `git grep` cannot search at all. Delegating to git's own discovery keeps
65
- * this in sync with whatever repo git itself would act on (worktrees,
66
- * submodules, symlinks included) without a second implementation of the walk.
67
- */
68
- function repoRootFor(start) {
41
+ export function repoRootFor(start) {
42
+ const dir = statSync(start).isDirectory() ? start : dirname(start);
69
43
  try {
70
- return execFileSync('git', ['-C', start, 'rev-parse', '--show-toplevel'], {
44
+ return execFileSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], {
71
45
  encoding: 'utf8',
72
46
  }).trim();
73
47
  }
@@ -76,23 +50,51 @@ function repoRootFor(start) {
76
50
  throw new Error(`${start} is not inside a git working tree${stderr ? ` (${stderr})` : ''}`);
77
51
  }
78
52
  }
79
- function buildArgs({ symbol, regex, context }) {
80
- // -I: skip binary files — a binary hit otherwise prints a headerless
81
- // "Binary file X matches" line that corrupts the -z parse below.
82
- // --untracked: a brand-new file the agent just created and has not `git
83
- // add`ed yet is exactly the blast-radius case this tool exists for; without
84
- // this flag it is silently invisible. Still respects .gitignore.
53
+ function buildArgs({ symbol, regex }) {
85
54
  const args = ['grep', '-n', '-z', '-I', '--untracked'];
86
- if (context > 0)
87
- args.push(`-B${context}`, `-A${context}`);
88
- // Word-regexp only in literal mode: a regex author already controls their
89
- // own boundaries, so imposing one on top would be a surprise, not a safety net.
90
55
  args.push(...(regex ? ['--extended-regexp'] : ['--fixed-strings', '--word-regexp']));
91
56
  args.push('-e', symbol);
92
57
  return args;
93
58
  }
94
- /** `-z` NUL-delimits path\0line\0content per record; a stray line with no
95
- * NUL (a `--` context divider, a binary-match notice) is simply dropped. */
59
+ function withContext(root, matches, context) {
60
+ const fileLines = new Map();
61
+ const out = [];
62
+ let lastFile = '';
63
+ let lastLineShown = 0;
64
+ for (const m of matches) {
65
+ let lines = fileLines.get(m.file);
66
+ if (lines === undefined) {
67
+ try {
68
+ lines = readFileSync(join(root, m.file), 'utf8').split('\n');
69
+ }
70
+ catch {
71
+ lines = null;
72
+ }
73
+ fileLines.set(m.file, lines);
74
+ }
75
+ if (!lines) {
76
+ out.push(m);
77
+ continue;
78
+ }
79
+ const from = Math.max(1, m.line - context);
80
+ const to = Math.min(lines.length, m.line + context);
81
+ const start = m.file === lastFile ? Math.max(from, lastLineShown + 1) : from;
82
+ for (let n = start; n <= to; n += 1) {
83
+ out.push(n === m.line
84
+ ? m
85
+ : {
86
+ file: m.file,
87
+ line: n,
88
+ text: lines[n - 1] ?? '',
89
+ isDefinition: false,
90
+ isMatch: false,
91
+ });
92
+ }
93
+ lastFile = m.file;
94
+ lastLineShown = to;
95
+ }
96
+ return out;
97
+ }
96
98
  function parseGrepOutput(raw) {
97
99
  const rows = [];
98
100
  for (const record of raw.split('\n')) {
@@ -106,12 +108,6 @@ function parseGrepOutput(raw) {
106
108
  }
107
109
  return rows;
108
110
  }
109
- /**
110
- * Cheap, best-effort "this looks like the declaration" marker. Unlike
111
- * classifyTurn's `because` regression, this never hides or filters a line —
112
- * it only annotates one already-shown line, so a false positive costs a
113
- * wrong label, not a silently misfiled result.
114
- */
115
111
  function isDefinitionLike(symbol, text) {
116
112
  const s = symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
117
113
  return new RegExp(`\\b(function\\*?\\s+${s}\\b` +
@@ -123,9 +119,10 @@ function isDefinitionLike(symbol, text) {
123
119
  export function formatUsages(result) {
124
120
  if (result.matches.length === 0)
125
121
  return `No usages of that symbol found under ${result.root}.`;
126
- const rows = result.matches.map((m) => `${m.file}:${m.line}${m.isDefinition ? ' [definition?]' : ''} ${m.text.trim()}`);
122
+ const rows = result.matches.map((m) => `${m.file}${m.isMatch ? ':' : '-'}${m.line}${m.isDefinition ? ' [definition?]' : ''} ${m.text.trim()}`);
123
+ const shown = result.matches.filter((m) => m.isMatch).length;
127
124
  const header = result.truncated
128
- ? `showing ${result.matches.length} of ${result.total}+ match(es) (raise \`limit\` or narrow \`symbol\`):`
125
+ ? `showing ${shown} of ${result.total}+ match(es) (raise \`limit\` or narrow \`symbol\`):`
129
126
  : `${result.total} match(es):`;
130
127
  return `${header}\n${rows.join('\n')}`;
131
128
  }
@@ -1,2 +1,2 @@
1
- export { findUsages, formatUsages } from './find.js';
1
+ export { findUsages, formatUsages, repoRootFor } from './find.js';
2
2
  export type { FindUsagesInput, UsagesResult, UsageMatch } from './find.js';
@@ -1 +1 @@
1
- export { findUsages, formatUsages } from './find.js';
1
+ export { findUsages, formatUsages, repoRootFor } from './find.js';
@@ -1,13 +1 @@
1
- /**
2
- * Canonicalises a project path so scoping survives symlinks, then widens it to
3
- * the repository root so every directory inside a repo keys the same memory.
4
- *
5
- * Scoping is an exact string comparison, so two spellings of the same place
6
- * silently split a project's memory in half. macOS makes symlinks the default
7
- * case rather than an edge case: `/tmp` links to `/private/tmp`, so a hook
8
- * reading `cwd` and a CLI reading `process.cwd()` disagree about one folder.
9
- * Subdirectories are the same failure by a different route: running the agent
10
- * from `repo/frontend` used to start a second, empty memory, indistinguishable
11
- * from never having worked in the repo at all.
12
- */
13
1
  export declare function resolveProject(path: string | undefined): string;
@@ -1,18 +1,6 @@
1
1
  import { existsSync, realpathSync } from 'node:fs';
2
2
  import { homedir } from 'node:os';
3
3
  import { dirname, join, resolve, sep } from 'node:path';
4
- /**
5
- * Canonicalises a project path so scoping survives symlinks, then widens it to
6
- * the repository root so every directory inside a repo keys the same memory.
7
- *
8
- * Scoping is an exact string comparison, so two spellings of the same place
9
- * silently split a project's memory in half. macOS makes symlinks the default
10
- * case rather than an edge case: `/tmp` links to `/private/tmp`, so a hook
11
- * reading `cwd` and a CLI reading `process.cwd()` disagree about one folder.
12
- * Subdirectories are the same failure by a different route: running the agent
13
- * from `repo/frontend` used to start a second, empty memory, indistinguishable
14
- * from never having worked in the repo at all.
15
- */
16
4
  export function resolveProject(path) {
17
5
  const absolute = resolve(path ?? process.cwd());
18
6
  let canonical;
@@ -24,18 +12,6 @@ export function resolveProject(path) {
24
12
  }
25
13
  return repoRoot(canonical) ?? canonical;
26
14
  }
27
- /**
28
- * Nearest ancestor containing a `.git` entry, or null outside a work tree.
29
- *
30
- * Never returns the home directory or anything above it. People keep dotfiles
31
- * repositories in `$HOME`, and without that guard every unrelated project on
32
- * the machine would walk up, find `~/.git`, and collapse into a single shared
33
- * memory. A directory that merely holds several repositories is not a repo
34
- * itself, so it keeps its own key and its contents stay pooled.
35
- *
36
- * `.git` is a file rather than a directory in worktrees and submodules, so
37
- * this tests for existence, not for a directory.
38
- */
39
15
  function repoRoot(start) {
40
16
  const home = canonicalHome();
41
17
  for (let dir = start;;) {
@@ -1,10 +1 @@
1
- /**
2
- * Maps a project path to a single opaque FTS-safe token.
3
- *
4
- * Project paths contain slashes, dots and hyphens, all of which FTS5 treats as
5
- * token separators, so a path cannot be matched as one unit. Hashing it to a
6
- * single alphanumeric token lets project scoping happen inside the FTS match
7
- * instead of as a post-match join, which is the difference between scanning
8
- * one project's index and scanning every project's.
9
- */
10
1
  export declare function scopeToken(project: string): string;
@@ -1,12 +1,3 @@
1
- /**
2
- * Maps a project path to a single opaque FTS-safe token.
3
- *
4
- * Project paths contain slashes, dots and hyphens, all of which FTS5 treats as
5
- * token separators, so a path cannot be matched as one unit. Hashing it to a
6
- * single alphanumeric token lets project scoping happen inside the FTS match
7
- * instead of as a post-match join, which is the difference between scanning
8
- * one project's index and scanning every project's.
9
- */
10
1
  export function scopeToken(project) {
11
2
  let hash = 0x811c9dc5;
12
3
  for (let i = 0; i < project.length; i += 1) {
@@ -1,10 +1,5 @@
1
1
  export declare function toShortId(id: string): string;
2
- /** True when a caller passed a short form rather than a full uuid. */
3
2
  export declare function isShortId(id: string): boolean;
4
- /**
5
- * Split incoming ids into exact matches and prefixes so adapters can issue one
6
- * indexed `IN (...)` query plus one prefix query, rather than a scan per id.
7
- */
8
3
  export declare function partitionIds(ids: string[]): {
9
4
  exact: string[];
10
5
  prefixes: string[];
@@ -1,28 +1,10 @@
1
- /**
2
- * Display form for observation ids.
3
- *
4
- * A full UUID costs about 9 tokens per line, roughly as much as the title it
5
- * labels, so nearly half of a search result is identifier noise. Taking the
6
- * first two UUID groups keeps 12 hex digits of entropy (2.8e14 values), which
7
- * makes a collision vanishingly unlikely at the scale one database holds, and
8
- * cuts the identifier to about 4 tokens.
9
- *
10
- * The short form is a literal prefix of the stored id, so resolution is a
11
- * prefix match that every backend can serve from its primary key index. Same
12
- * idea as an abbreviated git SHA.
13
- */
14
- const SHORT_LENGTH = 13; // "2904a5fd-0f22"
1
+ const SHORT_LENGTH = 13;
15
2
  export function toShortId(id) {
16
3
  return id.slice(0, SHORT_LENGTH);
17
4
  }
18
- /** True when a caller passed a short form rather than a full uuid. */
19
5
  export function isShortId(id) {
20
6
  return id.length < 36;
21
7
  }
22
- /**
23
- * Split incoming ids into exact matches and prefixes so adapters can issue one
24
- * indexed `IN (...)` query plus one prefix query, rather than a scan per id.
25
- */
26
8
  export function partitionIds(ids) {
27
9
  const exact = [];
28
10
  const prefixes = [];
@@ -1,28 +1,2 @@
1
- /**
2
- * Shaping for the two places a body is shown in part rather than in full.
3
- *
4
- * Layer 1 was built on the assumption that a title tells you which row holds
5
- * the answer. It often does not — "Committed as 30daa92" is a true report of an
6
- * outcome and says nothing about whether to expand it — so a search returned
7
- * fifteen rows that all looked alike and the only way to choose was to guess.
8
- * A snippet costs about sixty characters and saves a whole body per wrong
9
- * guess, which is the trade the terse index was making in the wrong direction.
10
- */
11
- /**
12
- * One line, whitespace collapsed, clipped at a word boundary.
13
- *
14
- * Bodies carry newlines, markdown tables and code, none of which survive being
15
- * shown on one line of an index; and the search engines wrap matches in their
16
- * own markers, which are noise once the fragment is already the point.
17
- */
18
1
  export declare function toSnippet(text: unknown, max?: number): string | undefined;
19
- /**
20
- * Bounds a full body at layer 3.
21
- *
22
- * The cost argument that made the index terse was never applied one layer down,
23
- * where a single call may ask for twenty-five bodies at once — so the multiplier
24
- * is far worse there than in the index it was written for. The remainder is
25
- * counted rather than dropped silently, because a reader who needs the rest has
26
- * to know it exists.
27
- */
28
2
  export declare function clipBody(body: string, max: number): string;
@@ -1,28 +1,7 @@
1
- /**
2
- * Shaping for the two places a body is shown in part rather than in full.
3
- *
4
- * Layer 1 was built on the assumption that a title tells you which row holds
5
- * the answer. It often does not — "Committed as 30daa92" is a true report of an
6
- * outcome and says nothing about whether to expand it — so a search returned
7
- * fifteen rows that all looked alike and the only way to choose was to guess.
8
- * A snippet costs about sixty characters and saves a whole body per wrong
9
- * guess, which is the trade the terse index was making in the wrong direction.
10
- */
11
1
  const SNIPPET_MAX = 110;
12
- /**
13
- * One line, whitespace collapsed, clipped at a word boundary.
14
- *
15
- * Bodies carry newlines, markdown tables and code, none of which survive being
16
- * shown on one line of an index; and the search engines wrap matches in their
17
- * own markers, which are noise once the fragment is already the point.
18
- */
19
2
  export function toSnippet(text, max = SNIPPET_MAX) {
20
3
  if (typeof text !== 'string')
21
4
  return undefined;
22
- // Backticks, pipes and asterisks are markup and only ever noise on one line.
23
- // Underscores and hashes are left alone: they are far more often part of an
24
- // identifier than of emphasis, and stripping them turned
25
- // `aggregation_cursor.js` into two words that match nothing.
26
5
  const flat = text
27
6
  .replace(/<\/?b>/g, '')
28
7
  .replace(/[|`*]+/g, ' ')
@@ -36,15 +15,6 @@ export function toSnippet(text, max = SNIPPET_MAX) {
36
15
  const word = cut.lastIndexOf(' ');
37
16
  return `${cut.slice(0, word > max * 0.6 ? word : max)}…`;
38
17
  }
39
- /**
40
- * Bounds a full body at layer 3.
41
- *
42
- * The cost argument that made the index terse was never applied one layer down,
43
- * where a single call may ask for twenty-five bodies at once — so the multiplier
44
- * is far worse there than in the index it was written for. The remainder is
45
- * counted rather than dropped silently, because a reader who needs the rest has
46
- * to know it exists.
47
- */
48
18
  export function clipBody(body, max) {
49
19
  if (body.length <= max)
50
20
  return body;
@@ -1,15 +1,3 @@
1
- /** Serialize an embedding for BLOB columns / BSON binary. */
2
1
  export declare function packVector(values: number[]): Buffer;
3
2
  export declare function unpackVector(buffer: Buffer): number[];
4
- /**
5
- * Assumes both inputs are L2-normalized, which the embedder guarantees.
6
- *
7
- * Different widths are different embedding spaces, and a database accumulates
8
- * both the moment `provider: auto` upgrades from the 256d builtin to 384d
9
- * MiniLM. Scoring zero drops those below the relevance floor instead of
10
- * comparing a prefix and returning a meaningless number.
11
- *
12
- * ponytail: width stands in for model identity; store an embedder id per row
13
- * if two same-size models ever coexist.
14
- */
15
3
  export declare function cosine(a: number[], b: number[]): number;
@@ -1,4 +1,3 @@
1
- /** Serialize an embedding for BLOB columns / BSON binary. */
2
1
  export function packVector(values) {
3
2
  const floats = Float32Array.from(values);
4
3
  return Buffer.from(floats.buffer, floats.byteOffset, floats.byteLength);
@@ -7,17 +6,6 @@ export function unpackVector(buffer) {
7
6
  const copy = Buffer.from(buffer);
8
7
  return Array.from(new Float32Array(copy.buffer, copy.byteOffset, copy.byteLength / 4));
9
8
  }
10
- /**
11
- * Assumes both inputs are L2-normalized, which the embedder guarantees.
12
- *
13
- * Different widths are different embedding spaces, and a database accumulates
14
- * both the moment `provider: auto` upgrades from the 256d builtin to 384d
15
- * MiniLM. Scoring zero drops those below the relevance floor instead of
16
- * comparing a prefix and returning a meaningless number.
17
- *
18
- * ponytail: width stands in for model identity; store an embedder id per row
19
- * if two same-size models ever coexist.
20
- */
21
9
  export function cosine(a, b) {
22
10
  if (a.length !== b.length)
23
11
  return 0;
@@ -1,12 +1 @@
1
- /**
2
- * Suppresses Node's ExperimentalWarning for `node:sqlite`.
3
- *
4
- * The warning is correct but useless here: the API is deliberate, not
5
- * accidental, and it fires on every hook invocation. Left alone it prints two
6
- * lines of noise before every prompt the user types, which makes real errors
7
- * from these hooks impossible to spot.
8
- *
9
- * Only that one warning is swallowed. Everything else is re-emitted to stderr
10
- * so genuine problems still surface.
11
- */
12
1
  export declare function silenceSqliteWarning(): void;
@@ -1,14 +1,3 @@
1
- /**
2
- * Suppresses Node's ExperimentalWarning for `node:sqlite`.
3
- *
4
- * The warning is correct but useless here: the API is deliberate, not
5
- * accidental, and it fires on every hook invocation. Left alone it prints two
6
- * lines of noise before every prompt the user types, which makes real errors
7
- * from these hooks impossible to spot.
8
- *
9
- * Only that one warning is swallowed. Everything else is re-emitted to stderr
10
- * so genuine problems still surface.
11
- */
12
1
  export function silenceSqliteWarning() {
13
2
  const original = process.listeners('warning');
14
3
  process.removeAllListeners('warning');
@@ -0,0 +1,183 @@
1
+ # How claude-db works
2
+
3
+ The [README](../README.md) covers what it is and how to use it. This is the
4
+ part underneath: what gets captured, what gets given back, and how the code
5
+ graph stays honest.
6
+
7
+ ## Capture
8
+
9
+ Claude Code already writes every session to disk as JSONL — your prompts, its
10
+ replies, every tool call. claude-db reads that file, so it captures **why** you
11
+ did something, not just which files changed.
12
+
13
+ ```
14
+ you send a prompt
15
+ │
16
+ ├─ 1. save the previous turn
17
+ │ read new lines from the session transcript
18
+ │ keep turns that changed something
19
+ │ store title + reasoning + files, with an embedding
20
+ │
21
+ └─ 2. search memory using your prompt
22
+ inject the best match above your message
23
+ ```
24
+
25
+ Both steps are hooks, so they always run. Nothing depends on Claude deciding to
26
+ look something up.
27
+
28
+ Install also writes a short standing instruction into `CLAUDE.local.md` (or
29
+ `~/.claude/CLAUDE.md` for a machine-wide install), telling Claude to search
30
+ memory before asking you to re-explain something. Hook output is context the
31
+ agent may or may not act on; a memory file is a rule for the whole session,
32
+ which is what makes recall the default rather than something you have to ask
33
+ for. `claude-db uninstall` takes the block back out.
34
+
35
+ **What gets saved.** One observation per turn, and only if that turn edited a
36
+ file or ran a real command. Questions, `grep`, and "ok" are skipped. A busy day
37
+ produces 10 to 20 rows, not hundreds.
38
+
39
+ **What gets injected.** Recent session summaries at startup, plus the single
40
+ best match in full on each prompt. Roughly 350 tokens when something relevant
41
+ exists, zero when it doesn't.
42
+
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.
45
+ Full bodies come only from `get_observations`, for ids you picked.
46
+
47
+ One stored memory looks like this:
48
+
49
+ ```
50
+ [decision] Chose WebSocket over polling for live order updates
51
+
52
+ Asked: the order feed keeps dropping
53
+
54
+ Polling at 3s hammered the API and still lagged behind. Switched to a
55
+ WebSocket subscription with exponential backoff and a replay flag, so no
56
+ order is missed during a drop.
57
+
58
+ Files: src/ws/client.ts, src/ws/reconnect.ts
59
+ Ran: Test run: pnpm test
60
+ ```
61
+
62
+ ## Unfinished work
63
+
64
+ A captured turn is stored `open`, and closes when every file it touched has
65
+ been committed. That check runs inside the flush that already happens on each
66
+ prompt, so nothing new has to fire for it to stay accurate, and a stored flag
67
+ that drifted from reality would be corrected on the next flush anyway.
68
+
69
+ Closing is deliberately one-way. Editing a file again does not reopen work that
70
+ already landed, or a finished task would flicker back into the list every time
71
+ a neighbouring line changed.
72
+
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
76
+ no words worth matching, so recency has to come from somewhere else.
77
+
78
+ Rows captured before this existed default to `done`. Marking a whole existing
79
+ database unfinished would be worse than saying nothing.
80
+
81
+ ## Staying current
82
+
83
+ `claude-db install` copies two things to disk: the `/cdb-scan` skill, and a
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
86
+ soon as the package updates.
87
+
88
+ The hooks are registered by absolute path into the installed package, so they
89
+ always run the current code even when those copies are stale. SessionStart
90
+ compares them against what shipped and rewrites them when they differ, which
91
+ makes `npm i -g claude-db` sufficient on its own and returns `install` to being
92
+ a one-time step.
93
+
94
+ It only refreshes files that already exist. Nothing is created behind your
95
+ back, and anything `uninstall` removed stays removed.
96
+
97
+ ## The code graph
98
+
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
101
+ imports what, what extends what. Parsing is local and deterministic, costs no
102
+ tokens, and takes about a second on a mid-size repository. A rescan only
103
+ re-parses files whose contents changed.
104
+
105
+ `find_usages` then answers in four modes, over MCP as well as the CLI:
106
+
107
+ | mode | answers |
108
+ | ---------------- | ----------------------------------------------------------- |
109
+ | `text` (default) | live `git grep`; needs no scan and is never stale |
110
+ | `usages` | what references this symbol, with the relation on each line |
111
+ | `explain` | that, plus what the symbol itself reaches |
112
+ | `path` | how two symbols connect |
113
+
114
+ ```
115
+ Shortest path (4 hops):
116
+ cmdScan --> scanRepository --> extractFile --> symbolId --> observationId
117
+ ```
118
+
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
121
+ nothing is guessed. `INFERRED` means the target was matched by name across
122
+ files, which is wrong when two files export the same identifier, and carries a
123
+ score saying how sure the match was. Name matching is the one guess this makes,
124
+ so it is labelled rather than presented as fact.
125
+
126
+ **A stored index can go stale, and this one is not allowed to.** Every graph
127
+ query hashes the working tree first and re-parses whatever changed before
128
+ answering, so it cannot report a line the source has already moved past. The
129
+ SessionStart hook does the same refresh in the background for repositories that
130
+ have been scanned, but correctness does not depend on it having run.
131
+
132
+ Traversal is keyed on symbol id rather than name. Keying by name would merge
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
135
+ shortest path a route nothing can actually take.
136
+
137
+ Languages: TypeScript, TSX, JavaScript, Python, Go and Rust. The parser is
138
+ ast-grep, which ships with the package as a prebuilt binary per platform, so
139
+ nothing compiles at install and nothing else has to be installed.
140
+
141
+ ## The `/cdb-scan` skill
142
+
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.
146
+
147
+ The graph records what the code _is_; the notes record why it is built that
148
+ way. Those notes are tagged `inferred`, because they are Claude's reading of
149
+ the code rather than a record of anything that happened. Everything else in the
150
+ database is testimony, and a search result must not blur the two.
151
+
152
+ ## Databases
153
+
154
+ SQLite by default, at `~/.claude-memory/memory.db`. The connection string picks
155
+ the backend, and `CLAUDE_DB_URL` overrides the config file.
156
+
157
+ Search is hybrid — keyword plus vector — on all three backends. Ranking, fusion
158
+ and token budgeting live in `src/search` rather than in the adapters, so recall
159
+ behaves identically no matter which database is plugged in; only retrieval cost
160
+ changes. Memory is partitioned by project path, so one database serves every
161
+ repo you work in.
162
+
163
+ MongoDB Atlas can index vector search instead of scanning brute-force, but
164
+ Atlas indexes are not created by this tool. Add one by hand on the
165
+ `observations` collection:
166
+
167
+ ```json
168
+ {
169
+ "name": "memory_vector",
170
+ "type": "vectorSearch",
171
+ "fields": [
172
+ { "type": "vector", "path": "embedding", "numDimensions": 256, "similarity": "cosine" },
173
+ { "type": "filter", "path": "project" },
174
+ { "type": "filter", "path": "kind" },
175
+ { "type": "filter", "path": "tags" },
176
+ { "type": "filter", "path": "createdAt" }
177
+ ]
178
+ }
179
+ ```
180
+
181
+ `numDimensions` is 256 for the builtin embedder, 384 once
182
+ `@xenova/transformers` is installed. Without this index Mongo still works —
183
+ vector search falls back to scoring candidates in process.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-db",
3
- "version": "0.4.1",
3
+ "version": "0.5.0",
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",
@@ -17,7 +17,9 @@
17
17
  "files": [
18
18
  "dist",
19
19
  "skills",
20
+ "docs",
20
21
  "README.md",
22
+ "CHANGELOG.md",
21
23
  "LICENSE"
22
24
  ],
23
25
  "engines": {
@@ -34,15 +36,24 @@
34
36
  "try": "node scripts/try.mjs",
35
37
  "bench": "node scripts/bench.mjs",
36
38
  "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)}\"",
37
- "prepublishOnly": "npm run build && npm test"
39
+ "prepublishOnly": "npm run build && npm test",
40
+ "format": "prettier --write .",
41
+ "format:check": "prettier --check ."
38
42
  },
39
43
  "dependencies": {
44
+ "@ast-grep/lang-go": "^0.0.6",
45
+ "@ast-grep/lang-python": "^0.0.6",
46
+ "@ast-grep/lang-rust": "^0.0.7",
47
+ "@ast-grep/napi": "^0.45.0",
40
48
  "@modelcontextprotocol/sdk": "^1.30.0",
49
+ "graphology": "^0.26.0",
50
+ "graphology-shortest-path": "^2.1.0",
41
51
  "zod": "^4.4.3"
42
52
  },
43
53
  "devDependencies": {
44
54
  "@types/node": "^22.20.1",
45
- "typescript": "^5.9.3"
55
+ "typescript": "^5.9.3",
56
+ "prettier": "^3.8.0"
46
57
  },
47
58
  "keywords": [
48
59
  "claude",