autoctxd 0.4.1 → 0.4.2
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 +77 -62
- package/README.md +309 -301
- package/bin/autoctxd.cjs +42 -0
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,62 +1,77 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
All notable changes to this project will be documented in this file.
|
|
4
|
-
|
|
5
|
-
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
-
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
-
|
|
8
|
-
## [0.4.
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
|
|
19
|
-
###
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
-
|
|
48
|
-
-
|
|
49
|
-
-
|
|
50
|
-
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
-
|
|
59
|
-
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [0.4.2] - 2026-05-16
|
|
9
|
+
|
|
10
|
+
### Fixed
|
|
11
|
+
- `npm install -g autoctxd` now shows a helpful message when Bun is missing from PATH, instead of crashing with a cryptic error. The new Node.js wrapper in `bin/autoctxd.cjs` detects Bun availability and provides clear, platform-specific installation instructions for the user.
|
|
12
|
+
|
|
13
|
+
## [0.4.1] - 2026-05-16
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
- `.npmignore` so the npm tarball ships only the runtime files (excludes `tests/`, dev scripts, models, docs assets, internal notes, build artifacts).
|
|
17
|
+
- `repository`, `homepage`, `bugs`, and `preferGlobal` fields in `package.json` for npm discoverability.
|
|
18
|
+
|
|
19
|
+
### Fixed
|
|
20
|
+
- Typecheck cleanup in `src/db/vector/search.ts` (consistent `_distance` access via `as any`).
|
|
21
|
+
- `tsconfig.json` types switched from the unmaintained `bun-types` package to the official `bun` types.
|
|
22
|
+
|
|
23
|
+
## [0.4.0] - 2026-05-15
|
|
24
|
+
|
|
25
|
+
Quality pass before the first public release. Same surface area, three pre-existing bugs in the classifier and decision extractor fixed.
|
|
26
|
+
|
|
27
|
+
### Fixed
|
|
28
|
+
- Decision extractor no longer captures `npm install` / `bun add` / `pip install` mentions in Monitor commands, task descriptions, and log streams as architectural decisions. The dependency detector now validates the captured token against a reject list (`output`, `progress`, `tsx`, `tests`, `dev`, `prod`, …) and rejects numeric-only tokens, very short bare words, and anything without alphabetic characters.
|
|
29
|
+
- Classifier filters internal harness tools (`Monitor`, `ToolSearch`, `TaskStop`, `TaskOutput`, `TodoWrite`) and Bash/PowerShell summaries that carry their payloads. These are still persisted but at importance 1, so they fall out of "top observations" and never get injected as recovered context.
|
|
30
|
+
- Bash/PowerShell exploration commands (`List …`, `Check …`, `Find …`, `git status`, `git log`, `git diff`, `git blame`, …) are now classified as `research` with low importance instead of dropping to `other`. PowerShell gets the same Bash heuristics it lacked before.
|
|
31
|
+
- Decisions no longer duplicate across sessions. A unique index on `(project_path, title)` plus `INSERT OR IGNORE` makes re-extraction idempotent.
|
|
32
|
+
- The decision extractor's "tool-prefixed noise" guard was extended to catch `Bash:` / `PowerShell:` / `Edit:` / `Edited ` / `Monitor:` / `ToolSearch:` / `TodoWrite` / `TaskStop:` / `TaskOutput:` summaries that previously slipped through when the classifier promoted them to type=decision via a stray keyword.
|
|
33
|
+
|
|
34
|
+
### Added
|
|
35
|
+
- `autoctxd cleanup-decisions [--dry-run]` — deletes generic-word noise (`Added npm dep: output`, …) and tool-prefixed leftovers from the pre-0.4 extractor, and collapses any cross-session duplicates that predate the unique index. Idempotent; safe to re-run.
|
|
36
|
+
- Schema migration: cross-session duplicate decisions in legacy DBs are collapsed to the earliest row on open, then the unique index is enforced going forward.
|
|
37
|
+
|
|
38
|
+
### Improved
|
|
39
|
+
- On the author's real DB, this collapsed the architectural-decisions feed from 142 noisy rows to 4 actual decisions.
|
|
40
|
+
|
|
41
|
+
## [0.3.0] - 2026-05-15
|
|
42
|
+
|
|
43
|
+
First public release.
|
|
44
|
+
|
|
45
|
+
### Added
|
|
46
|
+
- **MCP server** with 7 tools (`recall_decisions`, `recall_unfinished`, `search_memory`, `get_project_history`, `check_intent`, `record_feedback`, `record_decision`) for active memory recall in Claude Code, Cursor, Windsurf, Cline, and Claude Desktop.
|
|
47
|
+
- **Active Guard** — `check_intent` flags actions that contradict past decisions before they happen.
|
|
48
|
+
- **Feedback loop** — `record_feedback` lets the system learn which memories are useful, irrelevant, or wrong per user.
|
|
49
|
+
- **Pluggable embeddings** — TF-IDF (default, zero-install), MiniLM-L6-v2 via `@xenova/transformers` (opt-in), and Ollama for any local embedding model. Switch with `autoctxd embeddings switch`; cache is partitioned per provider.
|
|
50
|
+
- **Local web dashboard** at `http://localhost:4589` — metric cards, activity timeline, decision feed, decision chains, pattern panel, hybrid search.
|
|
51
|
+
- **Decision chains** — automatically detects sequences like `mysql → postgres → sqlite` across sessions.
|
|
52
|
+
- **Token-savings metrics** — accumulated estimate of tokens injected vs. tokens that would otherwise be re-explained.
|
|
53
|
+
- **One-command installer** for macOS, Linux (`install.sh`) and Windows (`install.ps1`) — bootstraps Bun if missing, clones the repo, installs deps, initializes the DB, registers the hooks in `settings.json` (non-destructive merge).
|
|
54
|
+
- **Health-check doctor** (`autoctxd doctor`) — validates runtime, deps, DB schema, LanceDB, hook registration, data directory, and accumulated metrics.
|
|
55
|
+
- **`.autoctxd-ignore`** — gitignore-style opt-out for sensitive projects (single `*` opts the whole project out).
|
|
56
|
+
- **Cross-session pattern detection** — tool preferences, work-type focus, file hotspots, TDD vs. fix-first, peak coding hours (after 3+ sessions per project).
|
|
57
|
+
- **Hybrid search** — semantic (vector) + full-text (FTS5) with project filter.
|
|
58
|
+
- **Re-classification** — `autoctxd reclassify` re-runs the classifier on old observations after improvements.
|
|
59
|
+
- **Export** — `autoctxd export ./my-app > context.md` for project memory as markdown.
|
|
60
|
+
|
|
61
|
+
### Stack
|
|
62
|
+
- Bun runtime
|
|
63
|
+
- SQLite + FTS5 for structured storage and full-text search
|
|
64
|
+
- LanceDB for vector storage (dim adapts to active provider)
|
|
65
|
+
- Keyword + tool/file heuristics for classification (no LLM calls)
|
|
66
|
+
|
|
67
|
+
### Privacy
|
|
68
|
+
- No telemetry. No cloud. No network calls during operation.
|
|
69
|
+
- Everything in `~/.claude/autoctxd/data/` — delete to wipe.
|
|
70
|
+
- See [SECURITY.md](SECURITY.md) for the full threat model.
|
|
71
|
+
|
|
72
|
+
### Testing
|
|
73
|
+
- 75 tests, isolated temp DB (never touches real memory).
|
|
74
|
+
- Cross-provider embeddings benchmark (`bun run benchmark:embeddings`).
|
|
75
|
+
- Tests cover classifier, compressor, decision extractor, decision chains, ignore matcher, embedding providers, and end-to-end integration.
|
|
76
|
+
|
|
77
|
+
[0.3.0]: https://github.com/autoctxd/autoctxd/releases/tag/v0.3.0
|
package/README.md
CHANGED
|
@@ -1,301 +1,309 @@
|
|
|
1
|
-
# autoctxd
|
|
2
|
-
|
|
3
|
-
**Persistent, local memory for Claude Code.**
|
|
4
|
-
|
|
5
|
-
[](LICENSE)
|
|
6
|
-
[](https://bun.sh)
|
|
7
|
-
[](https://github.com/autoctxd/autoctxd/actions/workflows/ci.yml)
|
|
8
|
-
[](#privacy)
|
|
9
|
-
[](#how-it-works)
|
|
10
|
-
[](CONTRIBUTING.md)
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
Every Claude Code session starts from scratch. You re-explain your project, re-state decisions you already made, re-describe what you were in the middle of. `autoctxd` fixes that — silently, locally, with zero API cost.
|
|
15
|
-
|
|
16
|
-
- **100% local, zero API cost** — pure heuristics, no LLM calls, nothing leaves your machine
|
|
17
|
-
- Captures every tool use automatically through Claude Code hooks
|
|
18
|
-
- Injects the right ~600 tokens of context into each new session
|
|
19
|
-
- Tracks architectural decisions separately — they never get forgotten
|
|
20
|
-
- Detects work patterns across sessions
|
|
21
|
-
- **Active Guard** — flags actions that contradict past decisions, before you make them
|
|
22
|
-
|
|
23
|
-
## Why autoctxd?
|
|
24
|
-
|
|
25
|
-
| | autoctxd | Mem0 / memori (cloud) | Plain CLAUDE.md |
|
|
26
|
-
|---|---|---|---|
|
|
27
|
-
| Where your code context lives | **Your disk** | Their servers | A static file you maintain |
|
|
28
|
-
| Cost per session | **$0** | API calls billed | $0 |
|
|
29
|
-
| Captures automatically | **Yes** (hooks) | Via SDK calls | No — you write it |
|
|
30
|
-
| Active recall during reasoning | **Yes** (7 MCP tools) | Yes | No |
|
|
31
|
-
| Flags decision contradictions | **Yes** (Active Guard) | No | No |
|
|
32
|
-
| Works offline | **Yes** | No | Yes |
|
|
33
|
-
| Cross-session patterns / hotspots | **Yes** | Limited | No |
|
|
34
|
-
| Setup | **One command** | Account + API key | Edit a file |
|
|
35
|
-
|
|
36
|
-
Built specifically for the **Claude Code workflow** — hooks, MCP, and a local dashboard, not a generic SDK you bolt onto something.
|
|
37
|
-
|
|
38
|
-
## How it works
|
|
39
|
-
|
|
40
|
-
```
|
|
41
|
-
Session 1 Session 2 (days later)
|
|
42
|
-
───────── ─────────────────────
|
|
43
|
-
You work on auth refactor ───┐ ┌──► Claude already knows:
|
|
44
|
-
Claude uses Edit/Write/Bash │ │ • "Migrated from jwt to iron-session"
|
|
45
|
-
▼ │ • Hot files: auth/session.ts
|
|
46
|
-
┌──────────┐ │ • Last session left the login route
|
|
47
|
-
│ SQLite │ │ half-wired (blocked)
|
|
48
|
-
│ LanceDB │─────┘
|
|
49
|
-
└──────────┘ no re-explaining needed
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
Two integration modes, use either or both:
|
|
53
|
-
|
|
54
|
-
**1. Passive (hooks, Claude Code only)** — injects context at session start.
|
|
55
|
-
|
|
56
|
-
| Hook | What it does |
|
|
57
|
-
|---|---|
|
|
58
|
-
| `PreToolUse` | Builds context block from past sessions and injects it |
|
|
59
|
-
| `PostToolUse` | Classifies and stores each tool use as an observation |
|
|
60
|
-
| `Stop` | Compresses the session, extracts decisions, detects patterns, generates embeddings |
|
|
61
|
-
|
|
62
|
-
**2. Active (MCP server, works everywhere)** — Claude/Cursor/Windsurf/Cline query memory **during** reasoning via 7 tools:
|
|
63
|
-
|
|
64
|
-
| Tool | What it enables |
|
|
65
|
-
|---|---|
|
|
66
|
-
| `recall_decisions` | Look up past architectural decisions for a project |
|
|
67
|
-
| `recall_unfinished` | Surface blockers from past sessions |
|
|
68
|
-
| `search_memory` | Semantic + FTS search across all your coding memory |
|
|
69
|
-
| `get_project_history` | Recent session summaries |
|
|
70
|
-
| **`check_intent`** | **Active Guard** — flags actions that contradict past decisions |
|
|
71
|
-
| `record_feedback` | Learns from "useful/irrelevant/wrong" signals |
|
|
72
|
-
| `record_decision` | Persists decisions made in-conversation (never forgotten) |
|
|
73
|
-
|
|
74
|
-
See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) for setup in each editor.
|
|
75
|
-
|
|
76
|
-
Nothing leaves your machine.
|
|
77
|
-
|
|
78
|
-
## Install
|
|
79
|
-
|
|
80
|
-
### One-command install
|
|
81
|
-
|
|
82
|
-
**macOS / Linux**
|
|
83
|
-
```bash
|
|
84
|
-
curl -fsSL https://raw.githubusercontent.com/autoctxd/autoctxd/main/scripts/install.sh | bash
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
**Windows (PowerShell)**
|
|
88
|
-
```powershell
|
|
89
|
-
irm https://raw.githubusercontent.com/autoctxd/autoctxd/main/scripts/install.ps1 | iex
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
That's it — installs Bun if missing, clones the repo into `~/.claude/autoctxd`, installs deps, initializes the DB, and registers the three hooks in your existing `settings.json` (preserving anything already there).
|
|
93
|
-
|
|
94
|
-
Verify with `autoctxd doctor`. Uninstall cleanly with `bun run scripts/uninstall-hooks.ts`.
|
|
95
|
-
|
|
96
|
-
###
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
"
|
|
126
|
-
|
|
127
|
-
"
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
"
|
|
133
|
-
|
|
134
|
-
"
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
#
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
autoctxd embeddings
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
- [x]
|
|
283
|
-
- [x]
|
|
284
|
-
- [x]
|
|
285
|
-
- [x]
|
|
286
|
-
- [
|
|
287
|
-
- [
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
1
|
+
# autoctxd
|
|
2
|
+
|
|
3
|
+
**Persistent, local memory for Claude Code.**
|
|
4
|
+
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](https://bun.sh)
|
|
7
|
+
[](https://github.com/autoctxd/autoctxd/actions/workflows/ci.yml)
|
|
8
|
+
[](#privacy)
|
|
9
|
+
[](#how-it-works)
|
|
10
|
+
[](CONTRIBUTING.md)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
Every Claude Code session starts from scratch. You re-explain your project, re-state decisions you already made, re-describe what you were in the middle of. `autoctxd` fixes that — silently, locally, with zero API cost.
|
|
15
|
+
|
|
16
|
+
- **100% local, zero API cost** — pure heuristics, no LLM calls, nothing leaves your machine
|
|
17
|
+
- Captures every tool use automatically through Claude Code hooks
|
|
18
|
+
- Injects the right ~600 tokens of context into each new session
|
|
19
|
+
- Tracks architectural decisions separately — they never get forgotten
|
|
20
|
+
- Detects work patterns across sessions
|
|
21
|
+
- **Active Guard** — flags actions that contradict past decisions, before you make them
|
|
22
|
+
|
|
23
|
+
## Why autoctxd?
|
|
24
|
+
|
|
25
|
+
| | autoctxd | Mem0 / memori (cloud) | Plain CLAUDE.md |
|
|
26
|
+
|---|---|---|---|
|
|
27
|
+
| Where your code context lives | **Your disk** | Their servers | A static file you maintain |
|
|
28
|
+
| Cost per session | **$0** | API calls billed | $0 |
|
|
29
|
+
| Captures automatically | **Yes** (hooks) | Via SDK calls | No — you write it |
|
|
30
|
+
| Active recall during reasoning | **Yes** (7 MCP tools) | Yes | No |
|
|
31
|
+
| Flags decision contradictions | **Yes** (Active Guard) | No | No |
|
|
32
|
+
| Works offline | **Yes** | No | Yes |
|
|
33
|
+
| Cross-session patterns / hotspots | **Yes** | Limited | No |
|
|
34
|
+
| Setup | **One command** | Account + API key | Edit a file |
|
|
35
|
+
|
|
36
|
+
Built specifically for the **Claude Code workflow** — hooks, MCP, and a local dashboard, not a generic SDK you bolt onto something.
|
|
37
|
+
|
|
38
|
+
## How it works
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
Session 1 Session 2 (days later)
|
|
42
|
+
───────── ─────────────────────
|
|
43
|
+
You work on auth refactor ───┐ ┌──► Claude already knows:
|
|
44
|
+
Claude uses Edit/Write/Bash │ │ • "Migrated from jwt to iron-session"
|
|
45
|
+
▼ │ • Hot files: auth/session.ts
|
|
46
|
+
┌──────────┐ │ • Last session left the login route
|
|
47
|
+
│ SQLite │ │ half-wired (blocked)
|
|
48
|
+
│ LanceDB │─────┘
|
|
49
|
+
└──────────┘ no re-explaining needed
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Two integration modes, use either or both:
|
|
53
|
+
|
|
54
|
+
**1. Passive (hooks, Claude Code only)** — injects context at session start.
|
|
55
|
+
|
|
56
|
+
| Hook | What it does |
|
|
57
|
+
|---|---|
|
|
58
|
+
| `PreToolUse` | Builds context block from past sessions and injects it |
|
|
59
|
+
| `PostToolUse` | Classifies and stores each tool use as an observation |
|
|
60
|
+
| `Stop` | Compresses the session, extracts decisions, detects patterns, generates embeddings |
|
|
61
|
+
|
|
62
|
+
**2. Active (MCP server, works everywhere)** — Claude/Cursor/Windsurf/Cline query memory **during** reasoning via 7 tools:
|
|
63
|
+
|
|
64
|
+
| Tool | What it enables |
|
|
65
|
+
|---|---|
|
|
66
|
+
| `recall_decisions` | Look up past architectural decisions for a project |
|
|
67
|
+
| `recall_unfinished` | Surface blockers from past sessions |
|
|
68
|
+
| `search_memory` | Semantic + FTS search across all your coding memory |
|
|
69
|
+
| `get_project_history` | Recent session summaries |
|
|
70
|
+
| **`check_intent`** | **Active Guard** — flags actions that contradict past decisions |
|
|
71
|
+
| `record_feedback` | Learns from "useful/irrelevant/wrong" signals |
|
|
72
|
+
| `record_decision` | Persists decisions made in-conversation (never forgotten) |
|
|
73
|
+
|
|
74
|
+
See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) for setup in each editor.
|
|
75
|
+
|
|
76
|
+
Nothing leaves your machine.
|
|
77
|
+
|
|
78
|
+
## Install
|
|
79
|
+
|
|
80
|
+
### One-command install
|
|
81
|
+
|
|
82
|
+
**macOS / Linux**
|
|
83
|
+
```bash
|
|
84
|
+
curl -fsSL https://raw.githubusercontent.com/autoctxd/autoctxd/main/scripts/install.sh | bash
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
**Windows (PowerShell)**
|
|
88
|
+
```powershell
|
|
89
|
+
irm https://raw.githubusercontent.com/autoctxd/autoctxd/main/scripts/install.ps1 | iex
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
That's it — installs Bun if missing, clones the repo into `~/.claude/autoctxd`, installs deps, initializes the DB, and registers the three hooks in your existing `settings.json` (preserving anything already there).
|
|
93
|
+
|
|
94
|
+
Verify with `autoctxd doctor`. Uninstall cleanly with `bun run scripts/uninstall-hooks.ts`.
|
|
95
|
+
|
|
96
|
+
### From npm
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
npm install -g autoctxd
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
> Requires [Bun](https://bun.sh) on your PATH. If you don't have Bun, `autoctxd` will print install instructions on first run, or use the one-command installer above which handles Bun for you.
|
|
103
|
+
|
|
104
|
+
### Manual install
|
|
105
|
+
|
|
106
|
+
If you prefer step-by-step, requires [Bun](https://bun.sh) and Claude Code:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
cd ~/.claude
|
|
110
|
+
git clone https://github.com/autoctxd/autoctxd.git
|
|
111
|
+
cd autoctxd
|
|
112
|
+
bun install
|
|
113
|
+
bun run src/cli/index.ts init
|
|
114
|
+
bun run scripts/install-hooks.ts # merges hooks into settings.json
|
|
115
|
+
bun run src/cli/index.ts doctor # verify
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
<details>
|
|
119
|
+
<summary>Or if you want to add the hooks manually, here's the block:</summary>
|
|
120
|
+
|
|
121
|
+
```json
|
|
122
|
+
{
|
|
123
|
+
"hooks": {
|
|
124
|
+
"PreToolUse": [{
|
|
125
|
+
"matcher": "",
|
|
126
|
+
"hooks": [{
|
|
127
|
+
"type": "command",
|
|
128
|
+
"command": "bun run ~/.claude/autoctxd/src/hooks/pre-tool-use.ts"
|
|
129
|
+
}]
|
|
130
|
+
}],
|
|
131
|
+
"PostToolUse": [{
|
|
132
|
+
"matcher": "",
|
|
133
|
+
"hooks": [{
|
|
134
|
+
"type": "command",
|
|
135
|
+
"command": "bun run ~/.claude/autoctxd/src/hooks/post-tool-use.ts"
|
|
136
|
+
}]
|
|
137
|
+
}],
|
|
138
|
+
"Stop": [{
|
|
139
|
+
"matcher": "",
|
|
140
|
+
"hooks": [{
|
|
141
|
+
"type": "command",
|
|
142
|
+
"command": "bun run ~/.claude/autoctxd/src/hooks/stop.ts"
|
|
143
|
+
}]
|
|
144
|
+
}]
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
</details>
|
|
151
|
+
|
|
152
|
+
Restart Claude Code. The next session starts collecting. The one after that starts getting context.
|
|
153
|
+
|
|
154
|
+
## CLI
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
# What has autoctxd learned about you?
|
|
158
|
+
bun run src/cli/index.ts stats
|
|
159
|
+
|
|
160
|
+
# Every decision you've made across projects
|
|
161
|
+
bun run src/cli/index.ts decisions
|
|
162
|
+
|
|
163
|
+
# Hybrid search (semantic + full-text) across everything
|
|
164
|
+
bun run src/cli/index.ts search "race condition async"
|
|
165
|
+
|
|
166
|
+
# Drill into one session
|
|
167
|
+
bun run src/cli/index.ts show session <session-id>
|
|
168
|
+
|
|
169
|
+
# Patterns detected in your workflow
|
|
170
|
+
bun run src/cli/index.ts patterns
|
|
171
|
+
|
|
172
|
+
# Export a project's memory to markdown
|
|
173
|
+
bun run src/cli/index.ts export ./my-app > context.md
|
|
174
|
+
|
|
175
|
+
# Re-run the classifier on old observations (after classifier improvements)
|
|
176
|
+
bun run src/cli/index.ts reclassify
|
|
177
|
+
|
|
178
|
+
# Token accounting: what autoctxd has saved you
|
|
179
|
+
bun run src/cli/index.ts metrics
|
|
180
|
+
|
|
181
|
+
# Launch the local web dashboard
|
|
182
|
+
bun run src/cli/index.ts dashboard
|
|
183
|
+
# → http://localhost:4589
|
|
184
|
+
|
|
185
|
+
# Health check your install
|
|
186
|
+
bun run src/cli/index.ts doctor
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
## Dashboard
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
Running `autoctxd dashboard` launches a local web UI at `http://localhost:4589`:
|
|
194
|
+
|
|
195
|
+
- Metric cards: sessions, observations, decisions, projects, context hit rate, avg explore calls, tokens saved
|
|
196
|
+
- Activity timeline of every observation across all projects
|
|
197
|
+
- Architectural decision feed with alternatives and rationale
|
|
198
|
+
- **Decision chains** — automatically detected sequences like `mysql → postgres → sqlite` across sessions
|
|
199
|
+
- Pattern panel (tool preferences, work focus, hotspots, TDD vs fix-first, peak coding hours)
|
|
200
|
+
- Hybrid search (semantic + full-text) with project filter
|
|
201
|
+
|
|
202
|
+
Everything read-only, everything local. No accounts, no network.
|
|
203
|
+
|
|
204
|
+
## Debug mode
|
|
205
|
+
|
|
206
|
+
Set `AUTOCTXD_DEBUG=1` to log every hook invocation to `data/debug.log`:
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
AUTOCTXD_DEBUG=1 claude # then tail data/debug.log
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
You'll see what was injected, why, and timings.
|
|
213
|
+
|
|
214
|
+
## What gets captured
|
|
215
|
+
|
|
216
|
+
Each `PostToolUse` becomes an **observation**, classified as one of:
|
|
217
|
+
|
|
218
|
+
`bug_fix` · `refactor` · `new_feature` · `config` · `research` · `test` · `decision` · `blocked` · `deploy` · `other`
|
|
219
|
+
|
|
220
|
+
The classifier is pure heuristics. Scores each observation 0–10 for importance. Critical files (`auth`, `payment`, `migration`, `schema`) get boosted. Docs/readmes get demoted.
|
|
221
|
+
|
|
222
|
+
**Decisions** are first-class. Every `bun add`, `npm install`, `cargo add` becomes a stack decision. Every "switched from X to Y" becomes an architectural decision. These never get compressed away.
|
|
223
|
+
|
|
224
|
+
**Patterns** emerge after 3+ sessions in the same project: tool preferences, work-type focus, file hotspots, TDD vs. fix-first workflows, peak coding hours.
|
|
225
|
+
|
|
226
|
+
## What gets injected
|
|
227
|
+
|
|
228
|
+
At session start, `autoctxd` assembles a context block from:
|
|
229
|
+
|
|
230
|
+
- **Architectural decisions** on this project (all of them, always)
|
|
231
|
+
- **Recent session highlights** (top 3 sessions by recency)
|
|
232
|
+
- **Semantically similar past sessions** (cross-project if relevant)
|
|
233
|
+
- **Hot files** (modified 3+ times recently)
|
|
234
|
+
- **Your patterns in this project**
|
|
235
|
+
|
|
236
|
+
Format is compact — targets ~600-800 tokens so it doesn't crowd your context window.
|
|
237
|
+
|
|
238
|
+
## Privacy
|
|
239
|
+
|
|
240
|
+
Everything stays in `~/.claude/autoctxd/data/`. Delete the folder to wipe all memory. No telemetry, no cloud, no network calls during operation.
|
|
241
|
+
|
|
242
|
+
For sensitive projects, drop a `.autoctxd-ignore` file at the project root. Patterns follow a `.gitignore`-style subset — a single `*` opts the whole project out. See [SECURITY.md](SECURITY.md) for the full threat model and the list of what does/doesn't get persisted.
|
|
243
|
+
|
|
244
|
+
## Embedding providers
|
|
245
|
+
|
|
246
|
+
Pick the right trade-off for your machine and threat model. **TF-IDF is the default** — zero install pain, deterministic, fast. Upgrade when you want richer retrieval.
|
|
247
|
+
|
|
248
|
+
| Provider | Dim | Latency | Discrimination | Setup |
|
|
249
|
+
|---|---:|---:|---:|---|
|
|
250
|
+
| `tfidf` *(default)* | 128 | **0.1 ms** | gap 0.170, 92% wins | nothing — built in |
|
|
251
|
+
| `minilm` | 384 | 4.5 ms | gap 0.621, **100% wins** | `autoctxd embeddings switch minilm --yes` (~25MB model download on first use) |
|
|
252
|
+
| `ollama` | 768 | varies | run `bun run benchmark:embeddings` on your box | Requires [Ollama](https://ollama.com) running locally with `ollama pull nomic-embed-text` |
|
|
253
|
+
|
|
254
|
+
*Numbers from `scripts/benchmark-embeddings.ts` over 12 dev-text pairs (anchor / paraphrase / unrelated). "Wins" is the share of pairs where the model puts the paraphrase closer to the anchor than the unrelated text. Higher = better.*
|
|
255
|
+
|
|
256
|
+
```bash
|
|
257
|
+
# What's active and what's available?
|
|
258
|
+
autoctxd embeddings list
|
|
259
|
+
autoctxd embeddings status
|
|
260
|
+
|
|
261
|
+
# Switch — re-embeds everything you've stored, automatically
|
|
262
|
+
autoctxd embeddings switch minilm --yes
|
|
263
|
+
|
|
264
|
+
# Or pin via env (no persistence)
|
|
265
|
+
AUTOCTXD_EMBEDDING=minilm autoctxd ...
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
The cache is partitioned by provider, so switching back is cheap. `@xenova/transformers` is an `optionalDependency` — if `bun install` fails to fetch it, MiniLM is just unavailable and TF-IDF keeps working.
|
|
269
|
+
|
|
270
|
+
## Stack
|
|
271
|
+
|
|
272
|
+
| Component | Tech |
|
|
273
|
+
|---|---|
|
|
274
|
+
| Runtime | Bun |
|
|
275
|
+
| Structured DB | SQLite + FTS5 (full-text search) |
|
|
276
|
+
| Vector DB | LanceDB (dim adapts to active provider) |
|
|
277
|
+
| Embeddings | TF-IDF (default) · MiniLM-L6-v2 via transformers.js · Ollama (any embedding model) |
|
|
278
|
+
| Classification | Keyword + tool/file heuristics |
|
|
279
|
+
|
|
280
|
+
## Roadmap
|
|
281
|
+
|
|
282
|
+
- [x] Local web dashboard
|
|
283
|
+
- [x] Decision chains across sessions
|
|
284
|
+
- [x] Token savings metrics
|
|
285
|
+
- [x] One-command installer for all platforms
|
|
286
|
+
- [x] Health-check doctor
|
|
287
|
+
- [x] Integration test suite
|
|
288
|
+
- [x] **MCP server mode** — Claude queries memory actively, not just at session start
|
|
289
|
+
- [x] **Active Guard** — flags actions that contradict past decisions
|
|
290
|
+
- [x] **Feedback loop** — system learns what's useful to each user
|
|
291
|
+
- [x] **Multi-editor** — Cursor, Windsurf, Cline, Claude Desktop, Claude Code
|
|
292
|
+
- [x] **Pluggable embeddings** — TF-IDF default, MiniLM and Ollama opt-in
|
|
293
|
+
- [x] **`.autoctxd-ignore`** — gitignore-style opt-out for sensitive projects
|
|
294
|
+
- [ ] Codebase awareness — integrate git blame + AST analysis
|
|
295
|
+
- [ ] Predictive context — surface what you'll need next based on patterns
|
|
296
|
+
|
|
297
|
+
## Testing
|
|
298
|
+
|
|
299
|
+
```bash
|
|
300
|
+
bun test # 75 tests, isolated temp DB
|
|
301
|
+
bun run benchmark:embeddings # cross-provider quality + latency
|
|
302
|
+
bun run typecheck # tsc --noEmit
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
Coverage spans the classifier, compressor, decision extractor, decision chains, ignore matcher, embedding providers, and an end-to-end integration flow. Tests never touch your real memory.
|
|
306
|
+
|
|
307
|
+
## License
|
|
308
|
+
|
|
309
|
+
MIT.
|
package/bin/autoctxd.cjs
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
const { spawnSync } = require('node:child_process');
|
|
3
|
+
const path = require('node:path');
|
|
4
|
+
|
|
5
|
+
const bunCheck = spawnSync('bun', ['--version'], {
|
|
6
|
+
stdio: 'ignore',
|
|
7
|
+
shell: process.platform === 'win32',
|
|
8
|
+
});
|
|
9
|
+
|
|
10
|
+
if (bunCheck.error || bunCheck.status !== 0) {
|
|
11
|
+
const isWindows = process.platform === 'win32';
|
|
12
|
+
console.error('');
|
|
13
|
+
console.error(' autoctxd requires Bun (https://bun.sh) but it was not found in PATH.');
|
|
14
|
+
console.error('');
|
|
15
|
+
console.error(' Install Bun:');
|
|
16
|
+
if (isWindows) {
|
|
17
|
+
console.error(' powershell -c "irm bun.sh/install.ps1 | iex"');
|
|
18
|
+
} else {
|
|
19
|
+
console.error(' curl -fsSL https://bun.sh/install | bash');
|
|
20
|
+
}
|
|
21
|
+
console.error('');
|
|
22
|
+
console.error(' Then restart your terminal and run `autoctxd` again.');
|
|
23
|
+
console.error('');
|
|
24
|
+
console.error(' Alternative: use the one-command installer that handles Bun for you:');
|
|
25
|
+
if (isWindows) {
|
|
26
|
+
console.error(' irm https://raw.githubusercontent.com/autoctxd/autoctxd/main/scripts/install.ps1 | iex');
|
|
27
|
+
} else {
|
|
28
|
+
console.error(' curl -fsSL https://raw.githubusercontent.com/autoctxd/autoctxd/main/scripts/install.sh | bash');
|
|
29
|
+
}
|
|
30
|
+
console.error('');
|
|
31
|
+
process.exit(1);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
const cliPath = path.join(__dirname, '..', 'src', 'cli', 'index.ts');
|
|
35
|
+
const args = process.argv.slice(2);
|
|
36
|
+
|
|
37
|
+
const result = spawnSync('bun', [cliPath, ...args], {
|
|
38
|
+
stdio: 'inherit',
|
|
39
|
+
shell: process.platform === 'win32',
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
process.exit(result.status ?? 1);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "autoctxd",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.2",
|
|
4
4
|
"description": "Persistent, local, zero-API memory for Claude Code.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
"benchmark:embeddings": "bun run scripts/benchmark-embeddings.ts"
|
|
28
28
|
},
|
|
29
29
|
"bin": {
|
|
30
|
-
"autoctxd": "
|
|
30
|
+
"autoctxd": "bin/autoctxd.cjs"
|
|
31
31
|
},
|
|
32
32
|
"keywords": [
|
|
33
33
|
"claude",
|