claude-db 0.2.2 → 0.3.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 (39) hide show
  1. package/README.md +16 -4
  2. package/dist/capture/flush.d.ts +20 -1
  3. package/dist/capture/flush.js +45 -5
  4. package/dist/capture/git.d.ts +2 -0
  5. package/dist/capture/git.js +96 -0
  6. package/dist/capture/index.d.ts +4 -3
  7. package/dist/capture/index.js +4 -3
  8. package/dist/capture/manual.d.ts +9 -0
  9. package/dist/capture/manual.js +0 -0
  10. package/dist/capture/transcript.d.ts +8 -0
  11. package/dist/capture/transcript.js +30 -0
  12. package/dist/capture/turn-extractor.d.ts +9 -1
  13. package/dist/capture/turn-extractor.js +74 -13
  14. package/dist/cli/index.js +409 -27
  15. package/dist/cli/install.d.ts +8 -0
  16. package/dist/cli/install.js +24 -0
  17. package/dist/config/schema.d.ts +5 -0
  18. package/dist/config/schema.js +12 -0
  19. package/dist/hooks/session-end.js +15 -0
  20. package/dist/hooks/session-start.js +5 -0
  21. package/dist/mcp/render.d.ts +23 -0
  22. package/dist/mcp/render.js +49 -0
  23. package/dist/mcp/server.d.ts +1 -7
  24. package/dist/mcp/server.js +37 -36
  25. package/dist/store/adapter.d.ts +10 -0
  26. package/dist/store/adapter.js +8 -0
  27. package/dist/store/mongo/index.d.ts +1 -0
  28. package/dist/store/mongo/index.js +34 -3
  29. package/dist/store/postgres/index.d.ts +15 -0
  30. package/dist/store/postgres/index.js +89 -4
  31. package/dist/store/sqlite/index.d.ts +1 -0
  32. package/dist/store/sqlite/index.js +32 -2
  33. package/dist/types.d.ts +16 -0
  34. package/dist/update.d.ts +38 -0
  35. package/dist/update.js +144 -0
  36. package/dist/util/snippet.d.ts +28 -0
  37. package/dist/util/snippet.js +52 -0
  38. package/package.json +2 -1
  39. package/skills/cdb-scan/SKILL.md +72 -0
@@ -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,38 @@
1
+ export interface UpdateState {
2
+ /** When the registry was last asked. */
3
+ checkedAt?: number;
4
+ /** Newest version the registry reported. */
5
+ latest?: string;
6
+ /** Version we installed ourselves, so the next session can mention it. */
7
+ installed?: string;
8
+ }
9
+ export declare function packageVersion(): string;
10
+ export declare function readState(): UpdateState;
11
+ export declare function isDue(state: UpdateState, now?: number): boolean;
12
+ /** -1, 0 or 1. Numeric per segment, so 0.2.10 beats 0.2.9. */
13
+ export declare function compareVersions(a: string, b: string): number;
14
+ /**
15
+ * Caret semantics: 1.x may take any 1.y.z, but 0.2.x may only take 0.2.z.
16
+ *
17
+ * A release outside this range is allowed to change the database schema or the
18
+ * config, and `init()` migrates on first connection — so installing one without
19
+ * being asked would rewrite a user's database on their behalf. Those are
20
+ * reported and left for a human.
21
+ */
22
+ export declare function isCompatible(current: string, candidate: string): boolean;
23
+ export interface UpdateResult {
24
+ current: string;
25
+ latest: string | null;
26
+ installed: boolean;
27
+ reason?: string;
28
+ }
29
+ /**
30
+ * Asks the registry, and installs when configured to.
31
+ *
32
+ * Only ever called from a detached process, never inline: the check is network
33
+ * bound and `npm install -g` replaces the very files the hooks import, so
34
+ * neither belongs anywhere near the prompt path.
35
+ */
36
+ export declare function checkForUpdate(mode: 'auto' | 'notify' | 'off'): Promise<UpdateResult>;
37
+ /** One line for the session banner, or null when there is nothing to say. */
38
+ export declare function updateNotice(): string | null;
package/dist/update.js ADDED
@@ -0,0 +1,144 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
3
+ import { dirname, join, resolve } from 'node:path';
4
+ import { fileURLToPath } from 'node:url';
5
+ import { CONFIG_DIR } from './config/index.js';
6
+ const STATE_PATH = join(CONFIG_DIR, 'update.json');
7
+ const REGISTRY = 'https://registry.npmjs.org/claude-db/latest';
8
+ const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
9
+ export function packageVersion() {
10
+ try {
11
+ const path = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
12
+ return JSON.parse(readFileSync(path, 'utf8')).version ?? '0.0.0';
13
+ }
14
+ catch {
15
+ return '0.0.0';
16
+ }
17
+ }
18
+ export function readState() {
19
+ try {
20
+ return JSON.parse(readFileSync(STATE_PATH, 'utf8'));
21
+ }
22
+ catch {
23
+ return {};
24
+ }
25
+ }
26
+ function writeState(state) {
27
+ try {
28
+ mkdirSync(CONFIG_DIR, { recursive: true });
29
+ writeFileSync(STATE_PATH, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
30
+ }
31
+ catch {
32
+ // A lost state file only costs one redundant check.
33
+ }
34
+ }
35
+ export function isDue(state, now = Date.now()) {
36
+ return now - (state.checkedAt ?? 0) > CHECK_INTERVAL_MS;
37
+ }
38
+ /** -1, 0 or 1. Numeric per segment, so 0.2.10 beats 0.2.9. */
39
+ export function compareVersions(a, b) {
40
+ const left = a.split('.').map((part) => Number.parseInt(part, 10) || 0);
41
+ const right = b.split('.').map((part) => Number.parseInt(part, 10) || 0);
42
+ for (let i = 0; i < 3; i += 1) {
43
+ const diff = (left[i] ?? 0) - (right[i] ?? 0);
44
+ if (diff !== 0)
45
+ return diff > 0 ? 1 : -1;
46
+ }
47
+ return 0;
48
+ }
49
+ /**
50
+ * Caret semantics: 1.x may take any 1.y.z, but 0.2.x may only take 0.2.z.
51
+ *
52
+ * A release outside this range is allowed to change the database schema or the
53
+ * config, and `init()` migrates on first connection — so installing one without
54
+ * being asked would rewrite a user's database on their behalf. Those are
55
+ * reported and left for a human.
56
+ */
57
+ export function isCompatible(current, candidate) {
58
+ const [curMajor = 0, curMinor = 0] = current.split('.').map(Number);
59
+ const [newMajor = 0, newMinor = 0] = candidate.split('.').map(Number);
60
+ return curMajor === 0 ? curMajor === newMajor && curMinor === newMinor : curMajor === newMajor;
61
+ }
62
+ /**
63
+ * No abbreviated-packument accept header here: that format applies to the full
64
+ * document, and asking for it on /latest returns 406. With the header this
65
+ * check never once succeeded, and reported "up to date" while failing.
66
+ */
67
+ async function fetchLatest() {
68
+ try {
69
+ const res = await fetch(REGISTRY, { signal: AbortSignal.timeout(5000) });
70
+ if (!res.ok)
71
+ return null;
72
+ const body = (await res.json());
73
+ return typeof body.version === 'string' ? body.version : null;
74
+ }
75
+ catch {
76
+ return null;
77
+ }
78
+ }
79
+ /**
80
+ * Asks the registry, and installs when configured to.
81
+ *
82
+ * Only ever called from a detached process, never inline: the check is network
83
+ * bound and `npm install -g` replaces the very files the hooks import, so
84
+ * neither belongs anywhere near the prompt path.
85
+ */
86
+ export async function checkForUpdate(mode) {
87
+ const current = packageVersion();
88
+ if (mode === 'off')
89
+ return { current, latest: null, installed: false, reason: 'disabled' };
90
+ const latest = await fetchLatest();
91
+ const state = { ...readState(), checkedAt: Date.now() };
92
+ if (latest)
93
+ state.latest = latest;
94
+ // A failed check is not the same as being current, and saying so is what
95
+ // stops a broken updater from looking like a healthy one forever.
96
+ if (!latest) {
97
+ writeState(state);
98
+ return { current, latest: null, installed: false, reason: 'could not reach the registry' };
99
+ }
100
+ if (compareVersions(latest, current) <= 0) {
101
+ writeState(state);
102
+ return { current, latest, installed: false, reason: 'up to date' };
103
+ }
104
+ if (mode === 'notify') {
105
+ writeState(state);
106
+ return { current, latest, installed: false, reason: 'notify only' };
107
+ }
108
+ if (!isCompatible(current, latest)) {
109
+ writeState(state);
110
+ return { current, latest, installed: false, reason: 'not a compatible release' };
111
+ }
112
+ try {
113
+ execFileSync('npm', ['install', '-g', `claude-db@${latest}`], {
114
+ stdio: 'ignore',
115
+ timeout: 120_000,
116
+ });
117
+ writeState({ ...state, installed: latest });
118
+ return { current, latest, installed: true };
119
+ }
120
+ catch (error) {
121
+ writeState(state);
122
+ return {
123
+ current,
124
+ latest,
125
+ installed: false,
126
+ reason: error instanceof Error ? error.message.split('\n')[0] ?? 'install failed' : 'install failed',
127
+ };
128
+ }
129
+ }
130
+ /** One line for the session banner, or null when there is nothing to say. */
131
+ export function updateNotice() {
132
+ const state = readState();
133
+ const current = packageVersion();
134
+ if (state.installed && compareVersions(state.installed, current) <= 0) {
135
+ // We are running it now, so say so once and forget it.
136
+ const { installed: _done, ...rest } = state;
137
+ writeState(rest);
138
+ return `claude-db updated to ${current}.`;
139
+ }
140
+ if (state.latest && compareVersions(state.latest, current) > 0) {
141
+ return `claude-db ${state.latest} is available (running ${current}): npm i -g claude-db`;
142
+ }
143
+ return null;
144
+ }
@@ -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.2",
3
+ "version": "0.3.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.