agent-knowledge 1.9.0 → 1.9.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.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "agent-knowledge",
3
3
  "description": "Cross-session memory for AI coding agents. Git-synced Markdown knowledge base with hybrid semantic + TF-IDF search, typed knowledge graph, and session auto-distillation with secrets scrubbing.",
4
- "version": "1.9.0",
4
+ "version": "1.9.2",
5
5
  "author": {
6
6
  "name": "keshrath"
7
7
  },
package/CHANGELOG.md CHANGED
@@ -1,5 +1,38 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.9.2 (2026-04-19) — doc/setup drift cleanup + HOOKS.md rename
4
+
5
+ ### Fixed
6
+
7
+ - **`scripts/setup.js` now installs `first-prompt-inject.mjs`.** It was missing — SETUP.md advertised 6 hooks but automated setup only wired 5. Users running `node scripts/setup.js` previously didn't get the UserPromptSubmit targeted-injection hook.
8
+ - **Test-count badge** corrected in README (557 → 558 after v1.9.1's flake fix; badge wasn't updated at the time).
9
+
10
+ ### Changed
11
+
12
+ - **`docs/hooks.md` → `docs/HOOKS.md`** to match the ALL-CAPS convention of SETUP.md / USER-MANUAL.md / ARCHITECTURE.md / INGEST.md / DASHBOARD.md. All internal links updated (README, SETUP.md, USER-MANUAL.md, setup.js, CHANGELOG.md).
13
+ - **Hook count bumped 5 → 6 everywhere.** `session-start-ingest.mjs` was installed by setup.js (and runs in every session) but wasn't listed in SETUP.md or HOOKS.md. Now documented with a dedicated section in HOOKS.md and a row in every hook table.
14
+ - **Setup banner** (`scripts/setup.js` post-install message) now lists all six hooks with their exact script names instead of a 4-item vague summary.
15
+
16
+ ### Added
17
+
18
+ - **USER-MANUAL.md §3 Configuration → "Lifecycle Hooks" subsection.** Previously the manual had zero hook coverage; it now mirrors the SETUP.md table and points at HOOKS.md for the full reference.
19
+ - **USER-MANUAL.md §3 Configuration → "Persistent Memory — agent-knowledge, not host auto-memory" subsection.** Explains that on hosts with a per-session memory system (Claude Code's `~/.claude/projects/*/memory/`), durable facts should route to agent-knowledge instead. Includes the CLAUDE.md snippet that enforces the redirect for Claude Code users.
20
+ - **README feature list** gains a bullet naming agent-knowledge as the replacement for host auto-memory, linking to the USER-MANUAL section.
21
+
22
+ ### Tests
23
+
24
+ 558/558 passing. No source changes — docs + setup.js only.
25
+
26
+ ## 1.9.1 (2026-04-18) — freshness test flake fix
27
+
28
+ ### Fixed
29
+
30
+ - **`tests/freshness.test.ts` "default-path coverage" no longer times out under full-suite I/O pressure.** Previously ran with `sinceDays: 30`, which made the real `listSessions()` + `getSessionSummary()` path iterate every recent session JSONL on the developer's box — on a heavy-corpus machine this hit the 10s timeout when other test files were contending for I/O. Tightened to `sinceDays: 1` (the test pins "default branch returns an array without throwing" — the window size was incidental) and bumped the per-test timeout to 15s for headroom. Full suite now 558/558 green, stable across repeated runs. The failure had silently shipped through v1.8.1 and v1.9.0 labelled "pre-existing flake"; that was wrong and won't recur.
31
+
32
+ ### Tests
33
+
34
+ 558/558 passing (was 557/558 with the flake counted as pass). No behaviour changes, no source changes outside `tests/`.
35
+
3
36
  ## 1.9.0 (2026-04-18) — env var naming cleanup (**breaking**)
4
37
 
5
38
  Every env var is now under the canonical `AGENT_KNOWLEDGE_*` prefix per the repo-wide Genericity rule (`AGENT_<NAME>_<RESOURCE>`). The old `KNOWLEDGE_*` prefix and the unscoped `EXTRA_SESSION_ROOTS` are gone — no deprecation shim, no startup warning, just renamed. README and docs table rewritten so no host name (`Claude Code`, `~/.claude`) leaks into descriptions — the adapter registry already auto-detects `.claude`, `.cursor`, `.codex`, `.aider`, `.continue`, and OpenCode without configuration.
@@ -31,7 +64,7 @@ Standard third-party keys still work as fallbacks when the scoped form is unset:
31
64
  ### Documented
32
65
 
33
66
  - `AGENT_KNOWLEDGE_INDEX_VERBATIM`, `AGENT_KNOWLEDGE_EMBEDDING_THREADS`, `AGENT_KNOWLEDGE_EMBEDDING_MODEL` — existed but were missing from the README table.
34
- - `AGENT_KNOWLEDGE_AUTOWAKE`, `AGENT_KNOWLEDGE_WAKEUP_BUDGET`, `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT`, `AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET`, `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS`, `AGENT_KNOWLEDGE_PRECOMPACT_NUDGE` — hook env vars were in `docs/hooks.md` but not surfaced in the main README table. Fixed.
67
+ - `AGENT_KNOWLEDGE_AUTOWAKE`, `AGENT_KNOWLEDGE_WAKEUP_BUDGET`, `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT`, `AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET`, `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS`, `AGENT_KNOWLEDGE_PRECOMPACT_NUDGE` — hook env vars were in `docs/HOOKS.md` but not surfaced in the main README table. Fixed.
35
68
 
36
69
  ### Fixed
37
70
 
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
4
4
  [![Node >= 20](https://img.shields.io/badge/Node-%3E%3D%2020-brightgreen.svg)](https://nodejs.org)
5
- [![Tests: 557 passing](https://img.shields.io/badge/Tests-557%20passing-brightgreen.svg)]()
5
+ [![Tests: 558 passing](https://img.shields.io/badge/Tests-558%20passing-brightgreen.svg)]()
6
6
  [![MCP Tools: 6](https://img.shields.io/badge/MCP%20Tools-6-blueviolet.svg)]()
7
7
  [![LongMemEval R@5: 98.8%](https://img.shields.io/badge/LongMemEval%20R%405-98.8%25-brightgreen.svg)]()
8
8
 
@@ -83,7 +83,8 @@ No configuration needed. Additional session roots can be added via the `AGENT_KN
83
83
  - **Deterministic pre-extraction in distillation** — session summaries now include git commits, error patterns, URLs accessed, and packages changed extracted via regex from bash/tool output (no LLM cost)
84
84
  - **Freshness metadata on every search hit (v1.8.1)** — every knowledge result carries `freshness: { body_age_days, last_accessed, access_count, verified_at, verification_age_days, evergreen }`. Agent reads the trust signal and decides; we impose no policy demotion.
85
85
  - **Per-category decay windows (v1.8.1)** — the "Unused" filter and bytype chart honor per-category thresholds (projects 180d, people 365d, decisions 90d, workflows 60d, notes 30d) so identity-shaped content doesn't look stale just because it isn't re-read weekly.
86
- - **Lifecycle hooks** — `SessionStart` auto-wakeup, `UserPromptSubmit` first-prompt targeted injection, `PreCompact` memory-flush nudge. Every hook is fail-open and toggleable via an `AGENT_KNOWLEDGE_*` env var.
86
+ - **Lifecycle hooks** — `SessionStart` auto-wakeup + ingest-freshness check, `UserPromptSubmit` first-prompt targeted injection, `PreCompact` memory-flush nudge + distill, `SessionEnd` distill. Six hook scripts total, all fail-open, each toggleable via an `AGENT_KNOWLEDGE_*` env var. See [`docs/HOOKS.md`](docs/HOOKS.md).
87
+ - **Replaces host auto-memory** — on hosts with a per-session memory system (Claude Code's `~/.claude/projects/*/memory/`, similar in other IDEs), route durable user facts and feedback to agent-knowledge instead. Auto-memory is machine-local and invisible to other machines; agent-knowledge is git-synced, cross-machine, searchable, and surfaces in wakeup. See the Claude Code integration note in [`docs/USER-MANUAL.md`](docs/USER-MANUAL.md#persistent-memory--agent-knowledge-not-host-auto-memory).
87
88
 
88
89
  ## Codebase Ingestion
89
90
 
@@ -2,7 +2,7 @@
2
2
  "id": "agent-knowledge",
3
3
  "name": "Knowledge",
4
4
  "icon": "psychology",
5
- "version": "1.9.0",
5
+ "version": "1.9.2",
6
6
  "description": "Knowledge base — entries, sessions, search, graph relationships",
7
7
  "ui": "./dist/ui/app.js",
8
8
  "css": "./dist/ui/styles.css",
@@ -1,19 +1,20 @@
1
1
  # Hooks (Claude Code)
2
2
 
3
- agent-knowledge ships five hook scripts that integrate with Claude Code's
3
+ agent-knowledge ships six hook scripts that integrate with Claude Code's
4
4
  lifecycle events. They live under `scripts/hooks/` and are installed by
5
5
  `scripts/setup.js` into `~/.claude/settings.json`.
6
6
 
7
7
  All hooks fail open — any internal error is logged to stderr and the hook
8
8
  returns an empty JSON object so the user is never blocked.
9
9
 
10
- | Script | Event | Purpose |
11
- | ------------------------- | ---------------- | ------------------------------------------------------------------------ |
12
- | `session-start.js` | SessionStart | Announces dashboard URL + auto-loads wakeup payload into context |
13
- | `first-prompt-inject.mjs` | UserPromptSubmit | Injects query-targeted knowledge hits on the session's first real prompt |
14
- | `precompact-flush.mjs` | PreCompact | Rich session summary on disk + save-unsaved-context nudge into context |
15
- | `precompact-distill.mjs` | PreCompact | Lightweight text snapshot of recent user prompts |
16
- | `sessionend-distill.mjs` | SessionEnd | Final summary (turn counts, tool uses, first 20 prompts) |
10
+ | Script | Event | Purpose |
11
+ | -------------------------- | ---------------- | ------------------------------------------------------------------------ |
12
+ | `session-start.js` | SessionStart | Announces dashboard URL + auto-loads wakeup payload into context |
13
+ | `session-start-ingest.mjs` | SessionStart | Detects project + reports knowledge-ingest cache drift via SHA256 diff |
14
+ | `first-prompt-inject.mjs` | UserPromptSubmit | Injects query-targeted knowledge hits on the session's first real prompt |
15
+ | `precompact-flush.mjs` | PreCompact | Rich session summary on disk + save-unsaved-context nudge into context |
16
+ | `precompact-distill.mjs` | PreCompact | Lightweight text snapshot of recent user prompts |
17
+ | `sessionend-distill.mjs` | SessionEnd | Final summary (turn counts, tool uses, first 20 prompts) |
17
18
 
18
19
  ## session-start.js
19
20
 
@@ -37,6 +38,18 @@ Two jobs:
37
38
  Requires `npm run build` to have succeeded — if `dist/wakeup.js` is missing,
38
39
  only the dashboard-URL line is emitted (fail-open).
39
40
 
41
+ ## session-start-ingest.mjs
42
+
43
+ Second SessionStart hook, paired with `session-start.js`. On session start:
44
+
45
+ 1. Detects the current project from `cwd`.
46
+ 2. Checks whether a `knowledge-ingest` cache exists for it.
47
+ 3. If no cache → suggests bootstrapping (the `/knowledge-ingest` skill).
48
+ 4. If cache exists → computes a quick SHA256 diff of the current files vs the cached snapshot and reports how many files changed since last ingest.
49
+
50
+ Zero LLM tokens, reads/hashes only. Fail-open: all errors logged to stderr,
51
+ always outputs valid JSON.
52
+
40
53
  ## first-prompt-inject.mjs
41
54
 
42
55
  Fires on UserPromptSubmit. When the session's FIRST real user prompt arrives,
@@ -170,7 +183,7 @@ Replace `/abs/path/to/agent-knowledge` with your clone path.
170
183
 
171
184
  ## Testing the hooks
172
185
 
173
- `tests/hooks/hooks.test.ts` covers all five scripts with shape-correct
186
+ `tests/hooks/hooks.test.ts` covers the six scripts with shape-correct
174
187
  fail-open assertions plus a positive-path render test for
175
188
  `first-prompt-inject.mjs`. Run `npm test -- tests/hooks/` to execute them
176
189
  in isolation.
package/docs/SETUP.md CHANGED
@@ -69,7 +69,7 @@ From the agent-knowledge clone:
69
69
  node scripts/setup.js
70
70
  ```
71
71
 
72
- This detects Claude Code, registers the MCP server in `~/.claude.json`, wires all 5 hooks into `~/.claude/settings.json`, and grants `mcp__agent-knowledge__*` permission in one shot. Restart Claude Code afterwards to pick up the new config.
72
+ This detects Claude Code, registers the MCP server in `~/.claude.json`, wires all 6 lifecycle hooks into `~/.claude/settings.json`, and grants `mcp__agent-knowledge__*` permission in one shot. Restart Claude Code afterwards to pick up the new config.
73
73
 
74
74
  #### Register the MCP server (manual)
75
75
 
@@ -180,17 +180,18 @@ curl -X PUT http://localhost:3423/api/knowledge/notes/my-note \
180
180
 
181
181
  ## Hooks
182
182
 
183
- agent-knowledge ships **5 hook scripts** that wire into Claude Code's lifecycle events. `scripts/setup.js` installs them automatically; the block below shows the manual equivalent. Support varies by client.
183
+ agent-knowledge ships **6 hook scripts** that wire into Claude Code's lifecycle events. `scripts/setup.js` installs them automatically; the block below shows the manual equivalent. Support varies by client.
184
184
 
185
- | Hook | Event | Purpose |
186
- | ------------------------- | ---------------- | -------------------------------------------------------------------------------- |
187
- | `session-start.js` | SessionStart | Dashboard URL + auto-loads token-budgeted wakeup payload into context |
188
- | `first-prompt-inject.mjs` | UserPromptSubmit | v1.8 — query-targeted knowledge hits injected on the session's first real prompt |
189
- | `precompact-flush.mjs` | PreCompact | Rich session summary on disk + save-unsaved-context nudge into context |
190
- | `precompact-distill.mjs` | PreCompact | Lightweight text snapshot of recent user prompts |
191
- | `sessionend-distill.mjs` | SessionEnd | Final summary (turn counts, tool uses, first 20 prompts) |
185
+ | Hook | Event | Purpose |
186
+ | -------------------------- | ---------------- | -------------------------------------------------------------------------------- |
187
+ | `session-start.js` | SessionStart | Dashboard URL + auto-loads token-budgeted wakeup payload into context |
188
+ | `session-start-ingest.mjs` | SessionStart | Detects project + reports knowledge-ingest cache drift via SHA256 diff |
189
+ | `first-prompt-inject.mjs` | UserPromptSubmit | v1.8 — query-targeted knowledge hits injected on the session's first real prompt |
190
+ | `precompact-flush.mjs` | PreCompact | Rich session summary on disk + save-unsaved-context nudge into context |
191
+ | `precompact-distill.mjs` | PreCompact | Lightweight text snapshot of recent user prompts |
192
+ | `sessionend-distill.mjs` | SessionEnd | Final summary (turn counts, tool uses, first 20 prompts) |
192
193
 
193
- See [`docs/hooks.md`](hooks.md) for the full hook reference including environment variables and test coverage.
194
+ See [`docs/HOOKS.md`](HOOKS.md) for the full hook reference including environment variables and test coverage.
194
195
 
195
196
  ### Claude Code Hooks
196
197
 
@@ -204,6 +205,11 @@ See [`docs/hooks.md`](hooks.md) for the full hook reference including environmen
204
205
  "type": "command",
205
206
  "command": "node \"/path/to/agent-knowledge/scripts/hooks/session-start.js\"",
206
207
  "timeout": 5
208
+ },
209
+ {
210
+ "type": "command",
211
+ "command": "node \"/path/to/agent-knowledge/scripts/hooks/session-start-ingest.mjs\"",
212
+ "timeout": 10
207
213
  }
208
214
  ]
209
215
  }
@@ -141,6 +141,39 @@ knowledge_admin with action "config", memory_dir "/custom/path/knowledge"
141
141
  knowledge_admin with action "config", auto_distill false
142
142
  ```
143
143
 
144
+ ### Lifecycle Hooks
145
+
146
+ agent-knowledge ships six lifecycle hook scripts that integrate with Claude Code's event system. Running `node scripts/setup.js` installs all six into `~/.claude/settings.json`; on other hosts that don't support lifecycle hooks (Cursor, Windsurf), the MCP tools still work — you just lose the automatic context injection.
147
+
148
+ | Script | Event | Purpose |
149
+ | -------------------------- | ---------------- | ------------------------------------------------------------------------- |
150
+ | `session-start.js` | SessionStart | Dashboard URL + auto-loads token-budgeted wakeup payload into context |
151
+ | `session-start-ingest.mjs` | SessionStart | Detects project + reports knowledge-ingest cache drift via SHA256 diff |
152
+ | `first-prompt-inject.mjs` | UserPromptSubmit | Query-targeted knowledge hits injected on the session's first real prompt |
153
+ | `precompact-flush.mjs` | PreCompact | Rich session summary on disk + save-unsaved-context nudge into context |
154
+ | `precompact-distill.mjs` | PreCompact | Lightweight text snapshot of recent user prompts |
155
+ | `sessionend-distill.mjs` | SessionEnd | Final summary (turn counts, tool uses, first 20 prompts) |
156
+
157
+ Every hook fails open — if a script errors, it logs to stderr and the session continues. Each hook has env-var toggles (`AGENT_KNOWLEDGE_AUTOWAKE`, `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT`, `AGENT_KNOWLEDGE_PRECOMPACT_NUDGE`, etc.) — see [`docs/HOOKS.md`](HOOKS.md) for the full reference, test coverage, and budget/threshold knobs.
158
+
159
+ ### Persistent Memory — agent-knowledge, not host auto-memory
160
+
161
+ If your host has a per-session memory system (Claude Code writes `~/.claude/projects/*/memory/` files; Cursor has its own analogue), route durable facts to **agent-knowledge** instead:
162
+
163
+ - User preferences / feedback rules → `knowledge(action: write, category: "workflows", ..., evergreen: true)`
164
+ - User profile facts → `knowledge(action: write, category: "people", ...)`
165
+ - Project context → `knowledge(action: write, category: "projects", ...)`
166
+
167
+ Host auto-memory is machine-local and invisible to other sessions and other machines. agent-knowledge is git-synced, searchable via `knowledge_search`, shows up in wakeup, and survives machine swaps. For Claude Code specifically, add a rule to your global `~/.claude/CLAUDE.md` so Claude honors the redirect automatically:
168
+
169
+ ```markdown
170
+ ## Persistent memory: always agent-knowledge, never auto-memory
171
+
172
+ Every durable fact goes to agent-knowledge via `knowledge(action: write)`. Never write
173
+ to `~/.claude/projects/*/memory/` — auto-memory is machine-local and invisible to other
174
+ sessions.
175
+ ```
176
+
144
177
  ---
145
178
 
146
179
  ## 4. Dashboard Guide
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-knowledge",
3
- "version": "1.9.0",
3
+ "version": "1.9.2",
4
4
  "description": "Cross-session memory and recall for AI agents — git-synced knowledge base, knowledge graph, confidence scoring, hybrid semantic+TF-IDF search, auto-distillation with secrets scrubbing",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
package/scripts/setup.js CHANGED
@@ -142,6 +142,14 @@ addUnmatchedHook(
142
142
  10,
143
143
  );
144
144
 
145
+ // UserPromptSubmit: targeted knowledge injection on the session's first real prompt
146
+ addUnmatchedHook(
147
+ 'UserPromptSubmit',
148
+ 'first-prompt-inject.mjs',
149
+ `node "${join(hookDir, 'first-prompt-inject.mjs')}"`,
150
+ 10,
151
+ );
152
+
145
153
  // PreCompact: rich summary (library) + simple text distill (heuristic)
146
154
  addUnmatchedHook(
147
155
  'PreCompact',
@@ -205,13 +213,15 @@ console.log(`
205
213
  Setup complete!
206
214
 
207
215
  Restart Claude Code to load the new MCP server. Every session will now:
208
- - Show the knowledge dashboard URL on start (SessionStart hook)
209
- - Flush a rich session summary before compaction (precompact-flush)
210
- - Snapshot recent user prompts before compaction (precompact-distill)
211
- - Dump a final session summary on exit (sessionend-distill)
216
+ - Show the knowledge dashboard URL + L0/L1 wakeup payload on start (session-start.js)
217
+ - Report ingest freshness on start (session-start-ingest.mjs)
218
+ - Inject query-targeted knowledge hits on the first real user prompt (first-prompt-inject.mjs)
219
+ - Flush a rich session summary before compaction (precompact-flush.mjs)
220
+ - Snapshot recent user prompts before compaction (precompact-distill.mjs)
221
+ - Dump a final session summary on exit (sessionend-distill.mjs)
212
222
 
213
223
  Dashboard: http://localhost:3423 (auto-starts on first MCP connection)
214
224
  Knowledge base: ~/agent-knowledge/ (configurable via AGENT_KNOWLEDGE_MEMORY_DIR)
215
225
 
216
- See docs/hooks.md for details and docs/SETUP.md for manual configuration.
226
+ See docs/HOOKS.md for details and docs/SETUP.md for manual configuration.
217
227
  `);