claude-db 0.5.3 → 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.
- package/CHANGELOG.md +96 -0
- package/README.md +74 -45
- package/dist/capture/flush.js +16 -8
- package/dist/cli/commands/graph.js +14 -2
- package/dist/cli/commands/transfer.d.ts +1 -1
- package/dist/cli/commands/transfer.js +4 -2
- package/dist/cli/index.js +1 -1
- package/dist/cli/install.js +1 -0
- package/dist/cli/usage.js +1 -1
- package/dist/config/schema.d.ts +2 -1
- package/dist/config/schema.js +2 -1
- package/dist/graph/index.d.ts +2 -2
- package/dist/graph/index.js +2 -2
- package/dist/graph/query/format.js +7 -3
- package/dist/graph/query/index.d.ts +1 -0
- package/dist/graph/query/index.js +1 -0
- package/dist/graph/query/lookup.d.ts +1 -0
- package/dist/graph/query/lookup.js +6 -0
- package/dist/graph/query/suggest.d.ts +5 -0
- package/dist/graph/query/suggest.js +65 -0
- package/dist/graph/scan/files.d.ts +1 -0
- package/dist/graph/scan/files.js +8 -2
- package/dist/graph/scan/index.d.ts +1 -1
- package/dist/graph/scan/index.js +1 -1
- package/dist/hooks/grep-symbols.d.ts +3 -0
- package/dist/hooks/grep-symbols.js +22 -0
- package/dist/hooks/prefer-usages.d.ts +2 -0
- package/dist/hooks/prefer-usages.js +58 -0
- package/dist/mcp/server.js +6 -170
- package/dist/mcp/tools/kinds.d.ts +1 -0
- package/dist/mcp/tools/kinds.js +1 -0
- package/dist/mcp/tools/memory.d.ts +3 -0
- package/dist/mcp/tools/memory.js +44 -0
- package/dist/mcp/tools/observations.d.ts +3 -0
- package/dist/mcp/tools/observations.js +55 -0
- package/dist/mcp/tools/search.d.ts +3 -0
- package/dist/mcp/tools/search.js +54 -0
- package/dist/mcp/tools/usages.d.ts +3 -0
- package/dist/mcp/tools/usages.js +79 -0
- package/dist/search/service.js +3 -0
- package/dist/search/stopwords.d.ts +2 -0
- package/dist/search/stopwords.js +137 -0
- package/dist/store/sqlite/filters.js +3 -5
- package/dist/usages/find.d.ts +1 -1
- package/dist/usages/find.js +5 -3
- package/docs/how-it-works.md +12 -12
- package/docs/with-and-without.md +123 -0
- package/package.json +3 -1
- package/docs/mcp-findings.md +0 -391
- package/docs/token-economics.md +0 -216
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,101 @@
|
|
|
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
|
+
|
|
69
|
+
## 0.5.4
|
|
70
|
+
|
|
71
|
+
### Fixed
|
|
72
|
+
|
|
73
|
+
- **`reembed` could exhaust memory on a large database.** ([#7](https://github.com/Avijit07x/claude-db/issues/7))
|
|
74
|
+
Embedding walked the store 500 rows at a time and handed all 500 to a single
|
|
75
|
+
`embedder.embed()` call, which became one forward pass over 500 sequences in
|
|
76
|
+
the local model. Peak memory was set by that batch, so a database whose rows
|
|
77
|
+
were long enough went to swap and never came back. Embedding is now chunked by
|
|
78
|
+
`embeddings.batchSize`, so peak memory is a property of the chunk rather than
|
|
79
|
+
of the database: re-embedding 1,400 observations holds ~0.8 GB and takes the
|
|
80
|
+
same time per row as re-embedding 128. The chunking lives in
|
|
81
|
+
`embedObservations`, the one call every path routes through, so `flush`,
|
|
82
|
+
`seed` and `manual` capture are bounded by the same change — `seed` had the
|
|
83
|
+
identical ceiling and would have hit it on a large enough repo.
|
|
84
|
+
|
|
85
|
+
### Added
|
|
86
|
+
|
|
87
|
+
- **`embeddings.batchSize`, default 8.** Measured on `all-MiniLM-L6-v2` with
|
|
88
|
+
worst-case 512-token observations, peak RSS runs 0.8 GB at 8, 1.3 GB at 16,
|
|
89
|
+
2.4 GB at 32 and 4.5 GB at 64 — while wall-clock stays flat from 1 to 8,
|
|
90
|
+
because CPU inference is compute-bound and the token count is the same however
|
|
91
|
+
it is grouped. Batching buys no speed here and only costs memory, so the
|
|
92
|
+
default is deliberately small; lower it further if you are tight on RAM.
|
|
93
|
+
|
|
94
|
+
- **`reembed --project`.** `reembed` re-embedded every project on the machine
|
|
95
|
+
with no way to narrow it. On a database holding several projects that is the
|
|
96
|
+
difference between minutes and seconds, and the work skipped is work that
|
|
97
|
+
never has to be bounded. Without the flag the behaviour is unchanged.
|
|
98
|
+
|
|
3
99
|
## 0.5.3
|
|
4
100
|
|
|
5
101
|
### Fixed
|
package/README.md
CHANGED
|
@@ -6,18 +6,32 @@
|
|
|
6
6
|
[](https://github.com/Avijit07x/claude-db/actions/workflows/ci.yml)
|
|
7
7
|
[](./LICENSE)
|
|
8
8
|
|
|
9
|
+
[Documentation](https://claude-db.vercel.app/docs) ·
|
|
10
|
+
[Quick start](https://claude-db.vercel.app/docs/quick-start) ·
|
|
11
|
+
[CLI reference](https://claude-db.vercel.app/docs/cli)
|
|
12
|
+
|
|
9
13
|
---
|
|
10
14
|
|
|
11
|
-
##
|
|
15
|
+
## Every session starts from zero
|
|
16
|
+
|
|
17
|
+
You spent an hour yesterday explaining why the store uses three adapters, which
|
|
18
|
+
approach you already tried and abandoned, and why that one function must not be
|
|
19
|
+
touched. Today Claude knows none of it. So you explain it again.
|
|
12
20
|
|
|
13
|
-
|
|
14
|
-
|
|
21
|
+
claude-db fixes that, and the other half too. Claude re-derives your codebase
|
|
22
|
+
every time, grepping a name and opening files to work out what calls what.
|
|
15
23
|
|
|
16
|
-
|
|
17
|
-
|
|
24
|
+
```console
|
|
25
|
+
$ claude-db search "why does capture read the transcript"
|
|
18
26
|
|
|
19
|
-
|
|
20
|
-
|
|
27
|
+
83cf1246-eb14 decision 2026-08-19 Tested and written up.
|
|
28
|
+
…the old defaults prompt was now cut why does capture read the transcript…
|
|
29
|
+
88fab24f-5e59 decision 2026-08-19 Finding 4's other half needs checking…
|
|
30
|
+
…cannot work: 0.029483 "why does capture read…" <- highly relevant…
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
You never run that command. Claude gets the same context injected on every
|
|
34
|
+
prompt, so it walks in already knowing. Nothing leaves your machine.
|
|
21
35
|
|
|
22
36
|
## Install
|
|
23
37
|
|
|
@@ -28,27 +42,26 @@ cd your-project
|
|
|
28
42
|
claude-db install --project
|
|
29
43
|
```
|
|
30
44
|
|
|
31
|
-
Restart Claude Code. That's it
|
|
45
|
+
Restart Claude Code. That's it: capture and recall are hooks, so they run
|
|
32
46
|
without being asked.
|
|
33
47
|
|
|
34
48
|
`--project` scopes to one repo instead of every project on the machine. It
|
|
35
|
-
writes `.claude/settings.local.json` and `.mcp.json
|
|
49
|
+
writes `.claude/settings.local.json` and `.mcp.json`. Add `.mcp.json` to your
|
|
36
50
|
`.gitignore`, since it holds a machine-specific path.
|
|
37
51
|
|
|
38
52
|
## Map your code
|
|
39
53
|
|
|
54
|
+
Memory fills itself as you work. The code graph needs one command:
|
|
55
|
+
|
|
40
56
|
```bash
|
|
41
57
|
claude-db scan
|
|
42
|
-
|
|
43
|
-
claude-db usages --mode explain resolveProject
|
|
44
|
-
claude-db usages --mode path cmdScan observationId
|
|
45
58
|
```
|
|
46
59
|
|
|
47
|
-
Claude gets
|
|
48
|
-
|
|
49
|
-
|
|
60
|
+
Claude then gets four modes through MCP: `text` (a live grep, works with no
|
|
61
|
+
scan at all), `usages`, `explain` and `path`. Re-running `scan` is cheap: it
|
|
62
|
+
hashes files and re-parses only what changed.
|
|
50
63
|
|
|
51
|
-
Works out of the box on TypeScript, TSX, JavaScript, Python, Go and Rust
|
|
64
|
+
Works out of the box on TypeScript, TSX, JavaScript, Python, Go and Rust. The
|
|
52
65
|
parser ships with the package, so there is nothing else to install.
|
|
53
66
|
|
|
54
67
|
## Use another database
|
|
@@ -64,33 +77,42 @@ claude-db use "postgres://user:pass@host:5432/memory"
|
|
|
64
77
|
Install the driver you need (`npm install mongodb` or `pg`); neither ships by
|
|
65
78
|
default.
|
|
66
79
|
|
|
80
|
+
## With it, and without it
|
|
81
|
+
|
|
82
|
+
Asking _who defines and calls `closeObservations`_ by hand means a grep, then
|
|
83
|
+
opening three store adapters to see which hits are definitions. One `explain`
|
|
84
|
+
call answers it already classified: **2.1x cheaper**, measured across eight
|
|
85
|
+
real symbols in this repo.
|
|
86
|
+
|
|
87
|
+
Recall is the standing cost of ~180 tokens a prompt, skipped entirely on 28% of
|
|
88
|
+
prompts because the answer is already in context:
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
every prompt costs 180 tokens of recall
|
|
92
|
+
every lookup refunds 597 tokens (1,115 by hand - 518 with)
|
|
93
|
+
|
|
94
|
+
so one lookup pays for 3.3 prompts of recall
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Check it on your own repo with `npm run bench:ab` and `npm run bench:tokens`
|
|
98
|
+
from a clone. [With and without](./docs/with-and-without.md) has every number,
|
|
99
|
+
including the symbols where plain grep wins.
|
|
100
|
+
|
|
67
101
|
## Commands
|
|
68
102
|
|
|
69
|
-
`cdb` is a shorter alias for all of them.
|
|
70
|
-
|
|
71
|
-
| Command
|
|
72
|
-
|
|
|
73
|
-
| `claude-db install [--project]`
|
|
74
|
-
| `claude-db
|
|
75
|
-
| `claude-db
|
|
76
|
-
| `claude-db
|
|
77
|
-
| `claude-db
|
|
78
|
-
| `claude-db
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
| `claude-db usages [--mode <m>] <symbol>` | What uses a symbol: live `git grep`, or the code graph |
|
|
83
|
-
| `claude-db stats` | What this project's memory is made of |
|
|
84
|
-
| `claude-db projects` | Every project with memory stored |
|
|
85
|
-
| `claude-db merge [<path>]` | Move memory from an old project path onto this one |
|
|
86
|
-
| `claude-db use <url>` | Switch database and verify it |
|
|
87
|
-
| `claude-db sync <url>` | Two-way merge with another database |
|
|
88
|
-
| `claude-db flush` | Re-ingest every transcript for this project |
|
|
89
|
-
| `claude-db export [--all]` | Dump memory as JSONL, for backup or migration |
|
|
90
|
-
| `claude-db import <file>` | Load a dump back in; safe to repeat |
|
|
91
|
-
| `claude-db reembed` | Re-embed everything with the current model |
|
|
92
|
-
| `claude-db prune --older-than <days>` | Delete old memory (dry run without `--yes`) |
|
|
93
|
-
| `claude-db reset [--project] --yes` | Delete memory (dry run without `--yes`) |
|
|
103
|
+
`cdb` is a shorter alias for all of them. These are the ones you actually type:
|
|
104
|
+
|
|
105
|
+
| Command | What it does |
|
|
106
|
+
| ---------------------------------------- | ------------------------------------------------------ |
|
|
107
|
+
| `claude-db install [--project]` | Register hooks and the MCP server |
|
|
108
|
+
| `claude-db status` | Is it wired up, and when did it last record anything |
|
|
109
|
+
| `claude-db doctor [--deep]` | Resolved config; `--deep` proves a full round trip |
|
|
110
|
+
| `claude-db scan [--force]` | Build the code graph for this repo |
|
|
111
|
+
| `claude-db usages [--mode <m>] <symbol>` | What uses a symbol: live `git grep`, or the code graph |
|
|
112
|
+
| `claude-db use <url>` | Switch database and verify it |
|
|
113
|
+
|
|
114
|
+
Every other command, including `search`, `remember`, `seed`, `sync`, `export`,
|
|
115
|
+
`prune` and `reset`, is in the [CLI reference](https://claude-db.vercel.app/docs/cli).
|
|
94
116
|
|
|
95
117
|
Install also adds a `/cdb-scan` skill: run it once on an existing project and
|
|
96
118
|
Claude maps the codebase into memory, so search has something to find before
|
|
@@ -113,16 +135,23 @@ before anything is written.
|
|
|
113
135
|
|
|
114
136
|
## Documentation
|
|
115
137
|
|
|
116
|
-
-
|
|
117
|
-
|
|
118
|
-
|
|
138
|
+
**[claude-db.vercel.app/docs](https://claude-db.vercel.app/docs)** has the rest:
|
|
139
|
+
the [CLI reference](https://claude-db.vercel.app/docs/cli),
|
|
140
|
+
[MCP tools](https://claude-db.vercel.app/docs/mcp-tools),
|
|
141
|
+
[how it works](https://claude-db.vercel.app/docs/how-it-works),
|
|
142
|
+
[databases](https://claude-db.vercel.app/docs/databases) and
|
|
143
|
+
[troubleshooting](https://claude-db.vercel.app/docs/troubleshooting).
|
|
144
|
+
|
|
145
|
+
[Benchmarks](https://claude-db.vercel.app/docs/benchmarks) has every number,
|
|
146
|
+
including the symbols where plain grep wins. Releases are in the
|
|
147
|
+
[changelog](./CHANGELOG.md).
|
|
119
148
|
|
|
120
149
|
## Development
|
|
121
150
|
|
|
122
151
|
```bash
|
|
123
152
|
npm install
|
|
124
153
|
npm run build
|
|
125
|
-
npm test #
|
|
154
|
+
npm test # 326 checks
|
|
126
155
|
npm run try # simulate a session, touches nothing
|
|
127
156
|
npm run format
|
|
128
157
|
```
|
package/dist/capture/flush.js
CHANGED
|
@@ -36,14 +36,22 @@ export async function embedObservations(ctx, observations) {
|
|
|
36
36
|
const embedder = await ctx.embedder();
|
|
37
37
|
if (embedder.dimensions === 0)
|
|
38
38
|
return;
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
39
|
+
// ponytail: chunked because peak memory scales with the batch handed to one
|
|
40
|
+
// forward pass, not with the database. Measured on all-MiniLM-L6-v2, 512-token
|
|
41
|
+
// bodies: 8 -> 0.8GB, 16 -> 1.3GB, 32 -> 2.4GB, 64 -> 4.5GB, all at identical
|
|
42
|
+
// wall-clock. Batching buys nothing on CPU, so keep it small.
|
|
43
|
+
const size = ctx.config.embeddings.batchSize;
|
|
44
|
+
for (let start = 0; start < observations.length; start += size) {
|
|
45
|
+
const chunk = observations.slice(start, start + size);
|
|
46
|
+
const vectors = await embedder.embed(chunk.map((obs) => `${obs.title}\n${obs.body}`));
|
|
47
|
+
chunk.forEach((obs, index) => {
|
|
48
|
+
const vector = vectors[index];
|
|
49
|
+
if (vector && vector.length > 0) {
|
|
50
|
+
obs.embedding = vector;
|
|
51
|
+
obs.embedder = embedder.id;
|
|
52
|
+
}
|
|
53
|
+
});
|
|
54
|
+
}
|
|
47
55
|
}
|
|
48
56
|
catch (error) {
|
|
49
57
|
process.stderr.write(`[claude-db] embedding skipped: ` +
|
|
@@ -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
|
-
|
|
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
|
+
}
|
|
@@ -6,4 +6,4 @@ export declare function eachObservation(ctx: RecallContext, filter: {
|
|
|
6
6
|
export declare function cmdExport(argv: (string | undefined)[]): Promise<void>;
|
|
7
7
|
export declare function cmdImport(path: string | undefined): Promise<void>;
|
|
8
8
|
export declare function cmdPrune(argv: (string | undefined)[]): Promise<void>;
|
|
9
|
-
export declare function cmdReembed(): Promise<void>;
|
|
9
|
+
export declare function cmdReembed(argv?: (string | undefined)[]): Promise<void>;
|
|
@@ -98,7 +98,8 @@ export async function cmdPrune(argv) {
|
|
|
98
98
|
await ctx.close();
|
|
99
99
|
}
|
|
100
100
|
}
|
|
101
|
-
export async function cmdReembed() {
|
|
101
|
+
export async function cmdReembed(argv = []) {
|
|
102
|
+
const scoped = argv.includes('--project') || argv.includes('-p');
|
|
102
103
|
const base = loadConfig();
|
|
103
104
|
const ctx = await createContext({ embeddings: { ...base.embeddings, timeoutMs: 0 } });
|
|
104
105
|
try {
|
|
@@ -109,7 +110,8 @@ export async function cmdReembed() {
|
|
|
109
110
|
}
|
|
110
111
|
let updated = 0;
|
|
111
112
|
let skipped = 0;
|
|
112
|
-
const
|
|
113
|
+
const filter = scoped ? { project: resolveProject(undefined) } : {};
|
|
114
|
+
const scanned = await eachObservation(ctx, filter, async (batch) => {
|
|
113
115
|
const stale = batch.filter((obs) => obs.embedder !== embedder.id);
|
|
114
116
|
skipped += batch.length - stale.length;
|
|
115
117
|
if (stale.length === 0)
|
package/dist/cli/index.js
CHANGED
package/dist/cli/install.js
CHANGED
|
@@ -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'];
|
package/dist/cli/usage.js
CHANGED
|
@@ -25,7 +25,7 @@ export function usage() {
|
|
|
25
25
|
import <file.jsonl> Load a dump back in (safe to repeat)
|
|
26
26
|
sync <url> [--yes] Two-way merge with another database
|
|
27
27
|
update Install a newer compatible release now
|
|
28
|
-
reembed
|
|
28
|
+
reembed [--project] Re-embed with the current model
|
|
29
29
|
prune --older-than <days> Delete old memory (dry run without --yes)
|
|
30
30
|
reset [--project] --yes Delete stored memory (dry run without --yes)
|
|
31
31
|
|
package/dist/config/schema.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
2
|
export declare const ConfigSchema: z.ZodObject<{
|
|
3
3
|
database: z.ZodDefault<z.ZodString>;
|
|
4
|
-
embeddings: z.
|
|
4
|
+
embeddings: z.ZodPrefault<z.ZodObject<{
|
|
5
5
|
provider: z.ZodDefault<z.ZodEnum<{
|
|
6
6
|
auto: "auto";
|
|
7
7
|
local: "local";
|
|
@@ -10,6 +10,7 @@ export declare const ConfigSchema: z.ZodObject<{
|
|
|
10
10
|
}>>;
|
|
11
11
|
maxScanCandidates: z.ZodDefault<z.ZodNumber>;
|
|
12
12
|
timeoutMs: z.ZodDefault<z.ZodNumber>;
|
|
13
|
+
batchSize: z.ZodDefault<z.ZodNumber>;
|
|
13
14
|
}, z.core.$strip>>;
|
|
14
15
|
updates: z.ZodDefault<z.ZodEnum<{
|
|
15
16
|
auto: "auto";
|
package/dist/config/schema.js
CHANGED
|
@@ -6,8 +6,9 @@ export const ConfigSchema = z.object({
|
|
|
6
6
|
provider: z.enum(['auto', 'local', 'builtin', 'none']).default('auto'),
|
|
7
7
|
maxScanCandidates: z.number().int().positive().default(25000),
|
|
8
8
|
timeoutMs: z.number().int().nonnegative().default(3000),
|
|
9
|
+
batchSize: z.number().int().positive().default(8),
|
|
9
10
|
})
|
|
10
|
-
.
|
|
11
|
+
.prefault({}),
|
|
11
12
|
updates: z.enum(['auto', 'notify', 'off']).default('notify'),
|
|
12
13
|
capture: z
|
|
13
14
|
.object({
|
package/dist/graph/index.d.ts
CHANGED
|
@@ -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';
|
package/dist/graph/index.js
CHANGED
|
@@ -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}]`);
|
|
@@ -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[];
|
package/dist/graph/scan/files.js
CHANGED
|
@@ -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;
|