agent-knowledge 1.9.1 → 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.
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +24 -1
- package/README.md +3 -2
- package/agent-desk-plugin.json +1 -1
- package/docs/{hooks.md → HOOKS.md} +22 -9
- package/docs/SETUP.md +16 -10
- package/docs/USER-MANUAL.md +33 -0
- package/package.json +1 -1
- package/scripts/setup.js +15 -5
|
@@ -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.
|
|
4
|
+
"version": "1.9.2",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "keshrath"
|
|
7
7
|
},
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,28 @@
|
|
|
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
|
+
|
|
3
26
|
## 1.9.1 (2026-04-18) — freshness test flake fix
|
|
4
27
|
|
|
5
28
|
### Fixed
|
|
@@ -41,7 +64,7 @@ Standard third-party keys still work as fallbacks when the scoped form is unset:
|
|
|
41
64
|
### Documented
|
|
42
65
|
|
|
43
66
|
- `AGENT_KNOWLEDGE_INDEX_VERBATIM`, `AGENT_KNOWLEDGE_EMBEDDING_THREADS`, `AGENT_KNOWLEDGE_EMBEDDING_MODEL` — existed but were missing from the README table.
|
|
44
|
-
- `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/
|
|
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.
|
|
45
68
|
|
|
46
69
|
### Fixed
|
|
47
70
|
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[](LICENSE)
|
|
4
4
|
[](https://nodejs.org)
|
|
5
|
-
[]()
|
|
6
6
|
[]()
|
|
7
7
|
[]()
|
|
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.
|
|
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
|
|
package/agent-desk-plugin.json
CHANGED
|
@@ -1,19 +1,20 @@
|
|
|
1
1
|
# Hooks (Claude Code)
|
|
2
2
|
|
|
3
|
-
agent-knowledge ships
|
|
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
|
|
11
|
-
|
|
|
12
|
-
| `session-start.js`
|
|
13
|
-
| `
|
|
14
|
-
| `
|
|
15
|
-
| `precompact-
|
|
16
|
-
| `
|
|
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
|
|
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
|
|
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 **
|
|
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
|
|
186
|
-
|
|
|
187
|
-
| `session-start.js`
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `precompact-
|
|
191
|
-
| `
|
|
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/
|
|
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
|
}
|
package/docs/USER-MANUAL.md
CHANGED
|
@@ -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.
|
|
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 (
|
|
209
|
-
-
|
|
210
|
-
-
|
|
211
|
-
-
|
|
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/
|
|
226
|
+
See docs/HOOKS.md for details and docs/SETUP.md for manual configuration.
|
|
217
227
|
`);
|