claude-db 0.4.1 → 0.5.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 +399 -0
- package/README.md +62 -94
- package/dist/capture/command.d.ts +0 -14
- package/dist/capture/command.js +0 -23
- package/dist/capture/flush.d.ts +1 -50
- package/dist/capture/flush.js +4 -63
- package/dist/capture/git.js +0 -20
- package/dist/capture/identity.d.ts +0 -17
- package/dist/capture/identity.js +1 -21
- package/dist/capture/index.d.ts +1 -0
- package/dist/capture/index.js +1 -0
- package/dist/capture/manual.d.ts +0 -19
- package/dist/capture/manual.js +0 -0
- package/dist/capture/progress.d.ts +4 -0
- package/dist/capture/progress.js +33 -0
- package/dist/capture/transcript.d.ts +0 -45
- package/dist/capture/transcript.js +4 -70
- package/dist/capture/turn-extractor.d.ts +0 -15
- package/dist/capture/turn-extractor.js +1 -104
- package/dist/cli/args.d.ts +4 -0
- package/dist/cli/args.js +16 -0
- package/dist/cli/commands/doctor.d.ts +1 -0
- package/dist/cli/commands/doctor.js +76 -0
- package/dist/cli/commands/graph.d.ts +2 -0
- package/dist/cli/commands/graph.js +93 -0
- package/dist/cli/commands/insight.d.ts +3 -0
- package/dist/cli/commands/insight.js +129 -0
- package/dist/cli/commands/maintain.d.ts +3 -0
- package/dist/cli/commands/maintain.js +77 -0
- package/dist/cli/commands/memory.d.ts +3 -0
- package/dist/cli/commands/memory.js +77 -0
- package/dist/cli/commands/seed.d.ts +1 -0
- package/dist/cli/commands/seed.js +43 -0
- package/dist/cli/commands/setup.d.ts +4 -0
- package/dist/cli/commands/setup.js +156 -0
- package/dist/cli/commands/sync.d.ts +1 -0
- package/dist/cli/commands/sync.js +95 -0
- package/dist/cli/commands/transfer.d.ts +9 -0
- package/dist/cli/commands/transfer.js +129 -0
- package/dist/cli/commands/use.d.ts +1 -0
- package/dist/cli/commands/use.js +90 -0
- package/dist/cli/constants.d.ts +2 -0
- package/dist/cli/constants.js +4 -0
- package/dist/cli/files.d.ts +4 -0
- package/dist/cli/files.js +33 -0
- package/dist/cli/index.js +15 -1080
- package/dist/cli/install.d.ts +1 -59
- package/dist/cli/install.js +5 -194
- package/dist/cli/instructions.d.ts +5 -0
- package/dist/cli/instructions.js +55 -0
- package/dist/cli/paths.d.ts +5 -0
- package/dist/cli/paths.js +19 -0
- package/dist/cli/refresh.d.ts +1 -0
- package/dist/cli/refresh.js +25 -0
- package/dist/cli/usage.d.ts +1 -0
- package/dist/cli/usage.js +39 -0
- package/dist/config/load.d.ts +0 -5
- package/dist/config/load.js +1 -8
- package/dist/config/schema.js +2 -58
- package/dist/context.d.ts +0 -10
- package/dist/context.js +0 -16
- package/dist/embed/builtin.d.ts +0 -12
- package/dist/embed/builtin.js +0 -20
- package/dist/embed/embedder.d.ts +0 -14
- package/dist/embed/embedder.js +0 -1
- package/dist/embed/index.d.ts +0 -9
- package/dist/embed/index.js +0 -9
- package/dist/embed/local.d.ts +0 -8
- package/dist/embed/local.js +0 -12
- package/dist/graph/index.d.ts +7 -0
- package/dist/graph/index.js +4 -0
- package/dist/graph/languages/ecmascript.d.ts +4 -0
- package/dist/graph/languages/ecmascript.js +47 -0
- package/dist/graph/languages/go.d.ts +2 -0
- package/dist/graph/languages/go.js +15 -0
- package/dist/graph/languages/index.d.ts +6 -0
- package/dist/graph/languages/index.js +20 -0
- package/dist/graph/languages/python.d.ts +2 -0
- package/dist/graph/languages/python.js +15 -0
- package/dist/graph/languages/rules.d.ts +18 -0
- package/dist/graph/languages/rules.js +1 -0
- package/dist/graph/languages/rust.d.ts +2 -0
- package/dist/graph/languages/rust.js +16 -0
- package/dist/graph/parser.d.ts +31 -0
- package/dist/graph/parser.js +29 -0
- package/dist/graph/query/format.d.ts +2 -0
- package/dist/graph/query/format.js +41 -0
- package/dist/graph/query/index.d.ts +5 -0
- package/dist/graph/query/index.js +4 -0
- package/dist/graph/query/lookup.d.ts +21 -0
- package/dist/graph/query/lookup.js +35 -0
- package/dist/graph/query/path.d.ts +2 -0
- package/dist/graph/query/path.js +48 -0
- package/dist/graph/query/refresh.d.ts +2 -0
- package/dist/graph/query/refresh.js +21 -0
- package/dist/graph/scan/extract.d.ts +15 -0
- package/dist/graph/scan/extract.js +101 -0
- package/dist/graph/scan/files.d.ts +12 -0
- package/dist/graph/scan/files.js +51 -0
- package/dist/graph/scan/index.d.ts +18 -0
- package/dist/graph/scan/index.js +44 -0
- package/dist/graph/scan/resolve.d.ts +3 -0
- package/dist/graph/scan/resolve.js +48 -0
- package/dist/hooks/payload.d.ts +0 -8
- package/dist/hooks/payload.js +0 -6
- package/dist/hooks/relevance.d.ts +0 -17
- package/dist/hooks/relevance.js +55 -38
- package/dist/hooks/session-end.js +0 -11
- package/dist/hooks/session-start.js +33 -14
- package/dist/hooks/user-prompt.js +0 -18
- package/dist/mcp/render.d.ts +0 -20
- package/dist/mcp/render.js +0 -39
- package/dist/mcp/server.js +46 -25
- package/dist/search/rank.d.ts +0 -14
- package/dist/search/rank.js +0 -16
- package/dist/search/service.d.ts +1 -32
- package/dist/search/service.js +1 -36
- package/dist/store/adapter.d.ts +11 -44
- package/dist/store/adapter.js +1 -12
- package/dist/store/index.d.ts +0 -11
- package/dist/store/index.js +0 -11
- package/dist/store/mongo/docs.d.ts +61 -0
- package/dist/store/mongo/docs.js +106 -0
- package/dist/store/mongo/driver.d.ts +1 -15
- package/dist/store/mongo/driver.js +0 -15
- package/dist/store/mongo/filters.d.ts +6 -0
- package/dist/store/mongo/filters.js +18 -0
- package/dist/store/mongo/graph.d.ts +12 -0
- package/dist/store/mongo/graph.js +61 -0
- package/dist/store/mongo/helpers.d.ts +2 -0
- package/dist/store/mongo/helpers.js +8 -0
- package/dist/store/mongo/index.d.ts +16 -13
- package/dist/store/mongo/index.js +52 -295
- package/dist/store/mongo/observations.d.ts +10 -0
- package/dist/store/mongo/observations.js +97 -0
- package/dist/store/mongo/search.d.ts +6 -0
- package/dist/store/mongo/search.js +51 -0
- package/dist/store/mongo/sessions.d.ts +6 -0
- package/dist/store/mongo/sessions.js +24 -0
- package/dist/store/mongo/vectorSearch.d.ts +5 -0
- package/dist/store/mongo/vectorSearch.js +57 -0
- package/dist/store/postgres/driver.d.ts +19 -0
- package/dist/store/postgres/driver.js +13 -0
- package/dist/store/postgres/filters.d.ts +2 -0
- package/dist/store/postgres/filters.js +22 -0
- package/dist/store/postgres/graph.d.ts +11 -0
- package/dist/store/postgres/graph.js +115 -0
- package/dist/store/postgres/index.d.ts +20 -33
- package/dist/store/postgres/index.js +43 -428
- package/dist/store/postgres/insert.d.ts +3 -0
- package/dist/store/postgres/insert.js +59 -0
- package/dist/store/postgres/meta.d.ts +10 -0
- package/dist/store/postgres/meta.js +54 -0
- package/dist/store/postgres/observations.d.ts +10 -0
- package/dist/store/postgres/observations.js +139 -0
- package/dist/store/postgres/rows.d.ts +6 -0
- package/dist/store/postgres/rows.js +74 -0
- package/dist/store/postgres/schema.d.ts +3 -0
- package/dist/store/postgres/schema.js +84 -0
- package/dist/store/postgres/search.d.ts +3 -0
- package/dist/store/postgres/search.js +20 -0
- package/dist/store/postgres/sessions.d.ts +5 -0
- package/dist/store/postgres/sessions.js +26 -0
- package/dist/store/postgres/vectorSearch.d.ts +3 -0
- package/dist/store/postgres/vectorSearch.js +21 -0
- package/dist/store/sqlite/filters.d.ts +9 -0
- package/dist/store/sqlite/filters.js +77 -0
- package/dist/store/sqlite/graph.d.ts +11 -0
- package/dist/store/sqlite/graph.js +100 -0
- package/dist/store/sqlite/index.d.ts +12 -10
- package/dist/store/sqlite/index.js +41 -379
- package/dist/store/sqlite/observations.d.ts +10 -0
- package/dist/store/sqlite/observations.js +128 -0
- package/dist/store/sqlite/rows.d.ts +8 -0
- package/dist/store/sqlite/rows.js +84 -0
- package/dist/store/sqlite/schema.sql +42 -2
- package/dist/store/sqlite/search.d.ts +5 -0
- package/dist/store/sqlite/search.js +86 -0
- package/dist/store/sqlite/sessions.d.ts +5 -0
- package/dist/store/sqlite/sessions.js +21 -0
- package/dist/types.d.ts +47 -40
- package/dist/types.js +0 -4
- package/dist/update.d.ts +0 -20
- package/dist/update.js +4 -29
- package/dist/usages/find.d.ts +2 -8
- package/dist/usages/find.js +51 -54
- package/dist/usages/index.d.ts +1 -1
- package/dist/usages/index.js +1 -1
- package/dist/util/project.d.ts +0 -12
- package/dist/util/project.js +0 -24
- package/dist/util/scope.d.ts +0 -9
- package/dist/util/scope.js +0 -9
- package/dist/util/shortid.d.ts +0 -5
- package/dist/util/shortid.js +1 -19
- package/dist/util/snippet.d.ts +0 -26
- package/dist/util/snippet.js +0 -30
- package/dist/util/vector.d.ts +0 -12
- package/dist/util/vector.js +0 -12
- package/dist/util/warnings.d.ts +0 -11
- package/dist/util/warnings.js +0 -11
- package/docs/how-it-works.md +183 -0
- package/package.json +14 -3
- package/skills/cdb-scan/SKILL.md +31 -6
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,399 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.5.0
|
|
4
|
+
|
|
5
|
+
`find_usages` could only ever answer "where does this string appear". It could
|
|
6
|
+
not say *how* two things relate — a call, an import, an inherit — or trace how
|
|
7
|
+
one symbol reaches another, and it re-paid the full search cost on every
|
|
8
|
+
question.
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **A code graph, built by `claude-db scan`.** Every source file is parsed with
|
|
13
|
+
ast-grep and stored as symbols plus the relationships between them. Parsing
|
|
14
|
+
is local, deterministic and costs no tokens; a rescan re-parses only files
|
|
15
|
+
whose contents changed, so it is seconds the first time and milliseconds
|
|
16
|
+
after. TypeScript, TSX, JavaScript, Python, Go and Rust, with the parser
|
|
17
|
+
shipped as a prebuilt binary per platform so nothing compiles at install
|
|
18
|
+
- **Three new `find_usages` modes**, on the CLI and over MCP: `usages` lists
|
|
19
|
+
what references a symbol with the relation on each line, `explain` adds what
|
|
20
|
+
the symbol reaches, and `path` traces how two symbols connect. `text` remains
|
|
21
|
+
the default and still needs no scan
|
|
22
|
+
- **Every edge carries its confidence.** `EXTRACTED` means it was read literally
|
|
23
|
+
out of the syntax tree; `INFERRED` means the target was matched by name across
|
|
24
|
+
files, and carries a score. Name matching is the one guess this makes, so it
|
|
25
|
+
is labelled rather than presented as fact
|
|
26
|
+
- **A class links to the members it defines**, so a path can cross the class
|
|
27
|
+
boundary — `boot --> App --> start --> helper` rather than stopping dead at
|
|
28
|
+
the class, which is where the obvious chain used to break
|
|
29
|
+
- **Work is tracked as unfinished until it is committed.** A captured turn is
|
|
30
|
+
stored `open` and closes once every file it touched has landed in a commit,
|
|
31
|
+
which the existing flush already checks — there is no new hook to stop
|
|
32
|
+
firing. `claude-db status` lists what is still open, and SessionStart injects
|
|
33
|
+
the newest few, so a fresh chat can answer "what was I doing" instead of
|
|
34
|
+
searching for words that a prompt like "do the last task" does not contain.
|
|
35
|
+
Closing is one-way: touching a file again does not reopen finished work, and
|
|
36
|
+
rows written before this release stay `done` rather than all appearing
|
|
37
|
+
unfinished
|
|
38
|
+
- **Updating the package is now enough.** The skill and the standing
|
|
39
|
+
instruction were copied to disk at install time, so `npm i -g claude-db` left
|
|
40
|
+
them frozen at whatever shipped when install was last run — you had to
|
|
41
|
+
remember to re-run it. The hooks are registered by absolute path into the
|
|
42
|
+
package, so they always run the current code; SessionStart now compares those
|
|
43
|
+
copies against the packaged ones and repairs them. It only ever refreshes
|
|
44
|
+
what already exists, so nothing is installed behind your back and an
|
|
45
|
+
uninstalled skill is not resurrected
|
|
46
|
+
- **`/cdb-scan` now runs in two passes** — the deterministic graph first, then
|
|
47
|
+
the written `profile:*` notes on top of it
|
|
48
|
+
|
|
49
|
+
### Fixed
|
|
50
|
+
|
|
51
|
+
- **A NUL byte in `src/capture/manual.ts` made the whole file invisible to**
|
|
52
|
+
**`find_usages`.** It was committed, renders as a space in every editor, and
|
|
53
|
+
made git classify a source file as binary — which `-I` then skipped, so a
|
|
54
|
+
lookup for `remember` returned 32 matches and omitted `remember()`'s own
|
|
55
|
+
definition. The separator is now written as an escape, which is byte-identical
|
|
56
|
+
so no stored id changed. A check now fails if any tracked source file contains
|
|
57
|
+
a NUL, since any such file would be invisible the same way
|
|
58
|
+
- **`--context` counted context lines as matches.** `git grep -z` replaces both
|
|
59
|
+
the match and context separators with the same NUL, so `-B`/`-A` output could
|
|
60
|
+
not be told apart from real hits: `total` was inflated, truncation was wrong,
|
|
61
|
+
and context lines consumed the `limit` budget. Context is now reconstructed
|
|
62
|
+
from disk after the real matches are known
|
|
63
|
+
- **A `path` pointing at a single file threw instead of scoping to it**, though
|
|
64
|
+
the tool documented that it accepted one — `git -C` requires a directory
|
|
65
|
+
- **MongoDB's Atlas vector path scored across embedding models.** Every other
|
|
66
|
+
search path filtered on the embedder that produced a vector; the indexed
|
|
67
|
+
Atlas path did not, so switching models silently ranked incomparable vectors
|
|
68
|
+
|
|
69
|
+
### Changed
|
|
70
|
+
|
|
71
|
+
- Prettier now formats the project, with the config checked in
|
|
72
|
+
- The CLI, the three store adapters and the test scripts are split by
|
|
73
|
+
responsibility; no source file is over 250 lines
|
|
74
|
+
|
|
75
|
+
### Upgrading
|
|
76
|
+
|
|
77
|
+
Nothing changes until you run `claude-db scan`, which builds the graph and adds
|
|
78
|
+
three tables. Postgres gains its tables on first connection after the upgrade.
|
|
79
|
+
|
|
80
|
+
This release adds real dependencies for the first time — the ast-grep parser
|
|
81
|
+
and graphology — so an install is roughly 23 MB larger. They are prebuilt, so
|
|
82
|
+
there is still no compile step.
|
|
83
|
+
|
|
84
|
+
## 0.4.1
|
|
85
|
+
|
|
86
|
+
### Fixed
|
|
87
|
+
|
|
88
|
+
- **`find_usages`'s `path` param only chose which repository to search, and**
|
|
89
|
+
**never actually scoped the search** — described as "directory to search
|
|
90
|
+
from," but no pathspec was ever passed to `git grep`, so a lookup scoped to
|
|
91
|
+
one folder still searched the whole repository. Caught by using the tool: a
|
|
92
|
+
search for `resolveProject` scoped to `src/usages/` (which does not use it)
|
|
93
|
+
still returned 41 matches from across the repo. An explicit `path` now
|
|
94
|
+
narrows the search for real; omitting it still searches the whole
|
|
95
|
+
repository, since a blast-radius check that silently narrowed by default
|
|
96
|
+
could hide a real usage and give false confidence nothing else depends on it
|
|
97
|
+
- The fix itself had the same bug this project keeps tripping on: comparing
|
|
98
|
+
`mkdtempSync`'s temp path against `git rev-parse --show-toplevel`'s result
|
|
99
|
+
failed on macOS, where `/var/folders/...` is a symlink to
|
|
100
|
+
`/private/var/folders/...` — the exact class of mismatch `resolveProject()`
|
|
101
|
+
already guards against with `realpathSync`. Applied the same fix here
|
|
102
|
+
|
|
103
|
+
### Changed
|
|
104
|
+
|
|
105
|
+
- The standing instruction written at install sharpens the `find_usages`
|
|
106
|
+
boundary: it is the default for any symbol/identifier lookup, not only
|
|
107
|
+
before editing a shared name; grep still wins for plain text, log files,
|
|
108
|
+
comments, strings, and scoping with grep flags this tool does not expose
|
|
109
|
+
|
|
110
|
+
## 0.4.0
|
|
111
|
+
|
|
112
|
+
Claude has had no better option than raw Bash `grep` for "what uses X" or "if
|
|
113
|
+
I change this, what breaks" — text matching with no idea whether a hit is the
|
|
114
|
+
definition, a real caller, or an unrelated word.
|
|
115
|
+
|
|
116
|
+
### Added
|
|
117
|
+
|
|
118
|
+
- **`find_usages`**, a sixth MCP tool, plus `claude-db usages <symbol>`. Wraps
|
|
119
|
+
`git grep`, never a persisted index: this project has already shipped three
|
|
120
|
+
silent-staleness bugs, and a symbol index that drifts from an edit is the
|
|
121
|
+
same failure shape in a new place. A live grep re-derives the answer from
|
|
122
|
+
the current source on every call, so there is nothing to invalidate. Scope
|
|
123
|
+
resolution deliberately does not reuse `resolveProject()` — that can point
|
|
124
|
+
at a directory pooling several sibling repos for memory partitioning, which
|
|
125
|
+
`git grep` cannot search — and resolves its own repo root instead. No
|
|
126
|
+
usage-kind classification (import vs call vs type): the `classifyTurn`
|
|
127
|
+
`because` regression is the direct precedent for why that regex heuristic
|
|
128
|
+
goes wrong. The one exception is a best-effort `[definition?]` marker that
|
|
129
|
+
only annotates an already-shown line rather than filtering anything
|
|
130
|
+
|
|
131
|
+
### Fixed
|
|
132
|
+
|
|
133
|
+
- **Untracked and binary files were mishandled in the first pass of the above**
|
|
134
|
+
before it shipped: a brand-new file that hasn't been `git add`ed yet is
|
|
135
|
+
exactly the blast-radius case the tool exists for, and was invisible
|
|
136
|
+
without `--untracked`; a binary file matching the term printed a headerless
|
|
137
|
+
line that corrupted the parser without `-I`. Both caught in review, both
|
|
138
|
+
covered by their own test
|
|
139
|
+
- A search-result snippet that only echoes words already in the title is now
|
|
140
|
+
dropped rather than shown, since it was paying for a line that told the
|
|
141
|
+
reader nothing new
|
|
142
|
+
|
|
143
|
+
## 0.3.0
|
|
144
|
+
|
|
145
|
+
Every defect shipped so far was silent — hooks swallow their errors so a memory
|
|
146
|
+
layer can never break a session, which is the right call and means nothing ever
|
|
147
|
+
reports that capture has stopped. This release is mostly about the tool proving
|
|
148
|
+
it works, plus the first two answers to "it knows nothing yet".
|
|
149
|
+
|
|
150
|
+
### Added
|
|
151
|
+
|
|
152
|
+
- **`status` reports when memory was last written**, and warns when this project
|
|
153
|
+
has been worked in for two days with nothing recorded. Work happening while
|
|
154
|
+
capture doesn't is the signal every failure so far has left, and nothing
|
|
155
|
+
surfaced it
|
|
156
|
+
- **`doctor --deep`** writes an observation, searches for it, expands it and
|
|
157
|
+
deletes it — through the real adapter, embedder and index. Reachability was
|
|
158
|
+
all `doctor` ever proved, and every silent failure had a reachable database
|
|
159
|
+
- **`claude-db seed --from-git`** builds memory from commit history: subject,
|
|
160
|
+
body, changed files, author and date. A fresh install knows nothing for weeks,
|
|
161
|
+
which is the worst moment to ask anyone to trust it. Merges and releases are
|
|
162
|
+
skipped, and ids come from the sha, so re-running adds rather than duplicates
|
|
163
|
+
- **`claude-db sync <url>`** two-way merges with another database. Content-derived
|
|
164
|
+
ids make it nearly free: an id on one side and not the other is memory the
|
|
165
|
+
other has never seen. Session recaps travel with it. Dry run without `--yes`
|
|
166
|
+
- **`/cdb-scan`**, installed alongside the hooks: Claude surveys the codebase
|
|
167
|
+
once into five notes — stack, layout, conventions, workflows, architecture.
|
|
168
|
+
Tagged `inferred`, because everything else in the database is a record of what
|
|
169
|
+
happened and this is a reading of the code
|
|
170
|
+
- **`search --tag <name>`**, and `tag` over MCP. Tags recorded the repository or
|
|
171
|
+
directory an observation touched and only ever nudged ranking, so a workspace
|
|
172
|
+
pooling several repositories could not ask about one of them
|
|
173
|
+
- **`remember --key <name>`**, and `key` over MCP: a stable identity, so a note
|
|
174
|
+
meant to be kept current is replaced rather than duplicated on every run
|
|
175
|
+
|
|
176
|
+
- **A snippet of the matching body in every search result.** The index was
|
|
177
|
+
built on the assumption that a title tells you which row holds the answer,
|
|
178
|
+
and it often does not: fifteen results dated the same day, titled things like
|
|
179
|
+
"Committed as 30daa92", leave nothing to choose on, so you expand two at
|
|
180
|
+
random and pay a full body for each guess. Measured over five real searches,
|
|
181
|
+
snippets add about 19 tokens a row and one avoided expansion saves about
|
|
182
|
+
1000. FTS5 `snippet()` and `ts_headline` centre the fragment on the match;
|
|
183
|
+
MongoDB's `$text` has no equivalent and returns the head of the body. Rows
|
|
184
|
+
found by vector similarity alone carry none — there are no query terms in
|
|
185
|
+
them to centre on — and were 20% of results in that measurement
|
|
186
|
+
- **`get_observations` takes a `chars` limit**, default 2000. The cost argument
|
|
187
|
+
that made the index terse was never applied one layer down, where a single
|
|
188
|
+
call may ask for twenty-five bodies at once. The remainder is counted rather
|
|
189
|
+
than dropped in silence
|
|
190
|
+
|
|
191
|
+
### Fixed
|
|
192
|
+
|
|
193
|
+
- **Titles still fell back to narration.** 0.2.2 skipped sentences that announce
|
|
194
|
+
the work; a sentence that merely says nothing still won, so "Working through
|
|
195
|
+
the improvements now." was a stored title. Titles now take the first sentence
|
|
196
|
+
carrying evidence — a filename, a number, a past-tense verb — and fall back
|
|
197
|
+
only when none does
|
|
198
|
+
- **`use` stranded your memory in silence.** Switching backends left everything
|
|
199
|
+
already recorded behind and started the new one empty. It now says so, and
|
|
200
|
+
says how to bring it across
|
|
201
|
+
- **`use` wrote into whatever it was pointed at.** One in anger resolved to a
|
|
202
|
+
live application database; two tables were created inside it without a word.
|
|
203
|
+
It now reports what else is in there, before adding anything
|
|
204
|
+
- **`kind` barely filtered.** `decision` matched on the bare word *because*,
|
|
205
|
+
which explains as readily as it decides — 98 of 471 stored decisions matched
|
|
206
|
+
on nothing else, and half the database was one kind. It now needs a weighed
|
|
207
|
+
alternative
|
|
208
|
+
- A certificate error from a managed Postgres now names the fix, not just the
|
|
209
|
+
problem
|
|
210
|
+
- Cursors for transcripts that no longer exist are swept during `flush`.
|
|
211
|
+
`clearCursor` landed in 0.2.0 and never covered anything written before it
|
|
212
|
+
|
|
213
|
+
### Changed
|
|
214
|
+
|
|
215
|
+
- **Postgres `init()` costs one round trip instead of four.** Every hook is its
|
|
216
|
+
own process, so nothing is pooled and the whole setup ran again on every
|
|
217
|
+
prompt. Against a managed instance — 49ms at best, 1045ms at the median for a
|
|
218
|
+
single round trip — that was most of why a remote backend felt broken. A
|
|
219
|
+
version row now short-circuits it, and anything unexpected falls through to
|
|
220
|
+
the full setup
|
|
221
|
+
|
|
222
|
+
### Upgrading
|
|
223
|
+
|
|
224
|
+
Postgres gains a `claude_db_meta` table on first connection, which is why this
|
|
225
|
+
is a minor release rather than a patch: `updates: auto` will report it and leave
|
|
226
|
+
it to you.
|
|
227
|
+
|
|
228
|
+
Titles and kinds are rewritten by re-ingesting, per project:
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
cd <project> && claude-db flush
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
## 0.2.3
|
|
235
|
+
|
|
236
|
+
### Added
|
|
237
|
+
|
|
238
|
+
- **Update notifications.** A newer release is reported once a day at session
|
|
239
|
+
start. The check runs detached at session end and writes a local file the next
|
|
240
|
+
session reads, so neither the network nor npm is ever on the prompt path
|
|
241
|
+
- `updates: notify | auto | off`. Notify is the default — installing on
|
|
242
|
+
someone's behalf means executing code they did not choose, in a process
|
|
243
|
+
holding their whole memory database. `auto` is available for anyone who wants
|
|
244
|
+
it, and stops at the caret boundary: 0.2.x takes 0.2.z but not 0.3.0, since a
|
|
245
|
+
release outside that range may migrate the database on first connection
|
|
246
|
+
- `claude-db update` to check and install on demand
|
|
247
|
+
- `doctor` reports the running version, which nothing did before
|
|
248
|
+
|
|
249
|
+
## 0.2.2
|
|
250
|
+
|
|
251
|
+
### Fixed
|
|
252
|
+
|
|
253
|
+
- **Titles announced the work instead of reporting it.** `buildTitle` took the
|
|
254
|
+
reply's opening sentence, which mid-task is a transition rather than an
|
|
255
|
+
outcome — "Now the use command and the top-level handler:", "Right — let me
|
|
256
|
+
do that properly". Measured on a real database, half of all titles read like
|
|
257
|
+
that. Since the title is the whole payload of a search result and of the
|
|
258
|
+
block injected above each prompt, a turn whose body held the answer was
|
|
259
|
+
unreachable. Titles now skip announcing sentences and take the first that
|
|
260
|
+
carries a claim
|
|
261
|
+
|
|
262
|
+
### Changed
|
|
263
|
+
|
|
264
|
+
- The memory instructions written at install now ask the agent to search
|
|
265
|
+
**before re-deriving** something the project already knows — grepping or
|
|
266
|
+
reading git history to reconstruct a past decision — not only before saying
|
|
267
|
+
it lacks context, which never fires when it silently reconstructs instead
|
|
268
|
+
|
|
269
|
+
### Upgrading
|
|
270
|
+
|
|
271
|
+
Existing titles are rewritten by re-ingesting, per project:
|
|
272
|
+
|
|
273
|
+
```bash
|
|
274
|
+
cd <project> && claude-db flush
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
Embeddings are recomputed as part of that; no separate `reembed` is needed.
|
|
278
|
+
|
|
279
|
+
## 0.2.1
|
|
280
|
+
|
|
281
|
+
### Fixed
|
|
282
|
+
|
|
283
|
+
- **`use` saved the connection string before testing it**, so a typo or a
|
|
284
|
+
retired host was written to the config permanently. Every hook then pointed
|
|
285
|
+
at a database that was not there, and because hooks swallow their errors,
|
|
286
|
+
memory silently stopped recording. It now connects and pings first, keeping
|
|
287
|
+
the previous database otherwise; `--force` saves unverified
|
|
288
|
+
- Errors from a database driver printed a raw stack trace instead of a message
|
|
289
|
+
- Credentials in a connection string (`user:password@host`) were not redacted,
|
|
290
|
+
and were stored verbatim in memory
|
|
291
|
+
- `remember` applied no redaction at all — dictated memory was stored raw
|
|
292
|
+
|
|
293
|
+
## 0.2.0
|
|
294
|
+
|
|
295
|
+
Memory becomes writable, is keyed on the repository rather than the directory
|
|
296
|
+
you happened to launch from, and behaves the same on all three backends.
|
|
297
|
+
|
|
298
|
+
### Fixed
|
|
299
|
+
|
|
300
|
+
- **SQLite orphaned an FTS row on every re-ingest.** `INSERT OR REPLACE` skips
|
|
301
|
+
the delete triggers that maintain the mirror unless `recursive_triggers` is
|
|
302
|
+
on. Existing databases repair themselves once, guarded by `user_version`
|
|
303
|
+
- **Postgres stored nothing on a default install.** The embedding column was
|
|
304
|
+
hardcoded to 384 dimensions while the built-in embedder produces 256, so
|
|
305
|
+
every insert failed and rolled the batch back. The column is now sized to the
|
|
306
|
+
vectors actually written
|
|
307
|
+
- **Postgres discarded corrections**, using `ON CONFLICT DO NOTHING` where the
|
|
308
|
+
other adapters overwrite, pinning every observation to its first, partial
|
|
309
|
+
capture
|
|
310
|
+
- **Postgres keyword search was narrower than the rest.** `plainto_tsquery`
|
|
311
|
+
ANDs every term, so a natural-language prompt matched nothing and per-prompt
|
|
312
|
+
injection never fired. Tags were not indexed there at all
|
|
313
|
+
- Vectors of different widths were compared and scored a meaningless number;
|
|
314
|
+
they now score zero and fall below the relevance floor
|
|
315
|
+
- Observation titles were never redacted, though they are injected above every
|
|
316
|
+
prompt
|
|
317
|
+
- Non-Latin prompts recalled nothing: three ASCII-only tokenisers, one of which
|
|
318
|
+
gave CJK text a zero vector
|
|
319
|
+
- `uninstall` left the MCP server registered when it was the only one
|
|
320
|
+
- `upsertSession` never updated `project` on SQLite or Postgres
|
|
321
|
+
|
|
322
|
+
### Added
|
|
323
|
+
|
|
324
|
+
- `remember` and `forget`, as MCP tools and CLI verbs. Capture is inferred from
|
|
325
|
+
events, and a rule is not an event, so a standing preference was the one
|
|
326
|
+
thing that could never be recorded
|
|
327
|
+
- `export`, `import`, `prune`, `reembed`, `stats` and `merge`
|
|
328
|
+
- `search --all`, and `project: "*"` over MCP, for cross-project recall
|
|
329
|
+
- `author` and `embedder` recorded per observation
|
|
330
|
+
- Install writes standing memory instructions to `CLAUDE.local.md`, so recall
|
|
331
|
+
is a default rather than something to ask for each session
|
|
332
|
+
|
|
333
|
+
### Changed
|
|
334
|
+
|
|
335
|
+
- Memory is keyed on the repository root, so working from a subdirectory no
|
|
336
|
+
longer starts a second, invisible memory. `$HOME` is refused, so a dotfiles
|
|
337
|
+
repo cannot collapse every project into one
|
|
338
|
+
- Session summaries carry across flushes and rank by kind
|
|
339
|
+
- Observations are tagged with the repository or top-level directory they
|
|
340
|
+
touched
|
|
341
|
+
- The embedder is bounded by `embeddings.timeoutMs`, so a first model download
|
|
342
|
+
cannot hang a prompt
|
|
343
|
+
- Redaction covers private keys, AWS keys, Slack tokens and JWTs
|
|
344
|
+
- A global install registers through `claude mcp add -s user` instead of
|
|
345
|
+
rewriting `~/.claude.json`, and every settings write is atomic
|
|
346
|
+
- `MemoryStore.clear()` is replaced by `remove(filter)`, alongside a new paged
|
|
347
|
+
`list(filter)`
|
|
348
|
+
|
|
349
|
+
### Notes
|
|
350
|
+
|
|
351
|
+
Postgres and MongoDB are now covered by CI rather than by argument. The suite
|
|
352
|
+
is 138 checks.
|
|
353
|
+
|
|
354
|
+
## 0.1.0
|
|
355
|
+
|
|
356
|
+
First release.
|
|
357
|
+
|
|
358
|
+
### Capture
|
|
359
|
+
|
|
360
|
+
- Reads Claude Code session transcripts rather than watching tool calls, so
|
|
361
|
+
observations carry the prompt (intent) and the agent's reasoning, not just
|
|
362
|
+
file paths
|
|
363
|
+
- Groups a transcript into turns: a prompt plus everything until the next one
|
|
364
|
+
- Content-derived observation ids, so reprocessing rewrites rather than
|
|
365
|
+
duplicating
|
|
366
|
+
- Flushes on every prompt, so sessions that crash or never close are still
|
|
367
|
+
recorded
|
|
368
|
+
- Byte-offset cursor per session, so each flush parses only the new tail
|
|
369
|
+
- Shell commands filtered by an allowlist of consequential operations
|
|
370
|
+
(dependency changes, tests, builds, history-changing git, migrations,
|
|
371
|
+
infra). Exploration is dropped
|
|
372
|
+
- Secrets redacted and excluded paths dropped before anything is written
|
|
373
|
+
|
|
374
|
+
### Storage
|
|
375
|
+
|
|
376
|
+
- One `MemoryStore` interface, three adapters: SQLite, MongoDB, Postgres
|
|
377
|
+
- Connection-string scheme selects the backend; drivers load lazily
|
|
378
|
+
- SQLite via Node's builtin `node:sqlite`: no native build step
|
|
379
|
+
- Project scoping indexed inside FTS rather than applied as a post-filter
|
|
380
|
+
- Brute-force vector scans bounded by `embeddings.maxScanCandidates`
|
|
381
|
+
|
|
382
|
+
### Recall
|
|
383
|
+
|
|
384
|
+
- Three-layer progressive disclosure: `search`, `timeline`,
|
|
385
|
+
`get_observations`, exposed as MCP tools
|
|
386
|
+
- Hybrid retrieval fused by Reciprocal Rank Fusion, with a recency boost
|
|
387
|
+
- Automatic injection at session start and on every prompt, with the best
|
|
388
|
+
match expanded in full
|
|
389
|
+
- Relevance floor per embedder, so an unrelated prompt injects nothing
|
|
390
|
+
- Zero-dependency builtin embedder; optional upgrade to all-MiniLM-L6-v2
|
|
391
|
+
|
|
392
|
+
### CLI
|
|
393
|
+
|
|
394
|
+
`install`, `uninstall`, `status`, `doctor`, `use`, `search`, `projects`,
|
|
395
|
+
`flush`, `reset`. Aliased as `cdb`.
|
|
396
|
+
|
|
397
|
+
- `--project` scopes to one repo instead of the whole machine
|
|
398
|
+
- `install` refuses to run from an npx cache, since hooks store absolute paths
|
|
399
|
+
- `reset` is a dry run unless given `--yes`
|
package/README.md
CHANGED
|
@@ -16,6 +16,11 @@ re-explain the architecture, why you chose X over Y, and what already failed.
|
|
|
16
16
|
claude-db records those decisions as you work and gives them back
|
|
17
17
|
automatically. Local by default, no account, no subscription.
|
|
18
18
|
|
|
19
|
+
It also maps your code: `claude-db scan` builds a graph of every symbol and how
|
|
20
|
+
they connect, so "what breaks if I change this" is a query instead of a grep.
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
19
24
|
```bash
|
|
20
25
|
npm install -g claude-db
|
|
21
26
|
|
|
@@ -23,117 +28,73 @@ cd your-project
|
|
|
23
28
|
claude-db install --project
|
|
24
29
|
```
|
|
25
30
|
|
|
26
|
-
Restart Claude Code. That's it
|
|
31
|
+
Restart Claude Code. That's it — capture and recall are hooks, so they run
|
|
32
|
+
without being asked.
|
|
27
33
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
replies, every tool call. claude-db reads that file, so it captures **why** you
|
|
32
|
-
did something, not just which files changed.
|
|
34
|
+
`--project` scopes to one repo instead of every project on the machine. It
|
|
35
|
+
writes `.claude/settings.local.json` and `.mcp.json` — add `.mcp.json` to your
|
|
36
|
+
`.gitignore`, since it holds a machine-specific path.
|
|
33
37
|
|
|
34
|
-
|
|
35
|
-
you send a prompt
|
|
36
|
-
│
|
|
37
|
-
├─ 1. save the previous turn
|
|
38
|
-
│ read new lines from the session transcript
|
|
39
|
-
│ keep turns that changed something
|
|
40
|
-
│ store title + reasoning + files, with an embedding
|
|
41
|
-
│
|
|
42
|
-
└─ 2. search memory using your prompt
|
|
43
|
-
inject the best match above your message
|
|
44
|
-
```
|
|
38
|
+
## Map your code
|
|
45
39
|
|
|
46
|
-
|
|
47
|
-
|
|
40
|
+
```bash
|
|
41
|
+
claude-db scan
|
|
48
42
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
agent may or may not act on; a memory file is a rule for the whole session,
|
|
53
|
-
which is what makes recall the default rather than something you have to ask
|
|
54
|
-
for. `claude-db uninstall` takes the block back out.
|
|
43
|
+
claude-db usages --mode explain resolveProject
|
|
44
|
+
claude-db usages --mode path cmdScan observationId
|
|
45
|
+
```
|
|
55
46
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
47
|
+
Claude gets the same four modes through MCP: `text` (a live grep, no scan
|
|
48
|
+
needed), `usages`, `explain` and `path`. Answers re-check the working tree
|
|
49
|
+
before replying, so they never report a line the source has moved past.
|
|
59
50
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
exists, zero when it doesn't.
|
|
51
|
+
Works out of the box on TypeScript, TSX, JavaScript, Python, Go and Rust — the
|
|
52
|
+
parser ships with the package, so there is nothing else to install.
|
|
63
53
|
|
|
64
|
-
|
|
65
|
-
body — enough to tell two similarly-titled rows apart without expanding either.
|
|
66
|
-
Full bodies come only from `get_observations`, for ids you picked.
|
|
54
|
+
## Use another database
|
|
67
55
|
|
|
68
|
-
|
|
56
|
+
SQLite by default, at `~/.claude-memory/memory.db`. No setup, no network. Point
|
|
57
|
+
it elsewhere to share memory across machines:
|
|
69
58
|
|
|
59
|
+
```bash
|
|
60
|
+
claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
|
|
61
|
+
claude-db use "postgres://user:pass@host:5432/memory"
|
|
70
62
|
```
|
|
71
|
-
[decision] Chose WebSocket over polling for live order updates
|
|
72
|
-
|
|
73
|
-
Asked: the order feed keeps dropping
|
|
74
63
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
order is missed during a drop.
|
|
78
|
-
|
|
79
|
-
Files: src/ws/client.ts, src/ws/reconnect.ts
|
|
80
|
-
Ran: Test run: pnpm test
|
|
81
|
-
```
|
|
64
|
+
Install the driver you need (`npm install mongodb` or `pg`); neither ships by
|
|
65
|
+
default.
|
|
82
66
|
|
|
83
67
|
## Commands
|
|
84
68
|
|
|
85
69
|
`cdb` is a shorter alias for all of them.
|
|
86
70
|
|
|
87
|
-
| Command
|
|
88
|
-
|
|
|
89
|
-
| `claude-db install [--project]`
|
|
90
|
-
| `claude-db uninstall [--project]`
|
|
91
|
-
| `claude-db status`
|
|
92
|
-
| `claude-db doctor [--deep]`
|
|
93
|
-
| `claude-db search [--all] [--tag <name>] <query>` | Search this project's memory, or every project
|
|
94
|
-
| `claude-db remember [--key <name>] <text>`
|
|
95
|
-
| `claude-db forget <id>`
|
|
96
|
-
| `claude-db seed --from-git`
|
|
97
|
-
| `claude-db
|
|
98
|
-
| `claude-db
|
|
99
|
-
| `claude-db
|
|
100
|
-
| `claude-db
|
|
101
|
-
| `claude-db
|
|
102
|
-
| `claude-db
|
|
103
|
-
| `claude-db
|
|
104
|
-
| `claude-db
|
|
105
|
-
| `claude-db
|
|
106
|
-
| `claude-db
|
|
107
|
-
| `claude-db
|
|
108
|
-
| `claude-db
|
|
71
|
+
| Command | What it does |
|
|
72
|
+
| ------------------------------------------------- | ------------------------------------------------------ |
|
|
73
|
+
| `claude-db install [--project]` | Register hooks and the MCP server |
|
|
74
|
+
| `claude-db uninstall [--project]` | Remove them, keeping your memory |
|
|
75
|
+
| `claude-db status` | Is it wired up, and when did it last record anything |
|
|
76
|
+
| `claude-db doctor [--deep]` | Resolved config; `--deep` proves a full round trip |
|
|
77
|
+
| `claude-db search [--all] [--tag <name>] <query>` | Search this project's memory, or every project |
|
|
78
|
+
| `claude-db remember [--key <name>] <text>` | Record a rule outright, e.g. "always use pnpm here" |
|
|
79
|
+
| `claude-db forget <id>` | Delete specific observations by id |
|
|
80
|
+
| `claude-db seed --from-git` | Fill a cold memory from this repo's history |
|
|
81
|
+
| `claude-db scan [--force]` | Build the code graph for this repo |
|
|
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`) |
|
|
109
94
|
|
|
110
95
|
Install also adds a `/cdb-scan` skill: run it once on an existing project and
|
|
111
|
-
Claude
|
|
112
|
-
|
|
113
|
-
notes are tagged `inferred`, because they are a reading of the code rather than
|
|
114
|
-
a record of what happened.
|
|
115
|
-
|
|
116
|
-
`--project` scopes to one repo instead of every project on the machine. It
|
|
117
|
-
writes `.claude/settings.local.json` and `.mcp.json` — add `.mcp.json` to your
|
|
118
|
-
`.gitignore`, since it holds a machine-specific path.
|
|
119
|
-
|
|
120
|
-
## Bring your own database
|
|
121
|
-
|
|
122
|
-
SQLite by default, at `~/.claude-memory/memory.db`. No setup, no network.
|
|
123
|
-
|
|
124
|
-
Only needed if you want memory shared across machines:
|
|
125
|
-
|
|
126
|
-
```bash
|
|
127
|
-
claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
|
|
128
|
-
claude-db use "postgres://user:pass@host:5432/memory"
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
The connection string picks the backend. Install the driver you need
|
|
132
|
-
(`npm install mongodb` or `pg`); neither ships by default. `CLAUDE_DB_URL`
|
|
133
|
-
overrides the config file if you prefer an env var.
|
|
134
|
-
|
|
135
|
-
Search is hybrid — keyword plus vector — on all three. Memory is partitioned by
|
|
136
|
-
project path, so one database serves every repo you work in.
|
|
96
|
+
Claude maps the codebase into memory, so search has something to find before
|
|
97
|
+
you have any history.
|
|
137
98
|
|
|
138
99
|
## Requirements
|
|
139
100
|
|
|
@@ -150,13 +111,20 @@ Nothing leaves your machine unless you point it at a remote database.
|
|
|
150
111
|
in `<private>...</private>` is stripped, and API keys and tokens are redacted
|
|
151
112
|
before anything is written.
|
|
152
113
|
|
|
114
|
+
## Documentation
|
|
115
|
+
|
|
116
|
+
- [How it works](./docs/how-it-works.md) — what gets captured and injected, how
|
|
117
|
+
the code graph is built and kept current, and how the database backends differ
|
|
118
|
+
- [Changelog](./CHANGELOG.md)
|
|
119
|
+
|
|
153
120
|
## Development
|
|
154
121
|
|
|
155
122
|
```bash
|
|
156
123
|
npm install
|
|
157
124
|
npm run build
|
|
158
|
-
npm test #
|
|
125
|
+
npm test # 263 checks
|
|
159
126
|
npm run try # simulate a session, touches nothing
|
|
127
|
+
npm run format
|
|
160
128
|
```
|
|
161
129
|
|
|
162
130
|
Releases publish from CI on a version tag:
|
|
@@ -1,20 +1,6 @@
|
|
|
1
1
|
import type { ObservationKind } from '../types.js';
|
|
2
2
|
export interface CommandClassification {
|
|
3
3
|
kind: ObservationKind;
|
|
4
|
-
/** Short human label used as the observation title. */
|
|
5
4
|
label: string;
|
|
6
5
|
}
|
|
7
|
-
/**
|
|
8
|
-
* Decides whether a shell command is worth remembering.
|
|
9
|
-
*
|
|
10
|
-
* Agents run far more commands to *look* than to *change*, and the looking is
|
|
11
|
-
* worthless later: nobody needs to recall that you grepped for easing curves
|
|
12
|
-
* three weeks ago. Capturing it crowds out the handful that genuinely mattered.
|
|
13
|
-
*
|
|
14
|
-
* So this is an allowlist of consequential operations rather than a blocklist
|
|
15
|
-
* of exploration. Exploration is unbounded in variety and impossible to
|
|
16
|
-
* enumerate; the operations that change project state are a short, stable list.
|
|
17
|
-
*
|
|
18
|
-
* Returns null for anything unrecognised, which means "do not store".
|
|
19
|
-
*/
|
|
20
6
|
export declare function classifyCommand(command: string): CommandClassification | null;
|
package/dist/capture/command.js
CHANGED
|
@@ -1,20 +1,4 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Decides whether a shell command is worth remembering.
|
|
3
|
-
*
|
|
4
|
-
* Agents run far more commands to *look* than to *change*, and the looking is
|
|
5
|
-
* worthless later: nobody needs to recall that you grepped for easing curves
|
|
6
|
-
* three weeks ago. Capturing it crowds out the handful that genuinely mattered.
|
|
7
|
-
*
|
|
8
|
-
* So this is an allowlist of consequential operations rather than a blocklist
|
|
9
|
-
* of exploration. Exploration is unbounded in variety and impossible to
|
|
10
|
-
* enumerate; the operations that change project state are a short, stable list.
|
|
11
|
-
*
|
|
12
|
-
* Returns null for anything unrecognised, which means "do not store".
|
|
13
|
-
*/
|
|
14
1
|
export function classifyCommand(command) {
|
|
15
|
-
// Agents chain aggressively: `pnpm lint; echo "==="; git status`. Classifying
|
|
16
|
-
// the raw string stores the whole chain as one title, most of which is
|
|
17
|
-
// exploration. Split first, then label only the segment that qualified.
|
|
18
2
|
for (const segment of splitSegments(command)) {
|
|
19
3
|
for (const rule of RULES) {
|
|
20
4
|
if (rule.pattern.test(segment)) {
|
|
@@ -24,20 +8,13 @@ export function classifyCommand(command) {
|
|
|
24
8
|
}
|
|
25
9
|
return null;
|
|
26
10
|
}
|
|
27
|
-
/** Splits on shell separators, keeping each simple command intact. */
|
|
28
11
|
function splitSegments(command) {
|
|
29
12
|
return command
|
|
30
13
|
.split(/(?:\|\||&&|[;\n|])/)
|
|
31
14
|
.map((segment) => segment.trim().replace(/\s+/g, ' '))
|
|
32
15
|
.filter((segment) => segment.length > 0);
|
|
33
16
|
}
|
|
34
|
-
/** Optional leading `cd foo &&`-style noise is already stripped by splitting. */
|
|
35
17
|
const PM = '(?:npm|pnpm|yarn|bun|npx)';
|
|
36
|
-
/**
|
|
37
|
-
* Every pattern is anchored to the start of a segment so a bare word inside a
|
|
38
|
-
* filename cannot match. `sed -n '1,50p' test.ts` is exploration; `pnpm test`
|
|
39
|
-
* is not, and only anchoring tells them apart.
|
|
40
|
-
*/
|
|
41
18
|
const RULES = [
|
|
42
19
|
{
|
|
43
20
|
pattern: new RegExp(`^${PM} (?:install|add|remove|uninstall|ci)\\b`, 'i'),
|