claude-db 0.4.0 → 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 -193
  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 +50 -27
  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 +58 -45
  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,26 +1,10 @@
1
1
  import { classifyCommand } from './command.js';
2
2
  import { currentAuthor, observationId } from './identity.js';
3
- /**
4
- * Builds observations from transcript turns.
5
- *
6
- * One observation per turn, titled by what was asked and bodied by what the
7
- * agent explained. That ordering matters: the prompt is the only record of
8
- * intent, and the assistant's prose is the only record of reasoning. A
9
- * file-path-based capture has access to neither, which is why it can never
10
- * produce a memory worth recalling.
11
- */
12
3
  export function observationsFromTurns(turns, sessionId, project, config) {
13
4
  return turns
14
5
  .filter((turn) => isSubstantive(turn, config))
15
6
  .map((turn) => buildObservation(turn, sessionId, project, config));
16
7
  }
17
- /**
18
- * A turn earns a slot only if it changed something.
19
- *
20
- * Conversation that produced no edit and no consequential command is chatter:
21
- * questions about state, requests to explain, "what's in your context". Those
22
- * are answered from the repo, not from memory.
23
- */
24
8
  function isSubstantive(turn, config) {
25
9
  const files = turn.files.filter((file) => !isExcluded(file, config.capture.exclude));
26
10
  const commands = turn.commands.filter((command) => classifyCommand(command) !== null);
@@ -46,8 +30,8 @@ function buildObservation(turn, sessionId, project, config) {
46
30
  sessionId,
47
31
  project,
48
32
  ...(author ? { author } : {}),
33
+ status: 'open',
49
34
  kind: classifyTurn(turn),
50
- // Redacted like the body: the title is injected above every future prompt.
51
35
  title: redact(buildTitle(turn, files)),
52
36
  body,
53
37
  files,
@@ -55,34 +39,8 @@ function buildObservation(turn, sessionId, project, config) {
55
39
  createdAt: turn.timestamp,
56
40
  };
57
41
  }
58
- /**
59
- * Sentences that announce work rather than report it.
60
- *
61
- * The original rule took the reply's opening sentence, assuming it stated the
62
- * outcome. Mid-task it almost never does: it says "Now the use command and the
63
- * top-level handler:" or "Right — let me do that properly". Measured on a real
64
- * database, about half of all titles were transitions like these, which is fatal
65
- * because the title is the whole payload of a search result and of the injected
66
- * block — the body may hold the answer, but nothing ever surfaces it.
67
- */
68
42
  const ANNOUNCEMENT = /^(now|next|then|first|right|ok|okay|good question|great|sure|perfect|let me|let's|i'?ll|here'?s|two|three|four|before|starting|continuing)\b/i;
69
- /**
70
- * Narration of work in progress: "Working through the improvements now."
71
- *
72
- * A participle opener describes what is being done, where a title has to say
73
- * what was. Listed rather than matched as a generic `\w+ing`, which would take
74
- * "Nothing changed" and "Something in the cache" with it.
75
- */
76
43
  const IN_PROGRESS = /^(work|add|fix|runn|updat|writ|build|mak|mov|remov|check|test|switch|wir|tak|go|do|try|look|read|creat|implement|refactor|pull|push|sett)ing\b/i;
77
- /**
78
- * Openers that point at something already said instead of saying it.
79
- *
80
- * Measured against real titles after the 0.2.2 fix: "That's the same gap we
81
- * just closed" displaced "remember() stores text raw — no redaction", because
82
- * the vague sentence happened to contain a past-tense verb. A back-reference
83
- * carries none of the claim — whatever it refers to is the claim — so it
84
- * belongs with the announcements rather than being scored against them.
85
- */
86
44
  const BACKREFERENCE = /^(that'?s|this is|these are|it'?s|there'?s|you'?(ve|re)|we'?(ve|re)|yes\b|no\b|exactly|correct|agreed|fair enough|both\b|either\b|same\b)/i;
87
45
  function announces(sentence) {
88
46
  return (sentence.endsWith(':') ||
@@ -90,58 +48,26 @@ function announces(sentence) {
90
48
  BACKREFERENCE.test(sentence) ||
91
49
  IN_PROGRESS.test(sentence));
92
50
  }
93
- /**
94
- * Marks of a sentence that reports an outcome rather than an intention.
95
- *
96
- * Skipping announcements alone still leaves the first merely-neutral sentence
97
- * winning, so a reply that opens with "Working through the improvements now."
98
- * stores that as its title. Scoring the opening few instead lets a later
99
- * sentence carrying a filename, a version or a past-tense verb take the slot.
100
- */
101
51
  const EVIDENCE = [
102
52
  /[\w-]+\.(ts|tsx|js|jsx|mjs|json|md|sql|py|go|rs|ya?ml|sh|toml|txt|css|html|lock)\b/i,
103
53
  /\b\w{3,}ed\b/i,
104
54
  /\d/,
105
55
  ];
106
- /** -1 announces the work, 0 says nothing in particular, 1 reports an outcome. */
107
56
  function reports(sentence) {
108
57
  if (announces(sentence))
109
58
  return -1;
110
- // A redaction marker is not evidence. "[redacted-key]" reads as a past-tense
111
- // verb to the rule above, which would promote a pasted secret over the
112
- // sentence that says what was actually done.
113
59
  const text = sentence.replace(/\[redacted[^\]]*\]/g, '');
114
60
  return EVIDENCE.some((test) => test.test(text)) ? 1 : 0;
115
61
  }
116
- /**
117
- * Prefers the sentence of the reply that reports the most.
118
- *
119
- * The prompt states a request ("can you create one icon"); the reply states
120
- * what actually happened ("Built mouse-scroll-icon.tsx, first of the Huge
121
- * Tier 1 Gestures batch"). The second is what someone searching their history
122
- * is looking for, and it is written in the vocabulary of the codebase — but
123
- * only once the throat-clearing in front of it is skipped.
124
- *
125
- * Redacted before it is scored, not just before it is stored: a sentence made
126
- * of a pasted key is dense with digits, and would otherwise outscore the one
127
- * that says what was done.
128
- */
129
62
  function buildTitle(turn, files) {
130
63
  const prose = stripMarkdown(redact(turn.reasoning));
131
- // Bounded: past the first few sentences a reply has moved on to detail that
132
- // no longer summarises the turn.
133
64
  const scored = sentences(prose)
134
65
  .slice(0, 6)
135
66
  .filter((sentence) => sentence.length >= 15)
136
67
  .map((sentence) => [sentence, reports(sentence)]);
137
- // The first sentence that reports, not the one that reports most: a later
138
- // sentence accumulates signals just by being long and specific, while the
139
- // summary comes first and the detail follows it.
140
68
  const best = scored.find(([, score]) => score > 0) ?? scored.find(([, score]) => score === 0);
141
69
  if (best)
142
70
  return headline(best[0]);
143
- // Nothing in the reply reports anything, so it is all narration. The prompt
144
- // is the only record of intent, and intent beats "Working through it now."
145
71
  const prompt = firstSentence(redact(turn.prompt));
146
72
  if (prompt)
147
73
  return headline(prompt);
@@ -150,7 +76,6 @@ function buildTitle(turn, files) {
150
76
  return headline(opening);
151
77
  return files.length > 0 ? `Changed ${shortPath(files[0] ?? '')}` : 'Session work';
152
78
  }
153
- /** Split on sentence enders followed by space, so "0.2.1" stays intact. */
154
79
  function sentences(text) {
155
80
  return text
156
81
  .split(/(?<=[.!?])\s+|\n+/)
@@ -158,14 +83,6 @@ function sentences(text) {
158
83
  .filter((sentence) => sentence.length > 0);
159
84
  }
160
85
  const TITLE_MAX = 80;
161
- /**
162
- * Trims a sentence to a scannable headline.
163
- *
164
- * Titles are the entire payload of a layer-1 search result and of the injected
165
- * memory block, so every character is paid on every query. Cutting at a clause
166
- * boundary keeps the claim intact where a hard character truncation would sever
167
- * it mid-phrase.
168
- */
169
86
  function headline(sentence) {
170
87
  if (sentence.length <= TITLE_MAX)
171
88
  return sentence;
@@ -176,12 +93,6 @@ function headline(sentence) {
176
93
  const word = clause.lastIndexOf(' ');
177
94
  return `${clause.slice(0, word > 30 ? word : TITLE_MAX)}...`;
178
95
  }
179
- /**
180
- * The first path segment under the project root, which is the repository name
181
- * when the project directory holds several repos, and the top-level source
182
- * folder when it is one repo. Tags carry real weight in every backend's index,
183
- * so this is what makes a pooled memory filterable by where the work happened.
184
- */
185
96
  export function topLevelDirs(files, project) {
186
97
  const prefix = project.endsWith('/') ? project : `${project}/`;
187
98
  const tags = new Set();
@@ -189,7 +100,6 @@ export function topLevelDirs(files, project) {
189
100
  if (!file.startsWith(prefix))
190
101
  continue;
191
102
  const parts = file.slice(prefix.length).split('/');
192
- // Two or more parts means the first is a directory, not a root-level file.
193
103
  if (parts.length > 1 && parts[0])
194
104
  tags.add(parts[0]);
195
105
  }
@@ -197,18 +107,10 @@ export function topLevelDirs(files, project) {
197
107
  }
198
108
  export function classifyTurn(turn) {
199
109
  const text = `${turn.prompt} ${turn.reasoning}`.toLowerCase();
200
- // Read from the prompt alone, and only where the phrasing is a standing
201
- // instruction. "the build always fails" is a bugfix, not a house rule, so
202
- // always/never have to be followed by something imperative to count.
203
110
  if (/\b(from now on|going forward|remember to|prefer)\b/.test(turn.prompt.toLowerCase()) ||
204
111
  /\b(always|never)\s+(use|run|do|add|write|call|put|name|commit|push|import|install)\b/.test(turn.prompt.toLowerCase())) {
205
112
  return 'preference';
206
113
  }
207
- // `because` used to be in here and matched 98 of 471 stored decisions on its
208
- // own, which is how every second observation became a `decision` and the
209
- // filter stopped narrowing anything. It explains as readily as it decides —
210
- // "the build failed because the cache key was stale" is a bugfix — so what is
211
- // left names an alternative that was weighed.
212
114
  if (/\b(instead of|rather than|in favou?r of|opted for|went with|chose|decided|trade-?off|why we)\b/.test(text)) {
213
115
  return 'decision';
214
116
  }
@@ -226,7 +128,6 @@ function firstSentence(text) {
226
128
  const match = /^(.+?)(?:[.!?](?:\s|$)|\n)/s.exec(trimmed);
227
129
  return (match?.[1] ?? trimmed.split('\n')[0] ?? '').trim();
228
130
  }
229
- /** Markdown links and emphasis read badly in a one-line title. */
230
131
  function stripMarkdown(text) {
231
132
  return text
232
133
  .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
@@ -245,10 +146,6 @@ export function redact(text) {
245
146
  return text
246
147
  .replace(PRIVATE_BLOCK, '[redacted]')
247
148
  .replace(PRIVATE_KEY, '[redacted-private-key]')
248
- // Credentials inside a URL: postgres://, mongodb+srv://, https://. A
249
- // connection string is the likeliest secret to be pasted into a tool whose
250
- // whole job is remembering what you pasted. The host survives, so the
251
- // memory stays useful.
252
149
  .replace(/\/\/[^\s:/@]+:[^\s@]+@/g, '//[redacted]@')
253
150
  .replace(/\b(sk-[A-Za-z0-9_-]{16,})\b/g, '[redacted-key]')
254
151
  .replace(/\b(gh[pousr]_[A-Za-z0-9]{16,})\b/g, '[redacted-token]')
@@ -0,0 +1,4 @@
1
+ import type { Scope } from './paths.js';
2
+ export declare function valueOf(argv: (string | undefined)[], flag: string): string | undefined;
3
+ export declare function withoutFlags(argv: (string | undefined)[], flags: string[]): string[];
4
+ export declare function scopeFrom(args: (string | undefined)[]): Scope;
@@ -0,0 +1,16 @@
1
+ export function valueOf(argv, flag) {
2
+ const index = argv.indexOf(flag);
3
+ return index >= 0 ? argv[index + 1] : undefined;
4
+ }
5
+ export function withoutFlags(argv, flags) {
6
+ const dropped = new Set();
7
+ for (const flag of flags) {
8
+ const at = argv.indexOf(flag);
9
+ if (at >= 0)
10
+ dropped.add(at).add(at + 1);
11
+ }
12
+ return argv.filter((arg, index) => typeof arg === 'string' && !dropped.has(index));
13
+ }
14
+ export function scopeFrom(args) {
15
+ return args.includes('--project') || args.includes('-p') ? 'project' : 'global';
16
+ }
@@ -0,0 +1 @@
1
+ export declare function cmdDoctor(argv: (string | undefined)[]): Promise<void>;
@@ -0,0 +1,76 @@
1
+ import { createContext } from '../../context.js';
2
+ import { loadConfig } from '../../config/index.js';
3
+ import { packageVersion } from '../../update.js';
4
+ import { randomUUID } from 'node:crypto';
5
+ import { remember } from '../../capture/index.js';
6
+ import { resolveProject } from '../../util/project.js';
7
+ import { toShortId } from '../../util/shortid.js';
8
+ export async function cmdDoctor(argv) {
9
+ const base = loadConfig();
10
+ const ctx = await createContext({
11
+ embeddings: { ...base.embeddings, timeoutMs: 0 },
12
+ });
13
+ const reachable = await ctx.store.ping();
14
+ const embedder = await ctx.embedder();
15
+ const vectors = await probeEmbedder(embedder);
16
+ console.log(`version : ${packageVersion()}`);
17
+ console.log(`database : ${ctx.config.database}`);
18
+ console.log(`adapter : ${ctx.store.kind}`);
19
+ console.log(`reachable: ${reachable ? 'yes' : 'no'}`);
20
+ console.log(`requested: embeddings.provider = ${ctx.config.embeddings.provider}`);
21
+ console.log(`embedder : ${embedder.id} (${embedder.dimensions}d)`);
22
+ console.log(`vectors : ${vectors}`);
23
+ console.log(`search : ${vectors.startsWith('working') ? 'hybrid (keyword + vector)' : 'keyword only'}`);
24
+ const healthy = argv.includes('--deep') ? await deepCheck(ctx) : true;
25
+ await ctx.close();
26
+ process.exit(reachable && healthy ? 0 : 1);
27
+ }
28
+ async function deepCheck(ctx) {
29
+ const project = resolveProject(undefined);
30
+ const canary = `zz${randomUUID().replace(/-/g, '')}`;
31
+ let ok = true;
32
+ const step = (label, passed, detail = '') => {
33
+ if (!passed)
34
+ ok = false;
35
+ console.log(` ${passed ? 'ok ' : 'FAIL'} ${label}${detail ? ` — ${detail}` : ''}`);
36
+ };
37
+ console.log('\ndeep check (writes one observation, then deletes it)');
38
+ let id = '';
39
+ try {
40
+ const written = await remember(ctx, {
41
+ project,
42
+ kind: 'context',
43
+ text: `claude-db self check ${canary}`,
44
+ });
45
+ id = written.id;
46
+ step('write', true, toShortId(id));
47
+ }
48
+ catch (error) {
49
+ step('write', false, error instanceof Error ? error.message : String(error));
50
+ return false;
51
+ }
52
+ try {
53
+ const found = await ctx.search.search({ text: canary, project, limit: 5 });
54
+ step('search', found.some((entry) => entry.id === id), `${found.length} result(s)`);
55
+ const [full] = await ctx.search.getObservations([id]);
56
+ step('expand', full?.body.includes(canary) === true);
57
+ }
58
+ finally {
59
+ const deleted = await ctx.store.remove({ ids: [id] });
60
+ step('cleanup', deleted === 1, `${deleted} removed`);
61
+ }
62
+ return ok;
63
+ }
64
+ async function probeEmbedder(embedder) {
65
+ if (embedder.dimensions === 0)
66
+ return 'disabled';
67
+ try {
68
+ const [vector] = await embedder.embed(['connectivity probe']);
69
+ return vector && vector.length > 0
70
+ ? `working (${vector.length}d)`
71
+ : 'unavailable (empty vector)';
72
+ }
73
+ catch (error) {
74
+ return `unavailable (${error instanceof Error ? error.message.split('.')[0] : 'error'})`;
75
+ }
76
+ }
@@ -0,0 +1,2 @@
1
+ export declare function cmdScan(argv: (string | undefined)[]): Promise<void>;
2
+ export declare function cmdUsages(argv: (string | undefined)[]): Promise<void>;
@@ -0,0 +1,93 @@
1
+ import { createContext } from '../../context.js';
2
+ import { findUsages, formatUsages, repoRootFor } from '../../usages/index.js';
3
+ import { formatGraph, languageNames, queryGraph, refreshGraph, scanRepository, } from '../../graph/index.js';
4
+ import { resolveProject } from '../../util/project.js';
5
+ import { valueOf, withoutFlags } from '../args.js';
6
+ export async function cmdScan(argv) {
7
+ const force = argv.includes('--force');
8
+ const path = valueOf(argv, '--path');
9
+ const root = repoRootFor(path ?? process.cwd());
10
+ const project = resolveProject(undefined);
11
+ const ctx = await createContext();
12
+ try {
13
+ const known = force
14
+ ? new Map()
15
+ : new Map((await ctx.store.scannedFiles(project)).map((f) => [f.path, f.hash]));
16
+ const started = Date.now();
17
+ const scan = scanRepository({ root, project, known, ...(force ? { force } : {}) });
18
+ if (force)
19
+ await ctx.store.removeGraph(project);
20
+ else if (scan.changed.length > 0)
21
+ await ctx.store.removeGraph(project, scan.changed);
22
+ await ctx.store.upsertGraph({
23
+ symbols: scan.symbols,
24
+ edges: scan.edges,
25
+ files: scan.files,
26
+ });
27
+ console.log(`Scanned ${root}`);
28
+ console.log(` ${scan.symbols.length} symbols, ${scan.edges.length} edges`);
29
+ console.log(` ${scan.changed.length} file(s) parsed, ${scan.skipped} unchanged, ` +
30
+ `${scan.unsupported} not a supported language`);
31
+ console.log(` ${Date.now() - started}ms (languages: ${languageNames()})`);
32
+ if (scan.symbols.length === 0 && scan.changed.length > 0) {
33
+ console.log(' Nothing was extracted, which usually means no supported source files.');
34
+ }
35
+ }
36
+ finally {
37
+ await ctx.close();
38
+ }
39
+ }
40
+ export async function cmdUsages(argv) {
41
+ const regex = argv.includes('--regex');
42
+ const path = valueOf(argv, '--path');
43
+ const context = Number(valueOf(argv, '--context') ?? 0);
44
+ const limit = Number(valueOf(argv, '--limit') ?? 100);
45
+ const mode = valueOf(argv, '--mode') ?? 'text';
46
+ const words = withoutFlags(argv, ['--path', '--context', '--limit', '--mode'])
47
+ .filter((arg) => arg !== '--regex')
48
+ .join(' ')
49
+ .trim();
50
+ if (!words) {
51
+ console.error('Usage: claude-db usages [--mode text|usages|explain|path] [--regex] ' +
52
+ '[--context <n>] [--path <dir>] [--limit <n>] <symbol> [<target>]');
53
+ process.exit(1);
54
+ }
55
+ if (!Number.isFinite(context) || context < 0) {
56
+ console.error('--context must be a non-negative number.');
57
+ process.exit(1);
58
+ }
59
+ if (!Number.isFinite(limit) || limit <= 0) {
60
+ console.error('--limit must be a positive number.');
61
+ process.exit(1);
62
+ }
63
+ if (mode === 'text') {
64
+ console.log(formatUsages(findUsages({ symbol: words, regex, context, limit, ...(path ? { path } : {}) })));
65
+ return;
66
+ }
67
+ if (mode !== 'usages' && mode !== 'explain' && mode !== 'path') {
68
+ console.error(`Unknown --mode "${mode}". Use text, usages, explain or path.`);
69
+ process.exit(1);
70
+ }
71
+ const [symbol, target] = words.split(/\s+/);
72
+ if (mode === 'path' && !target) {
73
+ console.error('--mode path needs two symbols: claude-db usages --mode path <from> <to>');
74
+ process.exit(1);
75
+ }
76
+ const root = repoRootFor(path ?? process.cwd());
77
+ const project = resolveProject(undefined);
78
+ const ctx = await createContext();
79
+ try {
80
+ const refreshed = await refreshGraph(ctx.store, root, project);
81
+ const answer = await queryGraph(ctx.store, project, {
82
+ mode,
83
+ symbol: symbol ?? '',
84
+ ...(target ? { target } : {}),
85
+ limit,
86
+ });
87
+ answer.refreshed = refreshed;
88
+ console.log(formatGraph(answer, root));
89
+ }
90
+ finally {
91
+ await ctx.close();
92
+ }
93
+ }
@@ -0,0 +1,3 @@
1
+ export declare function cmdStats(): Promise<void>;
2
+ export declare function cmdProjects(): Promise<void>;
3
+ export declare function cmdMerge(argv: (string | undefined)[]): Promise<void>;
@@ -0,0 +1,129 @@
1
+ import { createContext } from '../../context.js';
2
+ import { eachObservation } from '../commands/transfer.js';
3
+ import { resolve } from 'node:path';
4
+ import { resolveProject } from '../../util/project.js';
5
+ export async function cmdStats() {
6
+ const project = resolveProject(undefined);
7
+ const ctx = await createContext();
8
+ try {
9
+ const kinds = new Map();
10
+ const tags = new Map();
11
+ let embedded = 0;
12
+ let earliest = Number.POSITIVE_INFINITY;
13
+ let latest = 0;
14
+ const total = await eachObservation(ctx, { project }, (batch) => {
15
+ for (const obs of batch) {
16
+ kinds.set(obs.kind, (kinds.get(obs.kind) ?? 0) + 1);
17
+ for (const tag of obs.tags)
18
+ tags.set(tag, (tags.get(tag) ?? 0) + 1);
19
+ if (obs.embedding && obs.embedding.length > 0)
20
+ embedded += 1;
21
+ earliest = Math.min(earliest, obs.createdAt);
22
+ latest = Math.max(latest, obs.createdAt);
23
+ }
24
+ });
25
+ if (total === 0) {
26
+ console.log(`No memory stored for ${project}.`);
27
+ return;
28
+ }
29
+ const day = (ms) => new Date(ms).toISOString().slice(0, 10);
30
+ console.log(`project : ${project}`);
31
+ console.log(`observations: ${total}`);
32
+ console.log(`range : ${day(earliest)} to ${day(latest)}`);
33
+ console.log(`embedded : ${embedded} of ${total}`);
34
+ console.log('\nby kind');
35
+ for (const [kind, n] of [...kinds].sort((a, b) => b[1] - a[1])) {
36
+ console.log(` ${String(n).padStart(5)} ${kind}`);
37
+ }
38
+ if (tags.size > 0) {
39
+ console.log('\nby area');
40
+ for (const [tag, n] of [...tags].sort((a, b) => b[1] - a[1]).slice(0, 10)) {
41
+ console.log(` ${String(n).padStart(5)} ${tag}`);
42
+ }
43
+ }
44
+ }
45
+ finally {
46
+ await ctx.close();
47
+ }
48
+ }
49
+ export async function cmdProjects() {
50
+ const here = resolveProject(undefined);
51
+ const ctx = await createContext();
52
+ try {
53
+ const projects = await ctx.store.listProjects();
54
+ if (projects.length === 0) {
55
+ console.log('No memory stored yet.');
56
+ return;
57
+ }
58
+ console.log(`database: ${ctx.config.database}\n`);
59
+ for (const entry of projects) {
60
+ const marker = entry.project === here ? '*' : ' ';
61
+ const date = new Date(entry.lastActive).toISOString().slice(0, 10);
62
+ console.log(`${marker} ${String(entry.observations).padStart(5)} ${date} ${entry.project}`);
63
+ }
64
+ console.log('\n* is the project you are in now. Searches only ever see one row.');
65
+ }
66
+ finally {
67
+ await ctx.close();
68
+ }
69
+ }
70
+ export async function cmdMerge(argv) {
71
+ const into = resolveProject(undefined);
72
+ const confirmed = argv.includes('--yes') || argv.includes('-y');
73
+ const given = argv.find((arg) => typeof arg === 'string' && !arg.startsWith('-'));
74
+ const ctx = await createContext();
75
+ try {
76
+ if (!given) {
77
+ await listShards(ctx, into);
78
+ return;
79
+ }
80
+ const from = resolve(given);
81
+ if (from === into) {
82
+ console.error('Source and destination are the same project.');
83
+ process.exit(1);
84
+ }
85
+ let moved = 0;
86
+ const total = await eachObservation(ctx, { project: from }, async (batch) => {
87
+ if (!confirmed)
88
+ return;
89
+ await ctx.store.insertObservations(batch.map((obs) => ({ ...obs, project: into })));
90
+ moved += batch.length;
91
+ });
92
+ if (total === 0) {
93
+ console.error(`No memory stored under ${from}.`);
94
+ console.error('Run `claude-db projects` to see the exact paths in this database.');
95
+ process.exit(1);
96
+ }
97
+ if (!confirmed) {
98
+ console.log(`This would move ${total} observation(s):`);
99
+ console.log(` from ${from}`);
100
+ console.log(` into ${into}`);
101
+ console.log('\nNothing was moved. Re-run with --yes to confirm.');
102
+ return;
103
+ }
104
+ for (const session of await ctx.store.recentSessions(from, 1000)) {
105
+ await ctx.store.upsertSession({ ...session, project: into });
106
+ }
107
+ const swept = await ctx.store.remove({ project: from });
108
+ console.log(`Moved ${moved} observation(s) into ${into}.`);
109
+ if (swept > 0)
110
+ console.log(`Cleaned up ${swept} leftover row(s) under the old path.`);
111
+ }
112
+ finally {
113
+ await ctx.close();
114
+ }
115
+ }
116
+ async function listShards(ctx, into) {
117
+ const shards = (await ctx.store.listProjects()).filter((entry) => entry.project !== into && entry.project.startsWith(`${into}/`));
118
+ if (shards.length === 0) {
119
+ console.log(`No memory is stored under a subdirectory of ${into}.`);
120
+ console.log('Nothing to merge.');
121
+ return;
122
+ }
123
+ console.log(`Memory recorded under subdirectories of ${into}:\n`);
124
+ for (const shard of shards) {
125
+ console.log(` ${String(shard.observations).padStart(5)} ${shard.project}`);
126
+ }
127
+ console.log('\nMerge one in with:');
128
+ console.log(` claude-db merge ${shards[0]?.project} --yes`);
129
+ }
@@ -0,0 +1,3 @@
1
+ export declare function cmdReset(argv: (string | undefined)[]): Promise<void>;
2
+ export declare function cmdFlush(): Promise<void>;
3
+ export declare function cmdUpdate(argv: (string | undefined)[]): Promise<void>;
@@ -0,0 +1,77 @@
1
+ import { CONFIG_DIR, loadConfig } from '../../config/index.js';
2
+ import { basename, join } from 'node:path';
3
+ import { checkForUpdate } from '../../update.js';
4
+ import { createContext } from '../../context.js';
5
+ import { flushSession, resetCursor, sweepCursors, transcriptsFor } from '../../capture/index.js';
6
+ import { resolveProject } from '../../util/project.js';
7
+ import { rmSync } from 'node:fs';
8
+ export async function cmdReset(argv) {
9
+ const scoped = argv.includes('--project') || argv.includes('-p');
10
+ const confirmed = argv.includes('--yes') || argv.includes('-y');
11
+ const project = resolveProject(undefined);
12
+ const ctx = await createContext();
13
+ try {
14
+ const target = scoped ? project : ctx.config.database;
15
+ if (!confirmed) {
16
+ console.log(`This would delete ${scoped ? "this project's" : 'ALL'} memory from:`);
17
+ console.log(` ${target}`);
18
+ console.log('\nNothing was deleted. Re-run with --yes to confirm.');
19
+ return;
20
+ }
21
+ const deleted = await ctx.store.remove(scoped ? { project } : {});
22
+ console.log(`Deleted ${deleted} observation(s) from ${target}.`);
23
+ if (!scoped) {
24
+ clearLocalState();
25
+ console.log('Cleared transcript cursors so the next flush starts clean.');
26
+ }
27
+ }
28
+ finally {
29
+ await ctx.close();
30
+ }
31
+ }
32
+ function clearLocalState() {
33
+ rmSync(join(CONFIG_DIR, 'cursors'), { recursive: true, force: true });
34
+ }
35
+ export async function cmdFlush() {
36
+ const project = resolveProject(undefined);
37
+ const transcripts = transcriptsFor(project);
38
+ if (transcripts.length === 0) {
39
+ console.error(`No transcripts found for ${project}`);
40
+ process.exit(1);
41
+ }
42
+ const ctx = await createContext();
43
+ let total = 0;
44
+ try {
45
+ for (const path of transcripts) {
46
+ const sessionId = basename(path, '.jsonl');
47
+ resetCursor(sessionId);
48
+ const result = await flushSession(ctx, sessionId, project, path, true);
49
+ if (result.observations > 0) {
50
+ console.log(`${sessionId.slice(0, 8)} ${String(result.observations).padStart(4)} observations`);
51
+ total += result.observations;
52
+ }
53
+ }
54
+ }
55
+ finally {
56
+ await ctx.close();
57
+ }
58
+ console.log(`\n${total} observations from ${transcripts.length} transcript(s).`);
59
+ const swept = sweepCursors();
60
+ if (swept > 0)
61
+ console.log(`Swept ${swept} cursor(s) for transcripts that no longer exist.`);
62
+ }
63
+ export async function cmdUpdate(argv) {
64
+ const quiet = argv.includes('--quiet');
65
+ const config = loadConfig();
66
+ const mode = quiet ? config.updates : 'auto';
67
+ const result = await checkForUpdate(mode);
68
+ if (quiet)
69
+ return;
70
+ if (result.installed)
71
+ console.log(`Updated ${result.current} -> ${result.latest}.`);
72
+ else if (result.latest && result.latest !== result.current) {
73
+ console.log(`${result.latest} is available (running ${result.current}): ${result.reason}`);
74
+ }
75
+ else
76
+ console.log(`Up to date (${result.current}).`);
77
+ }
@@ -0,0 +1,3 @@
1
+ export declare function cmdSearch(argv: (string | undefined)[]): Promise<void>;
2
+ export declare function cmdRemember(argv: (string | undefined)[]): Promise<void>;
3
+ export declare function cmdForget(argv: (string | undefined)[]): Promise<void>;