claude-db 0.5.4 → 0.6.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 (38) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/dist/cli/commands/graph.js +14 -2
  3. package/dist/cli/install.js +1 -0
  4. package/dist/graph/index.d.ts +2 -2
  5. package/dist/graph/index.js +2 -2
  6. package/dist/graph/query/format.js +7 -3
  7. package/dist/graph/query/index.d.ts +1 -0
  8. package/dist/graph/query/index.js +1 -0
  9. package/dist/graph/query/lookup.d.ts +1 -0
  10. package/dist/graph/query/lookup.js +6 -0
  11. package/dist/graph/query/suggest.d.ts +5 -0
  12. package/dist/graph/query/suggest.js +65 -0
  13. package/dist/graph/scan/files.d.ts +1 -0
  14. package/dist/graph/scan/files.js +8 -2
  15. package/dist/graph/scan/index.d.ts +1 -1
  16. package/dist/graph/scan/index.js +1 -1
  17. package/dist/hooks/grep-symbols.d.ts +3 -0
  18. package/dist/hooks/grep-symbols.js +22 -0
  19. package/dist/hooks/prefer-usages.d.ts +2 -0
  20. package/dist/hooks/prefer-usages.js +58 -0
  21. package/dist/mcp/server.js +6 -170
  22. package/dist/mcp/tools/kinds.d.ts +1 -0
  23. package/dist/mcp/tools/kinds.js +1 -0
  24. package/dist/mcp/tools/memory.d.ts +3 -0
  25. package/dist/mcp/tools/memory.js +44 -0
  26. package/dist/mcp/tools/observations.d.ts +3 -0
  27. package/dist/mcp/tools/observations.js +55 -0
  28. package/dist/mcp/tools/search.d.ts +3 -0
  29. package/dist/mcp/tools/search.js +54 -0
  30. package/dist/mcp/tools/usages.d.ts +3 -0
  31. package/dist/mcp/tools/usages.js +79 -0
  32. package/dist/search/service.js +3 -0
  33. package/dist/search/stopwords.d.ts +2 -0
  34. package/dist/search/stopwords.js +137 -0
  35. package/dist/store/sqlite/filters.js +3 -5
  36. package/dist/usages/find.d.ts +1 -1
  37. package/dist/usages/find.js +5 -3
  38. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,71 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.6.0
4
+
5
+ ### Fixed
6
+
7
+ - **`scan` served a stale graph after every upgrade.** The scan cache keyed on
8
+ file content hash alone, so when an extractor changed, users' files did not —
9
+ and `scan` reported `N unchanged, 0 parsed` while continuing to serve edges
10
+ built by the previous extractor. Fixes shipped in 0.5.3 never reached anyone
11
+ who upgraded; only `scan --force` surfaced them, and nothing told you to run
12
+ it. The cache key now mixes in a `SCAN_VERSION` and a fingerprint of the
13
+ language rules, so an upgrade reparses once, automatically, and a rule edit
14
+ invalidates the cache without anyone remembering to bump a constant.
15
+ Verified against a cache written by the old extractor: 240 files skipped
16
+ before, 204 reparsed after, and an unchanged file is still skipped on the
17
+ next scan.
18
+
19
+ - **One common word in a query returned the whole corpus.** SQLite keyword
20
+ search ORs every token, so `"quantum entanglement recipes for sourdough"`
21
+ matched 30 rows on the strength of `for` alone, and an all-stopword query
22
+ matched everything. Postgres and Mongo were never affected — `plainto_tsquery`
23
+ and Mongo's `$text` strip stopwords already — so SQLite, the default backend,
24
+ was the only one exposed. Stopwords are now removed before the query is built,
25
+ and a query with no content words returns nothing instead of the corpus. The
26
+ filtering lives in `src/search`, not the adapter, so every backend behaves the
27
+ same. Note this could not be fixed after ranking: RRF discards score magnitude
28
+ by design, so the fused score is not a relevance measure and cannot be
29
+ thresholded.
30
+
31
+ - **`get_observations` answered with an empty string.** An id that resolved to
32
+ nothing produced no output at all rather than saying so, which reads as a
33
+ broken tool. It now names the ids that did not resolve, and a partial batch
34
+ appends which ones were missing instead of silently dropping them.
35
+
36
+ - **`timeline` could not tell a bad id from a quiet session.** Both produced
37
+ `No matching observations.`; the two now read differently.
38
+
39
+ ### Added
40
+
41
+ - **A `PreToolUse` hook that answers symbol searches from the code graph.**
42
+ When a shell `grep` or the Grep tool searches for something shaped like a code
43
+ symbol, the hook runs the graph lookup and returns the definition and every
44
+ reference alongside the search — the grep still runs, so nothing is blocked and
45
+ no second call is needed. It stays silent for plain text, piped output
46
+ filtering, `-v`, regexes, lowercase words, and any project with no graph
47
+ scanned. `CLAUDE_DB_USAGES_HOOK=off` disables it. Registered by `install` and
48
+ removed by `uninstall` like the other hooks.
49
+
50
+ - **`find_usages` suggests near names on a miss.** A miss used to end at
51
+ `No usages of that symbol found`, which is where people give up and go back to
52
+ grep. `embedObservation` now suggests `embedObservations`, `find_symbols`
53
+ suggests `findSymbols`, and a name with no near match still suggests nothing
54
+ rather than something incidental.
55
+
56
+ ### Changed
57
+
58
+ - **Tool descriptions now say when to reach for the tool.** `search`, `timeline`
59
+ and `get_observations` opened with `Layer 1/2/3`, an internal concept that
60
+ never stated a trigger, and `find_usages` opened by describing itself as a live
61
+ `git grep`. They now lead with the condition that should make you call them,
62
+ and `search` explains what to try when nothing matches.
63
+
64
+ - **`src/mcp/server.ts` split 303 lines into one module per tool group.**
65
+ `server.ts` is 37 lines of bootstrap; the tools live in `src/mcp/tools/`. The
66
+ tool logic is importable and unit-testable for the first time — previously
67
+ anything in `server.ts` self-started a stdio transport on import.
68
+
3
69
  ## 0.5.4
4
70
 
5
71
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  import { createContext } from '../../context.js';
2
2
  import { findUsages, formatUsages, repoRootFor } from '../../usages/index.js';
3
- import { formatGraph, languageNames, queryGraph, refreshGraph, scanRepository, } from '../../graph/index.js';
3
+ import { formatGraph, languageNames, queryGraph, refreshGraph, scanRepository, suggestFor, } from '../../graph/index.js';
4
4
  import { resolveProject } from '../../util/project.js';
5
5
  import { valueOf, withoutFlags } from '../args.js';
6
6
  export async function cmdScan(argv) {
@@ -61,7 +61,8 @@ export async function cmdUsages(argv) {
61
61
  process.exit(1);
62
62
  }
63
63
  if (mode === 'text') {
64
- console.log(formatUsages(findUsages({ symbol: words, regex, context, limit, ...(path ? { path } : {}) })));
64
+ const result = findUsages({ symbol: words, regex, context, limit, ...(path ? { path } : {}) });
65
+ console.log(formatUsages(result, await suggestionsOnMiss(result.matches.length, words)));
65
66
  return;
66
67
  }
67
68
  if (mode !== 'usages' && mode !== 'explain' && mode !== 'path') {
@@ -91,3 +92,14 @@ export async function cmdUsages(argv) {
91
92
  await ctx.close();
92
93
  }
93
94
  }
95
+ async function suggestionsOnMiss(matches, symbol) {
96
+ if (matches > 0)
97
+ return [];
98
+ const ctx = await createContext();
99
+ try {
100
+ return await suggestFor(ctx.store, resolveProject(undefined), symbol);
101
+ }
102
+ finally {
103
+ await ctx.close();
104
+ }
105
+ }
@@ -18,6 +18,7 @@ const HOOKS = [
18
18
  ['SessionStart', 'session-start.js'],
19
19
  ['UserPromptSubmit', 'user-prompt.js'],
20
20
  ['SessionEnd', 'session-end.js'],
21
+ ['PreToolUse', 'prefer-usages.js', 'Bash|Grep'],
21
22
  ];
22
23
  export function assertStableLocation(distDir) {
23
24
  const ephemeral = ['_npx', '_cacache'];
@@ -1,7 +1,7 @@
1
1
  export { LANGUAGES, languageFor, languageNames } from './languages/index.js';
2
2
  export type { LanguageSpec } from './languages/index.js';
3
3
  export { loadParser } from './parser.js';
4
- export { currentHashes, listFiles, scanRepository, sourceFiles } from './scan/index.js';
4
+ export { SCAN_VERSION, currentHashes, hashOf, listFiles, scanRepository, sourceFiles, } from './scan/index.js';
5
5
  export type { ScanOptions, ScanResult } from './scan/index.js';
6
- export { formatGraph, queryGraph, refreshGraph, shortestPath } from './query/index.js';
6
+ export { formatGraph, nearest, queryGraph, refreshGraph, shortestPath, suggestFor, } from './query/index.js';
7
7
  export type { GraphAnswer, GraphMode, GraphQuery } from './query/index.js';
@@ -1,4 +1,4 @@
1
1
  export { LANGUAGES, languageFor, languageNames } from './languages/index.js';
2
2
  export { loadParser } from './parser.js';
3
- export { currentHashes, listFiles, scanRepository, sourceFiles } from './scan/index.js';
4
- export { formatGraph, queryGraph, refreshGraph, shortestPath } from './query/index.js';
3
+ export { SCAN_VERSION, currentHashes, hashOf, listFiles, scanRepository, sourceFiles, } from './scan/index.js';
4
+ export { formatGraph, nearest, queryGraph, refreshGraph, shortestPath, suggestFor, } from './query/index.js';
@@ -1,3 +1,4 @@
1
+ import { formatSuggestions } from './suggest.js';
1
2
  function tag(edge) {
2
3
  const score = edge.confidence === 'INFERRED' ? ` ${edge.score.toFixed(2)}` : '';
3
4
  return `[${edge.relation}] [${edge.confidence}${score}]`;
@@ -5,15 +6,18 @@ function tag(edge) {
5
6
  export function formatGraph(answer, root) {
6
7
  if (answer.mode === 'path') {
7
8
  if (answer.path.length === 0) {
8
- return `No path found from "${answer.symbol}" to "${answer.target ?? ''}".`;
9
+ return (`No path found from "${answer.symbol}" to "${answer.target ?? ''}".` +
10
+ formatSuggestions(answer.suggestions));
9
11
  }
10
12
  return [
11
13
  `Shortest path (${answer.path.length - 1} hops):`,
12
14
  ` ${answer.path.join(' --> ')}`,
13
15
  ].join('\n');
14
16
  }
15
- if (answer.empty)
16
- return `No symbol "${answer.symbol}" in the graph for ${root}.`;
17
+ if (answer.empty) {
18
+ return (`No symbol "${answer.symbol}" in the graph for ${root}.` +
19
+ formatSuggestions(answer.suggestions));
20
+ }
17
21
  const lines = [];
18
22
  for (const definition of answer.definitions) {
19
23
  lines.push(`${definition.name} [${definition.kind}]`);
@@ -3,3 +3,4 @@ export { queryGraph } from './lookup.js';
3
3
  export type { GraphAnswer, GraphMode, GraphQuery } from './lookup.js';
4
4
  export { shortestPath } from './path.js';
5
5
  export { refreshGraph } from './refresh.js';
6
+ export { nearest, suggestFor } from './suggest.js';
@@ -2,3 +2,4 @@ export { formatGraph } from './format.js';
2
2
  export { queryGraph } from './lookup.js';
3
3
  export { shortestPath } from './path.js';
4
4
  export { refreshGraph } from './refresh.js';
5
+ export { nearest, suggestFor } from './suggest.js';
@@ -11,6 +11,7 @@ export interface GraphAnswer {
11
11
  path: string[];
12
12
  refreshed: string[];
13
13
  empty: boolean;
14
+ suggestions: string[];
14
15
  }
15
16
  export interface GraphQuery {
16
17
  mode: GraphMode;
@@ -1,4 +1,5 @@
1
1
  import { shortestPath } from './path.js';
2
+ import { suggestFor } from './suggest.js';
2
3
  export async function queryGraph(store, project, query) {
3
4
  const answer = {
4
5
  mode: query.mode,
@@ -9,12 +10,15 @@ export async function queryGraph(store, project, query) {
9
10
  path: [],
10
11
  refreshed: [],
11
12
  empty: false,
13
+ suggestions: [],
12
14
  };
13
15
  if (query.mode === 'path') {
14
16
  if (query.target)
15
17
  answer.target = query.target;
16
18
  answer.path = await shortestPath(store, project, query.symbol, query.target ?? '');
17
19
  answer.empty = answer.path.length === 0;
20
+ if (answer.empty)
21
+ answer.suggestions = await suggestFor(store, project, query.symbol);
18
22
  return answer;
19
23
  }
20
24
  answer.definitions = await store.findSymbols({
@@ -31,5 +35,7 @@ export async function queryGraph(store, project, query) {
31
35
  answer.inbound = edges.filter((edge) => edge.dstName === query.symbol);
32
36
  answer.outbound = edges.filter((edge) => ids.includes(edge.srcId) && edge.dstName !== query.symbol);
33
37
  answer.empty = answer.definitions.length === 0 && answer.inbound.length === 0;
38
+ if (answer.empty)
39
+ answer.suggestions = await suggestFor(store, project, query.symbol);
34
40
  return answer;
35
41
  }
@@ -0,0 +1,5 @@
1
+ import type { MemoryStore } from '../../store/adapter.js';
2
+ /** Names closest to `symbol`, best first. A miss that names no alternative is where people quit. */
3
+ export declare function nearest(names: Iterable<string>, symbol: string, limit?: number): string[];
4
+ export declare function suggestFor(store: MemoryStore, project: string, symbol: string): Promise<string[]>;
5
+ export declare function formatSuggestions(suggestions: string[]): string;
@@ -0,0 +1,65 @@
1
+ const CANDIDATES = 5000;
2
+ function tokens(name) {
3
+ return (name
4
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
5
+ .split(/[^A-Za-z0-9]+/)
6
+ .filter(Boolean)
7
+ .map((part) => part.toLowerCase())
8
+ // Stem the plural: "hooks" and "hook" are the same misremembered name.
9
+ .map((part) => (part.length > 3 && part.endsWith('s') ? part.slice(0, -1) : part)));
10
+ }
11
+ function score(candidate, query) {
12
+ const left = candidate.toLowerCase();
13
+ const right = query.toLowerCase();
14
+ if (left === right)
15
+ return 100;
16
+ // Ratios are taken against the LONGER name: without that, one-letter locals
17
+ // score as well as the real symbol, because everything contains "e".
18
+ const longest = Math.max(left.length, right.length);
19
+ let prefix = 0;
20
+ while (prefix < left.length && prefix < right.length && left[prefix] === right[prefix]) {
21
+ prefix += 1;
22
+ }
23
+ const byPrefix = prefix >= 3 ? (prefix / longest) * 120 : 0;
24
+ const wanted = tokens(query);
25
+ const mine = tokens(candidate);
26
+ const shared = mine.filter((part) => wanted.includes(part)).length;
27
+ const byToken = shared > 0 ? (shared / Math.max(mine.length, wanted.length)) * 100 : 0;
28
+ const contains = left.includes(right) || right.includes(left);
29
+ const byContains = contains ? (Math.min(left.length, right.length) / longest) * 100 : 0;
30
+ return Math.max(byPrefix, byToken, byContains);
31
+ }
32
+ /** Names closest to `symbol`, best first. A miss that names no alternative is where people quit. */
33
+ export function nearest(names, symbol, limit = 5) {
34
+ const scored = new Map();
35
+ for (const name of names) {
36
+ // Two-character locals are never what someone misremembered.
37
+ if (name === symbol || name.length < 3)
38
+ continue;
39
+ const value = score(name, symbol);
40
+ // Below this, matches are incidental ("widget" contains "get") and a wrong
41
+ // suggestion costs more than none: it sends you looking for the wrong thing.
42
+ if (value >= 40)
43
+ scored.set(name, Math.max(scored.get(name) ?? 0, value));
44
+ }
45
+ return [...scored]
46
+ .sort((a, b) => b[1] - a[1] || a[0].length - b[0].length || a[0].localeCompare(b[0]))
47
+ .slice(0, limit)
48
+ .map(([name]) => name);
49
+ }
50
+ export async function suggestFor(store, project, symbol) {
51
+ if (!symbol)
52
+ return [];
53
+ try {
54
+ const symbols = await store.findSymbols({ project, limit: CANDIDATES });
55
+ return nearest(symbols.map((entry) => entry.name), symbol);
56
+ }
57
+ catch {
58
+ return [];
59
+ }
60
+ }
61
+ export function formatSuggestions(suggestions) {
62
+ if (suggestions.length === 0)
63
+ return '';
64
+ return `\nDid you mean: ${suggestions.join(', ')}`;
65
+ }
@@ -5,6 +5,7 @@ export interface SourceFile {
5
5
  source: string;
6
6
  hash: string;
7
7
  }
8
+ export declare const SCAN_VERSION = 2;
8
9
  export declare function hashOf(bytes: Buffer): string;
9
10
  export declare function listFiles(root: string): string[];
10
11
  export declare function sourceFiles(root: string): string[];
@@ -2,11 +2,17 @@ import { execFileSync } from 'node:child_process';
2
2
  import { createHash } from 'node:crypto';
3
3
  import { readFileSync } from 'node:fs';
4
4
  import { join } from 'node:path';
5
- import { languageFor } from '../languages/index.js';
5
+ import { LANGUAGES, languageFor } from '../languages/index.js';
6
6
  const MAX_BUFFER = 64 * 1024 * 1024;
7
7
  const MAX_FILE_BYTES = 1024 * 1024;
8
+ export const SCAN_VERSION = 2;
9
+ const RULES_FINGERPRINT = createHash('sha256')
10
+ .update(JSON.stringify(LANGUAGES))
11
+ .digest('hex')
12
+ .slice(0, 12);
13
+ const CACHE_KEY = `v${SCAN_VERSION}:${RULES_FINGERPRINT}\n`;
8
14
  export function hashOf(bytes) {
9
- return createHash('sha256').update(bytes).digest('hex').slice(0, 32);
15
+ return createHash('sha256').update(CACHE_KEY).update(bytes).digest('hex').slice(0, 32);
10
16
  }
11
17
  export function listFiles(root) {
12
18
  const list = (args) => execFileSync('git', ['-C', root, ...args], {
@@ -1,6 +1,6 @@
1
1
  import type { CodeEdge, CodeSymbol, ScannedFile } from '../../types.js';
2
2
  export type { SourceFile } from './files.js';
3
- export { currentHashes, hashOf, listFiles, sourceFiles } from './files.js';
3
+ export { SCAN_VERSION, currentHashes, hashOf, listFiles, sourceFiles } from './files.js';
4
4
  export interface ScanOptions {
5
5
  root: string;
6
6
  project: string;
@@ -2,7 +2,7 @@ import { loadParser } from '../parser.js';
2
2
  import { extractFile } from './extract.js';
3
3
  import { listFiles, readSource } from './files.js';
4
4
  import { resolveEdges } from './resolve.js';
5
- export { currentHashes, hashOf, listFiles, sourceFiles } from './files.js';
5
+ export { SCAN_VERSION, currentHashes, hashOf, listFiles, sourceFiles } from './files.js';
6
6
  export function scanRepository(options) {
7
7
  const { root, project, known, force } = options;
8
8
  loadParser();
@@ -0,0 +1,3 @@
1
+ export declare function isSymbol(pattern: string): boolean;
2
+ /** Symbols a shell command searches the tree for, which the code graph also answers. */
3
+ export declare function symbolsGreppedIn(command: string): string[];
@@ -0,0 +1,22 @@
1
+ const SYMBOL = /^(?=.{4,})(?:[a-z]+(?:[A-Z][a-zA-Z0-9]*)+|[A-Z][a-z0-9]+(?:[A-Z][a-zA-Z0-9]*)*|[a-z][a-z0-9]*(?:_[a-z0-9]+)+)$/;
2
+ const GREP = /\b(?:grep|rg)\b((?:\s+-{1,2}[\w-]+(?:=\S+)?)*)\s+(?:(['"])(.+?)\2|(\S+))([^;&|]*)/g;
3
+ export function isSymbol(pattern) {
4
+ return SYMBOL.test(pattern);
5
+ }
6
+ /** Symbols a shell command searches the tree for, which the code graph also answers. */
7
+ export function symbolsGreppedIn(command) {
8
+ const found = new Set();
9
+ for (const match of command.matchAll(GREP)) {
10
+ const flags = match[1] ?? '';
11
+ const pattern = match[3] ?? match[4] ?? '';
12
+ const rest = match[5] ?? '';
13
+ if (!SYMBOL.test(pattern))
14
+ continue;
15
+ if (/-\w*v/.test(flags))
16
+ continue;
17
+ if (/-\w*[rR]\b|--recursive/.test(flags) || /^\s+[^-|;&>][^\s|;&>]*/.test(rest)) {
18
+ found.add(pattern);
19
+ }
20
+ }
21
+ return [...found].sort();
22
+ }
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
@@ -0,0 +1,58 @@
1
+ #!/usr/bin/env node
2
+ import { createContext } from '../context.js';
3
+ import { formatGraph, queryGraph } from '../graph/index.js';
4
+ import { isSymbol, symbolsGreppedIn } from './grep-symbols.js';
5
+ import { readPayload, runHook } from './payload.js';
6
+ import { resolveProject } from '../util/project.js';
7
+ import { silenceSqliteWarning } from '../util/warnings.js';
8
+ silenceSqliteWarning();
9
+ const MAX_SYMBOLS = 2;
10
+ const MAX_LINES = 14;
11
+ function requested(payload) {
12
+ const input = payload.tool_input ?? {};
13
+ if (payload.tool_name === 'Grep') {
14
+ const pattern = typeof input['pattern'] === 'string' ? input['pattern'] : '';
15
+ return isSymbol(pattern) ? [pattern] : [];
16
+ }
17
+ if (payload.tool_name === 'Bash') {
18
+ return symbolsGreppedIn(typeof input['command'] === 'string' ? input['command'] : '');
19
+ }
20
+ return [];
21
+ }
22
+ function trim(answer) {
23
+ const lines = answer.split('\n');
24
+ if (lines.length <= MAX_LINES)
25
+ return answer;
26
+ return [...lines.slice(0, MAX_LINES), ` ... more via find_usages`].join('\n');
27
+ }
28
+ await runHook(async () => {
29
+ if (process.env['CLAUDE_DB_USAGES_HOOK'] === 'off')
30
+ return;
31
+ const payload = await readPayload();
32
+ const symbols = requested(payload).slice(0, MAX_SYMBOLS);
33
+ if (symbols.length === 0)
34
+ return;
35
+ const project = resolveProject(payload.cwd);
36
+ const ctx = await createContext();
37
+ const blocks = [];
38
+ try {
39
+ for (const symbol of symbols) {
40
+ const answer = await queryGraph(ctx.store, project, { mode: 'usages', symbol, limit: 20 });
41
+ if (answer.empty)
42
+ continue;
43
+ blocks.push(trim(formatGraph(answer, project)));
44
+ }
45
+ }
46
+ finally {
47
+ await ctx.close();
48
+ }
49
+ if (blocks.length === 0)
50
+ return;
51
+ process.stdout.write(JSON.stringify({
52
+ hookSpecificOutput: {
53
+ hookEventName: 'PreToolUse',
54
+ additionalContext: `Code graph, for the symbol(s) this search names — the grep below still runs, ` +
55
+ `this is the structure it cannot show:\n\n${blocks.join('\n\n')}`,
56
+ },
57
+ }));
58
+ });
@@ -4,17 +4,13 @@ import { dirname, resolve } from 'node:path';
4
4
  import { fileURLToPath } from 'node:url';
5
5
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
6
6
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
7
- import { z } from 'zod';
8
- import { remember } from '../capture/index.js';
9
7
  import { createContext } from '../context.js';
10
- import { toShortId } from '../util/shortid.js';
11
- import { renderFull, renderIndex } from './render.js';
12
- import { resolveProject } from '../util/project.js';
13
- import { findUsages, formatUsages, repoRootFor } from '../usages/index.js';
14
- import { formatGraph, queryGraph, refreshGraph } from '../graph/index.js';
15
8
  import { silenceSqliteWarning } from '../util/warnings.js';
9
+ import * as memory from './tools/memory.js';
10
+ import * as observations from './tools/observations.js';
11
+ import * as search from './tools/search.js';
12
+ import * as usages from './tools/usages.js';
16
13
  silenceSqliteWarning();
17
- const KINDS = ['decision', 'pattern', 'bugfix', 'context', 'deadend', 'preference'];
18
14
  function packageVersion() {
19
15
  try {
20
16
  const path = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
@@ -26,168 +22,8 @@ function packageVersion() {
26
22
  }
27
23
  const ctx = await createContext();
28
24
  const server = new McpServer({ name: 'claude-db', version: packageVersion() });
29
- server.tool('search', 'Layer 1. Search project memory and get a compact index of matches ' +
30
- '(id, kind, date, title, and a line of the matching body) without full ' +
31
- 'bodies. Start here, and use the snippet to decide which ids are worth ' +
32
- 'passing to get_observations rather than expanding on the title alone.', {
33
- query: z.string().describe('Natural language description of what you need'),
34
- project: z
35
- .string()
36
- .optional()
37
- .describe('Absolute project path; defaults to cwd. Pass "*" to search every project'),
38
- kind: z.enum(KINDS).optional(),
39
- tag: z
40
- .string()
41
- .optional()
42
- .describe('Limit to one repository or top-level directory, e.g. "backend". Useful ' +
43
- 'when a workspace pools several repos under one project'),
44
- limit: z.number().int().min(1).max(50).default(10),
45
- }, async ({ query, project, kind, tag, limit }) => {
46
- const entries = await ctx.search.search({
47
- text: query,
48
- limit,
49
- ...(project === '*' ? {} : { project: resolveProject(project) }),
50
- ...(kind ? { kind } : {}),
51
- ...(tag ? { tag } : {}),
52
- });
53
- return { content: [{ type: 'text', text: renderIndex(entries) }] };
54
- });
55
- server.tool('remember', 'Record something the user stated outright that no transcript would capture: ' +
56
- 'a standing rule, preference or constraint ("always use pnpm here"). Use this ' +
57
- 'when the user says to remember something, not for work you just did — that ' +
58
- 'is captured automatically.', {
59
- text: z.string().describe('What to remember, in full. First line becomes the title'),
60
- kind: z.enum(KINDS).default('preference'),
61
- project: z.string().optional().describe('Absolute project path; defaults to cwd'),
62
- key: z
63
- .string()
64
- .optional()
65
- .describe('Stable name for a note meant to be kept current, e.g. "profile:stack". ' +
66
- 'Remembering the same key again replaces it instead of adding a duplicate'),
67
- tags: z.array(z.string()).max(5).optional().describe('Extra tags for filtering'),
68
- }, async ({ text, kind, project, key, tags }) => {
69
- const observation = await remember(ctx, {
70
- project: resolveProject(project),
71
- text,
72
- kind,
73
- ...(key ? { key } : {}),
74
- ...(tags ? { tags } : {}),
75
- });
76
- return {
77
- content: [
78
- {
79
- type: 'text',
80
- text: `Remembered ${toShortId(observation.id)} [${observation.kind}] ${observation.title}`,
81
- },
82
- ],
83
- };
84
- });
85
- server.tool('forget', 'Delete observations by id, for memory that is wrong or obsolete. Ids come ' +
86
- 'from search. This cannot be undone, so confirm with the user first.', { ids: z.array(z.string()).min(1).max(25) }, async ({ ids }) => {
87
- const deleted = await ctx.store.remove({ ids });
88
- return {
89
- content: [{ type: 'text', text: `Forgot ${deleted} observation(s).` }],
90
- };
91
- });
92
- server.tool('timeline', 'Layer 2. Show what happened immediately before and after a given ' +
93
- 'observation, to understand the context a decision was made in.', {
94
- observation_id: z.string(),
95
- before: z.number().int().min(0).max(20).default(5),
96
- after: z.number().int().min(0).max(20).default(5),
97
- }, async ({ observation_id, before, after }) => {
98
- const entries = await ctx.search.timeline({ observationId: observation_id, before, after });
99
- return { content: [{ type: 'text', text: renderIndex(entries) }] };
100
- });
101
- server.tool('get_observations', 'Layer 3. Fetch full bodies for specific observation ids, using the short ' +
102
- 'ids returned by search. Always batch every id you need into one call ' +
103
- 'rather than calling repeatedly.', {
104
- ids: z.array(z.string()).min(1).max(25),
105
- chars: z
106
- .number()
107
- .int()
108
- .min(200)
109
- .max(20000)
110
- .default(2000)
111
- .describe('Characters of each body to return. Bodies run to 4000 and this call ' +
112
- 'takes 25 ids, so the default keeps a batch readable; raise it when a ' +
113
- 'truncated answer says there is more'),
114
- }, async ({ ids, chars }) => {
115
- const observations = await ctx.search.getObservations(ids);
116
- return {
117
- content: [
118
- {
119
- type: 'text',
120
- text: observations.map((obs) => renderFull(obs, chars)).join('\n\n---\n\n'),
121
- },
122
- ],
123
- };
124
- });
125
- server.tool('find_usages', 'Find real usages of a symbol, and how the code around it connects. ' +
126
- '`mode: "text"` (default) is a live `git grep` — never stale, works with no ' +
127
- 'setup, and returns file:line with a best-effort [definition?] marker. The ' +
128
- 'other modes read the code graph built by `claude-db scan`, which knows a ' +
129
- 'call from an import from an inherit: "usages" lists what references the ' +
130
- 'symbol with the relation on each line, "explain" adds what the symbol ' +
131
- 'reaches, and "path" traces how two symbols connect (pass the second as ' +
132
- '`target`). Graph answers re-parse anything that changed before replying, ' +
133
- 'so they cannot report a line the source has moved past. Every edge is ' +
134
- 'tagged EXTRACTED (read literally from the syntax) or INFERRED (matched by ' +
135
- 'name across files, with a score). Use `search` instead for "why is this ' +
136
- 'the way it is" (history).', {
137
- symbol: z
138
- .string()
139
- .min(1)
140
- .max(200)
141
- .describe('Exact name to search for, e.g. "useAuth" or "CartButton"'),
142
- mode: z
143
- .enum(['text', 'usages', 'explain', 'path'])
144
- .default('text')
145
- .describe('How to answer. "text" greps live and needs no scan; the rest query the ' +
146
- 'stored graph and return nothing useful until `claude-db scan` has run'),
147
- target: z.string().optional().describe('The second symbol, for mode "path" only'),
148
- path: z
149
- .string()
150
- .optional()
151
- .describe('A file or directory to narrow the search to; omit to search the whole ' +
152
- 'repository (never narrows on its own — a blast-radius check that quietly ' +
153
- 'skipped part of the repo would be worse than no check). Must be inside a ' +
154
- 'git working tree. Different from the memory tools’ project param, which ' +
155
- 'can point at a folder pooling several repos rather than being one itself'),
156
- regex: z
157
- .boolean()
158
- .default(false)
159
- .describe('Treat symbol as an extended regular expression instead of a literal name'),
160
- context: z
161
- .number()
162
- .int()
163
- .min(0)
164
- .max(10)
165
- .default(0)
166
- .describe('Lines of surrounding context before/after each match'),
167
- limit: z
168
- .number()
169
- .int()
170
- .min(1)
171
- .max(500)
172
- .default(100)
173
- .describe('Cap on matching lines returned; the result says how many more exist'),
174
- }, async ({ symbol, mode, target, path, regex, context, limit }) => {
175
- if (mode === 'text') {
176
- const result = findUsages({ symbol, regex, context, limit, ...(path ? { path } : {}) });
177
- return { content: [{ type: 'text', text: formatUsages(result) }] };
178
- }
179
- const root = repoRootFor(path ?? process.cwd());
180
- const project = resolveProject(undefined);
181
- const refreshed = await refreshGraph(ctx.store, root, project);
182
- const answer = await queryGraph(ctx.store, project, {
183
- mode,
184
- symbol,
185
- ...(target ? { target } : {}),
186
- limit,
187
- });
188
- answer.refreshed = refreshed;
189
- return { content: [{ type: 'text', text: formatGraph(answer, root) }] };
190
- });
25
+ for (const tools of [search, memory, observations, usages])
26
+ tools.register(server, ctx);
191
27
  const transport = new StdioServerTransport();
192
28
  await server.connect(transport);
193
29
  for (const signal of ['SIGINT', 'SIGTERM']) {
@@ -0,0 +1 @@
1
+ export declare const KINDS: readonly ["decision", "pattern", "bugfix", "context", "deadend", "preference"];
@@ -0,0 +1 @@
1
+ export const KINDS = ['decision', 'pattern', 'bugfix', 'context', 'deadend', 'preference'];
@@ -0,0 +1,3 @@
1
+ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
+ import type { RecallContext } from '../../context.js';
3
+ export declare function register(server: McpServer, ctx: RecallContext): void;
@@ -0,0 +1,44 @@
1
+ import { z } from 'zod';
2
+ import { KINDS } from './kinds.js';
3
+ import { remember } from '../../capture/index.js';
4
+ import { toShortId } from '../../util/shortid.js';
5
+ import { resolveProject } from '../../util/project.js';
6
+ export function register(server, ctx) {
7
+ server.tool('remember', 'Record something the user stated outright that no transcript would capture: ' +
8
+ 'a standing rule, preference or constraint ("always use pnpm here"). Use this ' +
9
+ 'when the user says to remember something, not for work you just did — that ' +
10
+ 'is captured automatically.', {
11
+ text: z.string().describe('What to remember, in full. First line becomes the title'),
12
+ kind: z.enum(KINDS).default('preference'),
13
+ project: z.string().optional().describe('Absolute project path; defaults to cwd'),
14
+ key: z
15
+ .string()
16
+ .optional()
17
+ .describe('Stable name for a note meant to be kept current, e.g. "profile:stack". ' +
18
+ 'Remembering the same key again replaces it instead of adding a duplicate'),
19
+ tags: z.array(z.string()).max(5).optional().describe('Extra tags for filtering'),
20
+ }, async ({ text, kind, project, key, tags }) => {
21
+ const observation = await remember(ctx, {
22
+ project: resolveProject(project),
23
+ text,
24
+ kind,
25
+ ...(key ? { key } : {}),
26
+ ...(tags ? { tags } : {}),
27
+ });
28
+ return {
29
+ content: [
30
+ {
31
+ type: 'text',
32
+ text: `Remembered ${toShortId(observation.id)} [${observation.kind}] ${observation.title}`,
33
+ },
34
+ ],
35
+ };
36
+ });
37
+ server.tool('forget', 'Delete observations by id, for memory that is wrong or obsolete. Ids come ' +
38
+ 'from search. This cannot be undone, so confirm with the user first.', { ids: z.array(z.string()).min(1).max(25) }, async ({ ids }) => {
39
+ const deleted = await ctx.store.remove({ ids });
40
+ return {
41
+ content: [{ type: 'text', text: `Forgot ${deleted} observation(s).` }],
42
+ };
43
+ });
44
+ }
@@ -0,0 +1,3 @@
1
+ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
+ import type { RecallContext } from '../../context.js';
3
+ export declare function register(server: McpServer, ctx: RecallContext): void;
@@ -0,0 +1,55 @@
1
+ import { z } from 'zod';
2
+ import { renderFull, renderIndex } from '../render.js';
3
+ export function register(server, ctx) {
4
+ server.tool('timeline', 'Given one observation id from search, show what happened immediately before ' +
5
+ 'and after it. Use it when a single result is not enough to explain itself ' +
6
+ 'and you need the session around it — what led to a decision and what came ' +
7
+ 'of it. Ids are the short ids search prints.', {
8
+ observation_id: z.string(),
9
+ before: z.number().int().min(0).max(20).default(5),
10
+ after: z.number().int().min(0).max(20).default(5),
11
+ }, async ({ observation_id, before, after }) => {
12
+ const entries = await ctx.search.timeline({ observationId: observation_id, before, after });
13
+ if (entries.length === 0) {
14
+ const [found] = await ctx.search.getObservations([observation_id]);
15
+ const text = found
16
+ ? `No observations around ${observation_id}; it has no neighbours in that session.`
17
+ : `No observation with id ${observation_id}. Ids come from search, and are the short ` +
18
+ `ids it prints — run search first and pass one of those.`;
19
+ return { content: [{ type: 'text', text }] };
20
+ }
21
+ return { content: [{ type: 'text', text: renderIndex(entries) }] };
22
+ });
23
+ server.tool('get_observations', 'Read the full body of observations search has already found, using the short ' +
24
+ 'ids it printed. Use it whenever a search snippet looks like it answers your ' +
25
+ 'question but is cut off — the snippet is one line, the body is the reasoning. ' +
26
+ 'Always batch every id you need into one call rather than calling repeatedly.', {
27
+ ids: z.array(z.string()).min(1).max(25),
28
+ chars: z
29
+ .number()
30
+ .int()
31
+ .min(200)
32
+ .max(20000)
33
+ .default(2000)
34
+ .describe('Characters of each body to return. Bodies run to 4000 and this call ' +
35
+ 'takes 25 ids, so the default keeps a batch readable; raise it when a ' +
36
+ 'truncated answer says there is more'),
37
+ }, async ({ ids, chars }) => {
38
+ const observations = await ctx.search.getObservations(ids);
39
+ if (observations.length === 0) {
40
+ return {
41
+ content: [
42
+ {
43
+ type: 'text',
44
+ text: `No observation matched ${ids.join(', ')}. Ids come from search — run it first ` +
45
+ `and pass the short ids it prints.`,
46
+ },
47
+ ],
48
+ };
49
+ }
50
+ const missing = ids.filter((id) => !observations.some((obs) => obs.id === id || obs.id.startsWith(id)));
51
+ const body = observations.map((obs) => renderFull(obs, chars)).join('\n\n---\n\n');
52
+ const note = missing.length > 0 ? `\n\n(no observation matched ${missing.join(', ')})` : '';
53
+ return { content: [{ type: 'text', text: body + note }] };
54
+ });
55
+ }
@@ -0,0 +1,3 @@
1
+ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
+ import type { RecallContext } from '../../context.js';
3
+ export declare function register(server: McpServer, ctx: RecallContext): void;
@@ -0,0 +1,54 @@
1
+ import { z } from 'zod';
2
+ import { KINDS } from './kinds.js';
3
+ import { renderIndex } from '../render.js';
4
+ import { resolveProject } from '../../util/project.js';
5
+ export function register(server, ctx) {
6
+ server.tool('search', 'USE THIS BEFORE re-deriving anything this project already decided — before ' +
7
+ 'reading git history to reconstruct why code is the way it is, before saying ' +
8
+ 'you lack context, and before asking the user to re-explain a past decision ' +
9
+ 'or a failed approach. This answers WHY: decisions, dead ends, bugs and the ' +
10
+ 'reasoning behind them, which the source code cannot tell you. Returns a ' +
11
+ 'compact index (id, kind, date, title, and a line of the matching body) ' +
12
+ 'without full bodies; use the snippet to decide which ids are worth passing ' +
13
+ 'to get_observations rather than expanding on the title alone. For a code ' +
14
+ 'symbol use find_usages instead.', {
15
+ query: z.string().describe('Natural language description of what you need'),
16
+ project: z
17
+ .string()
18
+ .optional()
19
+ .describe('Absolute project path; defaults to cwd. Pass "*" to search every project'),
20
+ kind: z.enum(KINDS).optional(),
21
+ tag: z
22
+ .string()
23
+ .optional()
24
+ .describe('Limit to one repository or top-level directory, e.g. "backend". Useful ' +
25
+ 'when a workspace pools several repos under one project'),
26
+ limit: z.number().int().min(1).max(50).default(10),
27
+ }, async ({ query, project, kind, tag, limit }) => {
28
+ const entries = await ctx.search.search({
29
+ text: query,
30
+ limit,
31
+ ...(project === '*' ? {} : { project: resolveProject(project) }),
32
+ ...(kind ? { kind } : {}),
33
+ ...(tag ? { tag } : {}),
34
+ });
35
+ if (entries.length === 0) {
36
+ return { content: [{ type: 'text', text: await noMatches(ctx, project) }] };
37
+ }
38
+ return { content: [{ type: 'text', text: renderIndex(entries) }] };
39
+ });
40
+ }
41
+ async function noMatches(ctx, project) {
42
+ const scope = project === '*' ? undefined : resolveProject(project);
43
+ const any = await ctx.store.list({ ...(scope ? { project: scope } : {}), limit: 1 });
44
+ if (any.length === 0) {
45
+ return scope
46
+ ? `No memory recorded for ${scope} yet. Run \`claude-db flush\` to ingest this ` +
47
+ `project's sessions, or pass project: "*" to search every project.`
48
+ : 'No memory recorded in this database yet. Run `claude-db flush` to ingest sessions.';
49
+ }
50
+ return scope
51
+ ? `No match in ${scope}, though it does have memory. Try broader wording, drop the kind ` +
52
+ `or tag filter, or pass project: "*" to search every project.`
53
+ : 'No match in any project. Try broader wording, or drop the kind or tag filter.';
54
+ }
@@ -0,0 +1,3 @@
1
+ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
+ import type { RecallContext } from '../../context.js';
3
+ export declare function register(server: McpServer, ctx: RecallContext): void;
@@ -0,0 +1,79 @@
1
+ import { z } from 'zod';
2
+ import { findUsages, formatUsages, repoRootFor } from '../../usages/index.js';
3
+ import { formatGraph, queryGraph, refreshGraph, suggestFor } from '../../graph/index.js';
4
+ import { resolveProject } from '../../util/project.js';
5
+ export function register(server, ctx) {
6
+ server.tool('find_usages', 'USE THIS INSTEAD OF grep/rg WHENEVER THE THING YOU ARE LOOKING UP IS A CODE ' +
7
+ 'SYMBOL — a function, class, method, type, interface, constant or any ' +
8
+ 'identifier — and ALWAYS before editing, renaming or deleting one, because ' +
9
+ 'grep cannot tell a call from an import from an inherit and will not show ' +
10
+ 'you the blast radius. Reach for grep only for what is genuinely text: ' +
11
+ 'plain prose, comments, log output, string literals, multi-pattern regex, ' +
12
+ 'or the scoping flags this tool does not expose. Modes: "usages" lists what ' +
13
+ 'references the symbol with the relation on each line, "explain" adds what ' +
14
+ 'the symbol reaches, "path" traces how two symbols connect (pass the second ' +
15
+ 'as `target`), and `mode: "text"` (default) is a live `git grep` that needs ' +
16
+ 'no scan. Graph modes read the graph built by `claude-db scan` and re-parse ' +
17
+ 'anything that changed before replying, so they cannot report a line the ' +
18
+ 'source has moved past. Every edge is tagged EXTRACTED (read literally from ' +
19
+ 'the syntax) or INFERRED (matched by name across files, with a score). A ' +
20
+ 'miss suggests near names, so a half-remembered symbol is still worth ' +
21
+ 'asking about. Use `search` instead for "why is this the way it is" (history).', {
22
+ symbol: z
23
+ .string()
24
+ .min(1)
25
+ .max(200)
26
+ .describe('Exact name to search for, e.g. "useAuth" or "CartButton"'),
27
+ mode: z
28
+ .enum(['text', 'usages', 'explain', 'path'])
29
+ .default('text')
30
+ .describe('How to answer. "text" greps live and needs no scan; the rest query the ' +
31
+ 'stored graph and return nothing useful until `claude-db scan` has run'),
32
+ target: z.string().optional().describe('The second symbol, for mode "path" only'),
33
+ path: z
34
+ .string()
35
+ .optional()
36
+ .describe('A file or directory to narrow the search to; omit to search the whole ' +
37
+ 'repository (never narrows on its own — a blast-radius check that quietly ' +
38
+ 'skipped part of the repo would be worse than no check). Must be inside a ' +
39
+ 'git working tree. Different from the memory tools’ project param, which ' +
40
+ 'can point at a folder pooling several repos rather than being one itself'),
41
+ regex: z
42
+ .boolean()
43
+ .default(false)
44
+ .describe('Treat symbol as an extended regular expression instead of a literal name'),
45
+ context: z
46
+ .number()
47
+ .int()
48
+ .min(0)
49
+ .max(10)
50
+ .default(0)
51
+ .describe('Lines of surrounding context before/after each match'),
52
+ limit: z
53
+ .number()
54
+ .int()
55
+ .min(1)
56
+ .max(500)
57
+ .default(100)
58
+ .describe('Cap on matching lines returned; the result says how many more exist'),
59
+ }, async ({ symbol, mode, target, path, regex, context, limit }) => {
60
+ if (mode === 'text') {
61
+ const result = findUsages({ symbol, regex, context, limit, ...(path ? { path } : {}) });
62
+ const missed = result.matches.length === 0
63
+ ? await suggestFor(ctx.store, resolveProject(undefined), symbol)
64
+ : [];
65
+ return { content: [{ type: 'text', text: formatUsages(result, missed) }] };
66
+ }
67
+ const root = repoRootFor(path ?? process.cwd());
68
+ const project = resolveProject(undefined);
69
+ const refreshed = await refreshGraph(ctx.store, root, project);
70
+ const answer = await queryGraph(ctx.store, project, {
71
+ mode,
72
+ symbol,
73
+ ...(target ? { target } : {}),
74
+ limit,
75
+ });
76
+ answer.refreshed = refreshed;
77
+ return { content: [{ type: 'text', text: formatGraph(answer, root) }] };
78
+ });
79
+ }
@@ -1,4 +1,5 @@
1
1
  import { applyRecencyBoost, fuse } from './rank.js';
2
+ import { meaningfulTokens } from './stopwords.js';
2
3
  export class SearchService {
3
4
  store;
4
5
  embedder;
@@ -9,6 +10,8 @@ export class SearchService {
9
10
  this.maxScanCandidates = maxScanCandidates;
10
11
  }
11
12
  async search(query) {
13
+ if (meaningfulTokens(query.text).length === 0)
14
+ return [];
12
15
  const wide = {
13
16
  ...query,
14
17
  limit: query.limit * 3,
@@ -0,0 +1,2 @@
1
+ export declare function isStopword(token: string): boolean;
2
+ export declare function meaningfulTokens(text: string): string[];
@@ -0,0 +1,137 @@
1
+ const STOPWORDS = new Set([
2
+ 'a',
3
+ 'about',
4
+ 'after',
5
+ 'all',
6
+ 'also',
7
+ 'am',
8
+ 'an',
9
+ 'and',
10
+ 'any',
11
+ 'are',
12
+ 'as',
13
+ 'at',
14
+ 'be',
15
+ 'because',
16
+ 'been',
17
+ 'before',
18
+ 'being',
19
+ 'between',
20
+ 'both',
21
+ 'but',
22
+ 'by',
23
+ 'can',
24
+ 'could',
25
+ 'did',
26
+ 'do',
27
+ 'does',
28
+ 'doing',
29
+ 'done',
30
+ 'down',
31
+ 'during',
32
+ 'each',
33
+ 'even',
34
+ 'for',
35
+ 'from',
36
+ 'further',
37
+ 'get',
38
+ 'got',
39
+ 'had',
40
+ 'has',
41
+ 'have',
42
+ 'having',
43
+ 'he',
44
+ 'her',
45
+ 'here',
46
+ 'hers',
47
+ 'him',
48
+ 'his',
49
+ 'how',
50
+ 'however',
51
+ 'i',
52
+ 'if',
53
+ 'in',
54
+ 'into',
55
+ 'is',
56
+ 'it',
57
+ 'its',
58
+ 'itself',
59
+ 'just',
60
+ 'may',
61
+ 'me',
62
+ 'might',
63
+ 'more',
64
+ 'most',
65
+ 'much',
66
+ 'must',
67
+ 'my',
68
+ 'no',
69
+ 'nor',
70
+ 'not',
71
+ 'now',
72
+ 'of',
73
+ 'off',
74
+ 'on',
75
+ 'once',
76
+ 'only',
77
+ 'or',
78
+ 'other',
79
+ 'our',
80
+ 'out',
81
+ 'over',
82
+ 'own',
83
+ 'said',
84
+ 'same',
85
+ 'she',
86
+ 'should',
87
+ 'so',
88
+ 'some',
89
+ 'such',
90
+ 'than',
91
+ 'that',
92
+ 'the',
93
+ 'their',
94
+ 'them',
95
+ 'then',
96
+ 'there',
97
+ 'these',
98
+ 'they',
99
+ 'this',
100
+ 'those',
101
+ 'through',
102
+ 'to',
103
+ 'too',
104
+ 'under',
105
+ 'until',
106
+ 'up',
107
+ 'use',
108
+ 'used',
109
+ 'using',
110
+ 'very',
111
+ 'was',
112
+ 'we',
113
+ 'were',
114
+ 'what',
115
+ 'when',
116
+ 'where',
117
+ 'which',
118
+ 'while',
119
+ 'who',
120
+ 'whom',
121
+ 'why',
122
+ 'will',
123
+ 'with',
124
+ 'would',
125
+ 'you',
126
+ 'your',
127
+ 'yours',
128
+ ]);
129
+ export function isStopword(token) {
130
+ return STOPWORDS.has(token);
131
+ }
132
+ export function meaningfulTokens(text) {
133
+ return text
134
+ .toLowerCase()
135
+ .split(/[^\p{L}\p{N}_]+/u)
136
+ .filter((token) => token.length > 1 && !isStopword(token));
137
+ }
@@ -1,6 +1,7 @@
1
1
  import { partitionIds } from '../../util/shortid.js';
2
2
  import { resolve } from 'node:path';
3
3
  import { scopeToken } from '../../util/scope.js';
4
+ import { meaningfulTokens } from '../../search/stopwords.js';
4
5
  export function removeWhere(filter) {
5
6
  const conditions = [];
6
7
  const params = [];
@@ -58,13 +59,10 @@ export function appendScope(query, conditions, params, prefix) {
58
59
  }
59
60
  }
60
61
  export function toMatchExpression(text, project) {
61
- const tokens = text
62
- .toLowerCase()
63
- .split(/[^\p{L}\p{N}_]+/u)
64
- .filter((token) => token.length > 1);
62
+ const tokens = meaningfulTokens(text);
65
63
  const scope = project ? `scope:${scopeToken(project)}` : null;
66
64
  if (tokens.length === 0)
67
- return scope;
65
+ return null;
68
66
  const terms = tokens.map((token) => `"${token}"`).join(' OR ');
69
67
  return scope ? `${scope} AND (${terms})` : terms;
70
68
  }
@@ -20,4 +20,4 @@ export interface FindUsagesInput {
20
20
  }
21
21
  export declare function findUsages(input: FindUsagesInput): UsagesResult;
22
22
  export declare function repoRootFor(start: string): string;
23
- export declare function formatUsages(result: UsagesResult): string;
23
+ export declare function formatUsages(result: UsagesResult, suggestions?: string[]): string;
@@ -116,9 +116,11 @@ function isDefinitionLike(symbol, text) {
116
116
  `|(?:export\\s+)?(?:const|let|var)\\s+${s}\\s*[:=]` +
117
117
  `|export\\s*\\{[^}]*\\b${s}\\b)`).test(text);
118
118
  }
119
- export function formatUsages(result) {
120
- if (result.matches.length === 0)
121
- return `No usages of that symbol found under ${result.root}.`;
119
+ export function formatUsages(result, suggestions = []) {
120
+ if (result.matches.length === 0) {
121
+ return (`No usages of that symbol found under ${result.root}.` +
122
+ (suggestions.length > 0 ? `\nDid you mean: ${suggestions.join(', ')}` : ''));
123
+ }
122
124
  const rows = result.matches.map((m) => `${m.file}${m.isMatch ? ':' : '-'}${m.line}${m.isDefinition ? ' [definition?]' : ''} ${m.text.trim()}`);
123
125
  const shown = result.matches.filter((m) => m.isMatch).length;
124
126
  const header = result.truncated
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-db",
3
- "version": "0.5.4",
3
+ "version": "0.6.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",