claude-db 0.2.3 → 0.4.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.
@@ -2,9 +2,10 @@ import { DatabaseSync } from 'node:sqlite';
2
2
  import { mkdirSync, readFileSync } from 'node:fs';
3
3
  import { dirname, resolve } from 'node:path';
4
4
  import { fileURLToPath } from 'node:url';
5
- import { isWholeScope } from '../adapter.js';
5
+ import { foreignNames, isWholeScope } from '../adapter.js';
6
6
  import { cosine, packVector, unpackVector } from '../../util/vector.js';
7
7
  import { scopeToken } from '../../util/scope.js';
8
+ import { toSnippet } from '../../util/snippet.js';
8
9
  import { partitionIds } from '../../util/shortid.js';
9
10
  const HERE = dirname(fileURLToPath(import.meta.url));
10
11
  /**
@@ -184,6 +185,13 @@ export class SqliteStore {
184
185
  lastActive: Number(row['last']),
185
186
  }));
186
187
  }
188
+ async inventory() {
189
+ const rows = this.db
190
+ .prepare(`SELECT name FROM sqlite_master
191
+ WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'`)
192
+ .all();
193
+ return foreignNames(rows.map((row) => String(row['name'] ?? '')));
194
+ }
187
195
  async searchKeyword(query) {
188
196
  // The project constraint goes inside the MATCH expression, not the WHERE
189
197
  // clause. Filtering after the match makes FTS5 rank every project's
@@ -198,6 +206,10 @@ export class SqliteStore {
198
206
  conditions.push('o.kind = ?');
199
207
  params.push(query.kind);
200
208
  }
209
+ if (query.tag) {
210
+ conditions.push(TAG_PREDICATE('o.'));
211
+ params.push(query.tag);
212
+ }
201
213
  if (query.since !== undefined) {
202
214
  conditions.push('o.created_at >= ?');
203
215
  params.push(query.since);
@@ -211,8 +223,13 @@ export class SqliteStore {
211
223
  // weights (title, body, tags, scope) make a hit in the one-sentence claim
212
224
  // outrank the same word buried in a long body; scope carries no weight
213
225
  // because it is a filter, not a relevance signal.
226
+ // snippet() over column 1 (body) returns the matched fragment, which is
227
+ // what makes a result choosable without expanding it. Markers are empty
228
+ // because the fragment itself is the signal; single-quoted, since SQLite
229
+ // reads a double-quoted literal as an identifier.
214
230
  const rows = this.db
215
231
  .prepare(`SELECT o.id, o.kind, o.title, o.project, o.created_at,
232
+ snippet(observations_fts, 1, '', '', '…', 14) AS snippet,
216
233
  -bm25(observations_fts, 10.0, 1.0, 5.0, 0.0) AS score
217
234
  FROM observations_fts
218
235
  JOIN observations o ON o.rowid = observations_fts.rowid
@@ -311,6 +328,11 @@ function removeWhere(filter) {
311
328
  params,
312
329
  };
313
330
  }
331
+ /**
332
+ * Exact membership in the stored JSON array, rather than a LIKE over the raw
333
+ * text, so `api` cannot match `api-docs` and a tag containing `%` is harmless.
334
+ */
335
+ const TAG_PREDICATE = (prefix) => `EXISTS (SELECT 1 FROM json_each(${prefix}tags) WHERE value = ?)`;
314
336
  function appendScope(query, conditions, params, prefix) {
315
337
  if (query.project) {
316
338
  conditions.push(`${prefix}project = ?`);
@@ -320,6 +342,10 @@ function appendScope(query, conditions, params, prefix) {
320
342
  conditions.push(`${prefix}kind = ?`);
321
343
  params.push(query.kind);
322
344
  }
345
+ if (query.tag) {
346
+ conditions.push(TAG_PREDICATE(prefix));
347
+ params.push(query.tag);
348
+ }
323
349
  if (query.since !== undefined) {
324
350
  conditions.push(`${prefix}created_at >= ?`);
325
351
  params.push(query.since);
@@ -401,7 +427,7 @@ function toObservation(row) {
401
427
  return obs;
402
428
  }
403
429
  function toIndexEntry(row) {
404
- return {
430
+ const entry = {
405
431
  id: row['id'],
406
432
  kind: row['kind'],
407
433
  title: row['title'],
@@ -409,4 +435,8 @@ function toIndexEntry(row) {
409
435
  createdAt: Number(row['created_at']),
410
436
  score: Number(row['score'] ?? 0),
411
437
  };
438
+ const snippet = toSnippet(row['snippet']);
439
+ if (snippet)
440
+ entry.snippet = snippet;
441
+ return entry;
412
442
  }
package/dist/types.d.ts CHANGED
@@ -40,11 +40,27 @@ export interface ObservationIndexEntry {
40
40
  project: string;
41
41
  createdAt: number;
42
42
  score: number;
43
+ /**
44
+ * A line of the body around the match, so a result can be chosen without
45
+ * being expanded first. Produced by the keyword retriever, which is the only
46
+ * one with query terms to centre on; a row found by vector similarity alone
47
+ * has none.
48
+ */
49
+ snippet?: string;
43
50
  }
44
51
  export interface SearchQuery {
45
52
  text: string;
46
53
  project?: string;
47
54
  kind?: ObservationKind;
55
+ /**
56
+ * Narrows to observations touching one repository or top-level directory.
57
+ *
58
+ * A workspace that pools several repositories under one project key gets a
59
+ * memory covering all of them, and "the backend only" is a natural thing to
60
+ * ask that could not be expressed: tags were recorded and ranked, but never
61
+ * filtered on.
62
+ */
63
+ tag?: string;
48
64
  since?: number;
49
65
  until?: number;
50
66
  limit: number;
@@ -0,0 +1,29 @@
1
+ export interface UsageMatch {
2
+ file: string;
3
+ line: number;
4
+ text: string;
5
+ isDefinition: boolean;
6
+ }
7
+ export interface UsagesResult {
8
+ root: string;
9
+ matches: UsageMatch[];
10
+ total: number;
11
+ truncated: boolean;
12
+ }
13
+ export interface FindUsagesInput {
14
+ symbol: string;
15
+ path?: string;
16
+ regex: boolean;
17
+ context: number;
18
+ limit: number;
19
+ }
20
+ /**
21
+ * Live `git grep`, never a persisted index.
22
+ *
23
+ * A symbol index that drifts from an edit is the same failure shape as every
24
+ * silent-staleness bug this project has already shipped and fixed. This
25
+ * re-derives the answer from the current source on every call, so there is
26
+ * nothing to invalidate.
27
+ */
28
+ export declare function findUsages(input: FindUsagesInput): UsagesResult;
29
+ export declare function formatUsages(result: UsagesResult): string;
@@ -0,0 +1,115 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { resolve } from 'node:path';
3
+ // A hit here means the term is too generic to be a symbol lookup at all; the
4
+ // fix is a narrower query, not a bigger buffer.
5
+ const MAX_BUFFER = 16 * 1024 * 1024;
6
+ /**
7
+ * Live `git grep`, never a persisted index.
8
+ *
9
+ * A symbol index that drifts from an edit is the same failure shape as every
10
+ * silent-staleness bug this project has already shipped and fixed. This
11
+ * re-derives the answer from the current source on every call, so there is
12
+ * nothing to invalidate.
13
+ */
14
+ export function findUsages(input) {
15
+ const root = repoRootFor(input.path);
16
+ const args = buildArgs(input);
17
+ let raw;
18
+ try {
19
+ raw = execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: MAX_BUFFER });
20
+ }
21
+ catch (error) {
22
+ const err = error;
23
+ // git grep exits 1 for "ran fine, found nothing" — not an error.
24
+ if (err.status === 1)
25
+ return { root, matches: [], total: 0, truncated: false };
26
+ if (/maxBuffer/i.test(err.message)) {
27
+ throw new Error(`too many matches for "${input.symbol}" to read at once — narrow it ` +
28
+ '(a longer name, --path to a subdirectory, or --regex to anchor it tighter)');
29
+ }
30
+ throw new Error((err.stderr ?? err.message).trim().split('\n')[0]);
31
+ }
32
+ const parsed = parseGrepOutput(raw).map((row) => ({
33
+ ...row,
34
+ isDefinition: isDefinitionLike(input.symbol, row.text),
35
+ }));
36
+ return {
37
+ root,
38
+ matches: parsed.slice(0, input.limit),
39
+ total: parsed.length,
40
+ truncated: parsed.length > input.limit,
41
+ };
42
+ }
43
+ /**
44
+ * Deliberately not resolveProject(): that widens to the repository root for
45
+ * MEMORY partitioning, and inside a workspace pooling several sibling repos
46
+ * it can resolve to a directory that is not itself a git working tree, which
47
+ * `git grep` cannot search at all. Delegating to git's own discovery keeps
48
+ * this in sync with whatever repo git itself would act on (worktrees,
49
+ * submodules, symlinks included) without a second implementation of the walk.
50
+ */
51
+ function repoRootFor(path) {
52
+ const start = resolve(path ?? process.cwd());
53
+ try {
54
+ return execFileSync('git', ['-C', start, 'rev-parse', '--show-toplevel'], {
55
+ encoding: 'utf8',
56
+ }).trim();
57
+ }
58
+ catch (error) {
59
+ const stderr = error.stderr?.trim();
60
+ throw new Error(`${start} is not inside a git working tree${stderr ? ` (${stderr})` : ''}`);
61
+ }
62
+ }
63
+ function buildArgs({ symbol, regex, context }) {
64
+ // -I: skip binary files — a binary hit otherwise prints a headerless
65
+ // "Binary file X matches" line that corrupts the -z parse below.
66
+ // --untracked: a brand-new file the agent just created and has not `git
67
+ // add`ed yet is exactly the blast-radius case this tool exists for; without
68
+ // this flag it is silently invisible. Still respects .gitignore.
69
+ const args = ['grep', '-n', '-z', '-I', '--untracked'];
70
+ if (context > 0)
71
+ args.push(`-B${context}`, `-A${context}`);
72
+ // Word-regexp only in literal mode: a regex author already controls their
73
+ // own boundaries, so imposing one on top would be a surprise, not a safety net.
74
+ args.push(...(regex ? ['--extended-regexp'] : ['--fixed-strings', '--word-regexp']));
75
+ args.push('-e', symbol);
76
+ return args;
77
+ }
78
+ /** `-z` NUL-delimits path\0line\0content per record; a stray line with no
79
+ * NUL (a `--` context divider, a binary-match notice) is simply dropped. */
80
+ function parseGrepOutput(raw) {
81
+ const rows = [];
82
+ for (const record of raw.split('\n')) {
83
+ if (!record.includes('\0'))
84
+ continue;
85
+ const [file, lineStr, ...rest] = record.split('\0');
86
+ const line = Number(lineStr);
87
+ if (!file || !Number.isFinite(line))
88
+ continue;
89
+ rows.push({ file, line, text: rest.join('\0') });
90
+ }
91
+ return rows;
92
+ }
93
+ /**
94
+ * Cheap, best-effort "this looks like the declaration" marker. Unlike
95
+ * classifyTurn's `because` regression, this never hides or filters a line —
96
+ * it only annotates one already-shown line, so a false positive costs a
97
+ * wrong label, not a silently misfiled result.
98
+ */
99
+ function isDefinitionLike(symbol, text) {
100
+ const s = symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
101
+ return new RegExp(`\\b(function\\*?\\s+${s}\\b` +
102
+ `|class\\s+${s}\\b` +
103
+ `|(?:interface|type|enum)\\s+${s}\\b` +
104
+ `|(?:export\\s+)?(?:const|let|var)\\s+${s}\\s*[:=]` +
105
+ `|export\\s*\\{[^}]*\\b${s}\\b)`).test(text);
106
+ }
107
+ export function formatUsages(result) {
108
+ if (result.matches.length === 0)
109
+ return `No usages of that symbol found under ${result.root}.`;
110
+ const rows = result.matches.map((m) => `${m.file}:${m.line}${m.isDefinition ? ' [definition?]' : ''} ${m.text.trim()}`);
111
+ const header = result.truncated
112
+ ? `showing ${result.matches.length} of ${result.total}+ match(es) (raise \`limit\` or narrow \`symbol\`):`
113
+ : `${result.total} match(es):`;
114
+ return `${header}\n${rows.join('\n')}`;
115
+ }
@@ -0,0 +1,2 @@
1
+ export { findUsages, formatUsages } from './find.js';
2
+ export type { FindUsagesInput, UsagesResult, UsageMatch } from './find.js';
@@ -0,0 +1 @@
1
+ export { findUsages, formatUsages } from './find.js';
@@ -0,0 +1,28 @@
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
+ 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
+ export declare function clipBody(body: string, max: number): string;
@@ -0,0 +1,52 @@
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
+ 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
+ export function toSnippet(text, max = SNIPPET_MAX) {
20
+ if (typeof text !== 'string')
21
+ 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
+ const flat = text
27
+ .replace(/<\/?b>/g, '')
28
+ .replace(/[|`*]+/g, ' ')
29
+ .replace(/\s+/g, ' ')
30
+ .trim();
31
+ if (flat.length === 0)
32
+ return undefined;
33
+ if (flat.length <= max)
34
+ return flat;
35
+ const cut = flat.slice(0, max);
36
+ const word = cut.lastIndexOf(' ');
37
+ return `${cut.slice(0, word > max * 0.6 ? word : max)}…`;
38
+ }
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
+ export function clipBody(body, max) {
49
+ if (body.length <= max)
50
+ return body;
51
+ return `${body.slice(0, max)}\n… ${body.length - max} more characters (raise \`chars\` to read them)`;
52
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-db",
3
- "version": "0.2.3",
3
+ "version": "0.4.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",
@@ -16,6 +16,7 @@
16
16
  },
17
17
  "files": [
18
18
  "dist",
19
+ "skills",
19
20
  "README.md",
20
21
  "LICENSE"
21
22
  ],
@@ -0,0 +1,72 @@
1
+ ---
2
+ name: cdb-scan
3
+ description: Survey this codebase once and store a profile of it in project memory — stack, layout, conventions, workflows. Re-run any time to refresh it in place. Use when memory is newly installed on an existing project, or when the project has changed enough that the stored profile is stale.
4
+ ---
5
+
6
+ # Survey this project into memory
7
+
8
+ Everything else in claude-db's memory is testimony: it records what happened,
9
+ turn by turn, as it happened. A fresh install knows none of that, and stays
10
+ useless for weeks while it fills up.
11
+
12
+ This fills the gap from the one source available on day one — the code itself.
13
+ What you write here is **your reading of the codebase, not a record of events**,
14
+ so it is tagged `inferred` and must never be phrased as history.
15
+
16
+ ## How to run it
17
+
18
+ Work through the sections below in order. For each one, look at the actual
19
+ files, then call the `remember` MCP tool once with the given `key`.
20
+
21
+ `key` is what makes this re-runnable: writing the same key again replaces that
22
+ note rather than adding a second copy. Use these exact keys, and always pass
23
+ `tags: ["inferred"]` and `kind: "context"`.
24
+
25
+ Before you start, call `search` for `profile` in this project. If notes already
26
+ exist, read them first and update what changed rather than restating it — a
27
+ second run should be an edit, not a rewrite.
28
+
29
+ ### 1. `profile:stack`
30
+
31
+ Languages, runtime and version floors, frameworks, package manager, database,
32
+ test runner, build tool. Read the manifest (`package.json`, `pyproject.toml`,
33
+ `go.mod`, `Cargo.toml`) and the lockfile rather than guessing. Name versions
34
+ where a version constrains what can be written.
35
+
36
+ ### 2. `profile:layout`
37
+
38
+ The directory map, one line each, and what lives where. Include the entry
39
+ points: the binary, the server, the main export. Skip anything generated.
40
+
41
+ ### 3. `profile:conventions`
42
+
43
+ How this codebase is written, taken from the code and not from a style guide:
44
+ module system, import style, error handling, naming, comment density, how
45
+ tests are structured. Note where the project deviates from the language default,
46
+ since that is what someone would otherwise get wrong.
47
+
48
+ ### 4. `profile:workflows`
49
+
50
+ The commands that matter — install, build, test, lint, run, release — and
51
+ anything non-obvious about running them: a required service, an environment
52
+ variable, a step that must come first. Take them from the manifest scripts and
53
+ CI config, not from the README's aspirations.
54
+
55
+ ### 5. `profile:architecture`
56
+
57
+ Only the parts a newcomer could not infer from the layout: the main
58
+ abstractions and how a request or a command actually flows through them. Two
59
+ paragraphs at most. If the codebase is small enough that the layout says it
60
+ all, skip this section rather than padding it.
61
+
62
+ ## Rules
63
+
64
+ - **One `remember` call per section.** Five notes, five stable keys.
65
+ - **Write claims, not headings.** "Storage is one `MemoryStore` interface with
66
+ three adapters, selected by URI scheme" — not "Storage architecture".
67
+ - **Say what you verified.** If something was not read, leave it out. An
68
+ inferred profile that is confidently wrong is worse than a short one.
69
+ - **Never restate `CLAUDE.md`.** That file is already in the system prompt on
70
+ every turn. Memory is for what is not.
71
+ - **Do not record secrets, credentials or personal data**, even if the code
72
+ contains them.