claude-db 0.3.0 → 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.
package/README.md CHANGED
@@ -94,6 +94,7 @@ Ran: Test run: pnpm test
94
94
  | `claude-db remember [--key <name>] <text>` | Record a rule outright, e.g. "always use pnpm here" |
95
95
  | `claude-db forget <id>` | Delete specific observations by id |
96
96
  | `claude-db seed --from-git` | Fill a cold memory from this repo's history |
97
+ | `claude-db usages [--regex] <symbol>` | Find real usages via `git grep`, live — not a stored index |
97
98
  | `claude-db stats` | What this project's memory is made of |
98
99
  | `claude-db projects` | Every project with memory stored |
99
100
  | `claude-db merge [<path>]` | Move memory from an old project path onto this one |
package/dist/cli/index.js CHANGED
@@ -4,6 +4,7 @@ import { readFileSync, rmSync, statSync } from 'node:fs';
4
4
  import { basename, dirname, join, resolve } from 'node:path';
5
5
  import { fileURLToPath } from 'node:url';
6
6
  import { embedObservations, flushSession, remember, observationsFromGit, redact, resetCursor, sweepCursors, transcriptsFor, } from '../capture/index.js';
7
+ import { findUsages, formatUsages } from '../usages/index.js';
7
8
  import { createContext } from '../context.js';
8
9
  import { createStore } from '../store/index.js';
9
10
  import { CONFIG_DIR, CONFIG_PATH, loadConfig, saveConfig } from '../config/index.js';
@@ -95,6 +96,9 @@ async function run() {
95
96
  case 'seed':
96
97
  await cmdSeed(args);
97
98
  break;
99
+ case 'usages':
100
+ await cmdUsages(args);
101
+ break;
98
102
  case 'sync':
99
103
  await cmdSync(args);
100
104
  break;
@@ -149,6 +153,38 @@ async function cmdSeed(argv) {
149
153
  console.log(`Seeded ${observations.length} observation(s) from git history.`);
150
154
  console.log(`Oldest: ${new Date(observations[observations.length - 1]?.createdAt ?? 0).toISOString().slice(0, 10)}`);
151
155
  }
156
+ /**
157
+ * Live `git grep`, not a database lookup — the only command with no
158
+ * `createContext()` call, since it touches no store and no embedder.
159
+ *
160
+ * Never a persisted index: this project has already shipped three
161
+ * silent-staleness bugs, and a symbol index that drifts from an edit is the
162
+ * same failure shape. Re-deriving the answer from the current source on every
163
+ * call means there is nothing to invalidate.
164
+ */
165
+ async function cmdUsages(argv) {
166
+ const regex = argv.includes('--regex');
167
+ const path = valueOf(argv, '--path');
168
+ const context = Number(valueOf(argv, '--context') ?? 0);
169
+ const limit = Number(valueOf(argv, '--limit') ?? 100);
170
+ const symbol = withoutFlags(argv, ['--path', '--context', '--limit'])
171
+ .filter((arg) => arg !== '--regex')
172
+ .join(' ')
173
+ .trim();
174
+ if (!symbol) {
175
+ console.error('Usage: claude-db usages [--regex] [--context <n>] [--path <dir>] [--limit <n>] <symbol>');
176
+ process.exit(1);
177
+ }
178
+ if (!Number.isFinite(context) || context < 0) {
179
+ console.error('--context must be a non-negative number.');
180
+ process.exit(1);
181
+ }
182
+ if (!Number.isFinite(limit) || limit <= 0) {
183
+ console.error('--limit must be a positive number.');
184
+ process.exit(1);
185
+ }
186
+ console.log(formatUsages(findUsages({ symbol, regex, context, limit, ...(path ? { path } : {}) })));
187
+ }
152
188
  /**
153
189
  * Two-way merge with another database.
154
190
  *
@@ -1102,6 +1138,8 @@ function usage() {
1102
1138
  stats What this project's memory is made of
1103
1139
  flush Re-ingest every transcript for this project
1104
1140
  seed --from-git [--limit n] Fill a cold memory from this repo's history
1141
+ usages [--regex] <symbol> Find real usages via git grep, current source only
1142
+ [--context n] [--path <dir>] [--limit n]
1105
1143
  export [--all] > out.jsonl Dump memory as JSONL, for backup or migration
1106
1144
  import <file.jsonl> Load a dump back in (safe to repeat)
1107
1145
  sync <url> [--yes] Two-way merge with another database
@@ -74,6 +74,13 @@ const INSTRUCTIONS = [
74
74
  'Verifying against the code afterwards is right — memory records what was',
75
75
  'done, the source shows what is. Starting there is what wastes the memory.',
76
76
  '',
77
+ '`search` covers *why*: past decisions, bugs, reasoning. It does not know',
78
+ '*where* something is used right now — for that, call `find_usages` instead',
79
+ 'of grepping yourself, specifically before editing or removing a shared or',
80
+ 'exported name, and when asked what uses something. It re-derives the answer',
81
+ 'from the current source on every call, so it is never stale. Plain-text or',
82
+ 'log searching is still a job for grep.',
83
+ '',
77
84
  'When the user states a standing rule or preference, record it with',
78
85
  '`remember` so it survives this session.',
79
86
  BLOCK_END,
@@ -26,11 +26,40 @@ export function renderIndex(entries) {
26
26
  const date = new Date(entry.createdAt).toISOString().slice(5, 10);
27
27
  const head = `${toShortId(entry.id)} ${entry.kind} ${date} ${entry.title}`;
28
28
  // Absent for a row only vector search found: it holds no query terms to
29
- // centre a fragment on.
30
- return entry.snippet ? `${head}\n ${entry.snippet}` : head;
29
+ // centre a fragment on. Dropped too when it only restates the title.
30
+ const worth = entry.snippet !== undefined && !echoesTitle(entry.snippet, entry.title);
31
+ return worth ? `${head}\n ${entry.snippet}` : head;
31
32
  });
32
33
  return `${entries.length} result(s):\n${rows.join('\n')}`;
33
34
  }
35
+ /** Lowercased alphanumeric runs — the only form the two sides share. */
36
+ function words(text) {
37
+ return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
38
+ }
39
+ /**
40
+ * True when a fragment says little the title has not already said.
41
+ *
42
+ * A search engine centres its window on the query match, and the title is taken
43
+ * from the body, so on a short observation the two are frequently the same
44
+ * sentence — the row then pays a second time for a line already shown. Observed
45
+ * live: a title of "Added as section 3 of PLAN.md, with the later sections
46
+ * renumbered" under a fragment reading "…Added as section 3 of [PLAN.md](PLAN.md),
47
+ * with the later…".
48
+ *
49
+ * Compared as a bag of words rather than by substring, because that example is
50
+ * exactly the case a substring test misses: the fragment comes from the raw body
51
+ * and still carries the markdown the title had stripped.
52
+ */
53
+ function echoesTitle(snippet, title) {
54
+ const tokens = words(snippet);
55
+ if (tokens.length === 0)
56
+ return true;
57
+ const inTitle = new Set(words(title));
58
+ const shared = tokens.filter((word) => inTitle.has(word)).length;
59
+ // Not 1.0: the window carries the ellipses and a spill word or two from the
60
+ // neighbouring sentence, so an exact echo never scores as one.
61
+ return shared / tokens.length >= 0.7;
62
+ }
34
63
  /** Layer 3. Full detail for one observation, bounded by `chars`. */
35
64
  export function renderFull(obs, chars) {
36
65
  return [
@@ -10,6 +10,7 @@ import { createContext } from '../context.js';
10
10
  import { toShortId } from '../util/shortid.js';
11
11
  import { renderFull, renderIndex } from './render.js';
12
12
  import { resolveProject } from '../util/project.js';
13
+ import { findUsages, formatUsages } from '../usages/index.js';
13
14
  import { silenceSqliteWarning } from '../util/warnings.js';
14
15
  silenceSqliteWarning();
15
16
  const KINDS = [
@@ -129,6 +130,41 @@ server.tool('get_observations', 'Layer 3. Fetch full bodies for specific observa
129
130
  ],
130
131
  };
131
132
  });
133
+ server.tool('find_usages', 'Find real usages of a symbol or component name via `git grep` — a live read ' +
134
+ 'of the current source, not a stored index, so it is never stale. Returns ' +
135
+ 'file:line and the matching line, with a best-effort [definition?] marker on ' +
136
+ 'lines that look like a declaration. Use this before editing or removing a ' +
137
+ 'shared or exported name, or to answer "what uses this" (structure). Use ' +
138
+ '`search` instead for "why is this the way it is" (history).', {
139
+ symbol: z.string().min(1).max(200).describe('Exact name to search for, e.g. "useAuth" or "CartButton"'),
140
+ path: z
141
+ .string()
142
+ .optional()
143
+ .describe('Directory inside the repo to search from; defaults to cwd. Must be inside ' +
144
+ 'a git working tree. Different from the memory tools’ project param, which ' +
145
+ 'can point at a folder pooling several repos rather than being one itself'),
146
+ regex: z
147
+ .boolean()
148
+ .default(false)
149
+ .describe('Treat symbol as an extended regular expression instead of a literal name'),
150
+ context: z
151
+ .number()
152
+ .int()
153
+ .min(0)
154
+ .max(10)
155
+ .default(0)
156
+ .describe('Lines of surrounding context before/after each match'),
157
+ limit: z
158
+ .number()
159
+ .int()
160
+ .min(1)
161
+ .max(500)
162
+ .default(100)
163
+ .describe('Cap on matching lines returned; the result says how many more exist'),
164
+ }, async ({ symbol, path, regex, context, limit }) => {
165
+ const result = findUsages({ symbol, regex, context, limit, ...(path ? { path } : {}) });
166
+ return { content: [{ type: 'text', text: formatUsages(result) }] };
167
+ });
132
168
  const transport = new StdioServerTransport();
133
169
  await server.connect(transport);
134
170
  for (const signal of ['SIGINT', 'SIGTERM']) {
@@ -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';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-db",
3
- "version": "0.3.0",
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",