agent-knowledge 1.9.1 → 1.9.3

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.1",
4
+ "version": "1.9.3",
5
5
  "author": {
6
6
  "name": "keshrath"
7
7
  },
package/CHANGELOG.md CHANGED
@@ -1,5 +1,41 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.9.3 (2026-04-19) — README showcase rewrite
4
+
5
+ ### Changed
6
+
7
+ - **README no longer carries inline version markers** (`(v1.8)`, `(v1.8.1)`, `(v1.8 lifecycle integration)`). The feature list now describes the current state as a single coherent surface — version history lives in this CHANGELOG where it belongs. Moves the README from "changelog-in-bullet-points" to "how it works today".
8
+ - **Section renames to match**: `### Scored promoter (v1.8)` → `### Scored promoter`, `### Hooks (v1.8 lifecycle integration)` → `### Hooks`, `v1.8 search knobs:` → `Search knobs:`.
9
+ - **Wakeup bullet now names the token budget** — 800 default, overridable via `token_budget` param or `AGENT_KNOWLEDGE_WAKEUP_BUDGET` env var. The number was previously only in the env-var table.
10
+ - **Testing block refreshed** — stale `352 tests across 20 files` replaced with the real `558 tests across 35 files`; added `typecheck` and `check` script references so the documented workflow matches what `npm run check` actually runs.
11
+
12
+ ### Tests
13
+
14
+ 558/558 passing. Docs + metadata only — no source changes.
15
+
16
+ ## 1.9.2 (2026-04-19) — doc/setup drift cleanup + HOOKS.md rename
17
+
18
+ ### Fixed
19
+
20
+ - **`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.
21
+ - **Test-count badge** corrected in README (557 → 558 after v1.9.1's flake fix; badge wasn't updated at the time).
22
+
23
+ ### Changed
24
+
25
+ - **`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).
26
+ - **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.
27
+ - **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.
28
+
29
+ ### Added
30
+
31
+ - **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.
32
+ - **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.
33
+ - **README feature list** gains a bullet naming agent-knowledge as the replacement for host auto-memory, linking to the USER-MANUAL section.
34
+
35
+ ### Tests
36
+
37
+ 558/558 passing. No source changes — docs + setup.js only.
38
+
3
39
  ## 1.9.1 (2026-04-18) — freshness test flake fix
4
40
 
5
41
  ### Fixed
@@ -41,7 +77,7 @@ Standard third-party keys still work as fallbacks when the scoped form is unset:
41
77
  ### Documented
42
78
 
43
79
  - `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/hooks.md` but not surfaced in the main README table. Fixed.
80
+ - `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
81
 
46
82
  ### Fixed
47
83
 
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
 
@@ -51,17 +51,17 @@ No configuration needed. Additional session roots can be added via the `AGENT_KN
51
51
  - **Host-agnostic session search** -- unified search across every major AI coding assistant (Claude Code, Cursor, Codex CLI, Aider, Continue.dev, Cline, OpenCode). No host name is baked into configuration — the adapter registry probes installed host roots at startup.
52
52
  - **Hybrid search** -- semantic vector similarity blended with TF-IDF keyword ranking
53
53
  - **Git-synced knowledge base** -- markdown vault with YAML frontmatter, auto commit and push on writes
54
- - **Automatic staleness detection (v1.8.1)** -- `knowledge_analyze(action: "stale_by_code_activity")` cross-references file paths mentioned in each entry body against `filesModified` in recent session summaries. Pairs with a symbol-presence precision layer: identifiers the entry quotes (inline backticks + fenced blocks) are checked in the touched file; if they still exist, confidence downweights ×0.3. Entries with `evergreen: true` are exempt.
55
- - **Search-gap tracking (v1.8.1)** -- `knowledge_analyze(action: "search_gaps")` surfaces zero-result queries over the last `since_days`, grouped by token-Jaccard similarity. The clearest signal for "what entries should I write next?".
56
- - **Section-priority context packer (v1.8.1)** -- `knowledge(action: "wakeup")` assembles a multi-section bundle (`identity` → `active_tasks` → `recent_decisions` → `known_gotchas` → `last_session_summary` → `top_weighted` → `semantic_fallback`) within a token budget. Unused section budget redistributes to later sections.
57
- - **Scored + gated promoter (v1.8)** -- session insights promoted via a 6-signal weighted scorer with three independent gates (`minScore`, `minRecallCount`, `minUniqueQueries`). Runs automatically in background, on demand via `knowledge_admin(action: "promote")`, or benchable offline via `npm run bench:promote`. Emits an auditable `.dreams/YYYY-MM-DD.md` diary every run. Replaces the regex-only distiller.
54
+ - **Automatic staleness detection** -- `knowledge_analyze(action: "stale_by_code_activity")` cross-references file paths mentioned in each entry body against `filesModified` in recent session summaries. Pairs with a symbol-presence precision layer: identifiers the entry quotes (inline backticks + fenced blocks) are checked in the touched file; if they still exist, confidence downweights ×0.3. Entries with `evergreen: true` are exempt.
55
+ - **Search-gap tracking** -- `knowledge_analyze(action: "search_gaps")` surfaces zero-result queries over the last `since_days`, grouped by token-Jaccard similarity. The clearest signal for "what entries should I write next?".
56
+ - **Section-priority context packer** -- `knowledge(action: "wakeup")` assembles a multi-section bundle (`identity` → `active_tasks` → `recent_decisions` → `known_gotchas` → `last_session_summary` → `top_weighted` → `semantic_fallback`) within a token budget (default 800, override via `token_budget` or `AGENT_KNOWLEDGE_WAKEUP_BUDGET`). Unused section budget redistributes to later sections.
57
+ - **Scored + gated promoter** -- session insights promoted via a 6-signal weighted scorer with three independent gates (`minScore`, `minRecallCount`, `minUniqueQueries`). Runs automatically in background, on demand via `knowledge_admin(action: "promote")`, or benchable offline via `npm run bench:promote`. Emits an auditable `.dreams/YYYY-MM-DD.md` diary every run.
58
58
  - **Pluggable adapter system** -- add support for new tools by implementing the `SessionAdapter` interface
59
59
  - **Embeddings** -- local (Hugging Face), OpenAI, Claude/Voyage, or Gemini providers
60
60
  - **Fuzzy matching** -- typo-tolerant search using Levenshtein distance
61
61
  - **6 search scopes** -- errors, plans, configs, tools, files, decisions
62
62
  - **6 MCP tools** -- consolidated action-based interface (`knowledge`, `knowledge_search`, `knowledge_session`, `knowledge_graph`, `knowledge_analyze`, `knowledge_admin`)
63
- - **Evergreen entries (v1.8)** -- `evergreen: true` in frontmatter exempts an entry from decay in ranking AND makes it append-only under promotion. Dashboard renders a push-pin badge on these cards.
64
- - **Author attribution (v1.8.1)** -- optional `author: <string>` frontmatter surfaces as a muted chip on each card.
63
+ - **Evergreen entries** -- `evergreen: true` in frontmatter exempts an entry from decay in ranking AND makes it append-only under promotion. Dashboard renders a push-pin badge on these cards.
64
+ - **Author attribution** -- optional `author: <string>` frontmatter surfaces as a muted chip on each card.
65
65
  - **Code graph resolution** -- `calls`, `imports`, `inherits` edge types for code structure; directed BFS traversal (`outbound`/`inbound`/`both`); `bulk_link` for efficient ingestion; `unlink_by_origin` for clearing stale code edges before re-ingest; `code:` prefixed node IDs distinguish code from knowledge
66
66
  - **Temporal knowledge graph** -- edges support `valid_from` / `valid_to` validity windows; `as_of` queries return point-in-time snapshots; `invalidate` action marks facts as ended without deleting them
67
67
  - **Hybrid scoring boosts** -- proper-noun and temporal-proximity boosts on top of TF-IDF + semantic blend, capped at +66.7%, short-circuit when no signals are present
@@ -81,9 +81,10 @@ No configuration needed. Additional session roots can be added via the `AGENT_KN
81
81
  - **Knowledge brief** — `knowledge_analyze(action: "brief")` returns a cached ~200 token summary (core concepts, active projects, recent decisions, stale and gap counts) for session-start orientation
82
82
  - **Edge provenance** — graph edges track `origin` (manual, auto-link, distill, reflect) so analysis can distinguish user judgment from automated heuristics
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
- - **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
- - **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.
84
+ - **Freshness metadata on every search hit** — 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
+ - **Per-category decay windows** — 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 + 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
 
@@ -162,10 +163,10 @@ Response shape: `{mode: "general" | "scoped", sessions, knowledge}`. Scoped mode
162
163
 
163
164
  Scopes: `errors`, `plans`, `configs`, `tools`, `files`, `decisions`, `all`.
164
165
 
165
- v1.8 search knobs:
166
+ Search knobs:
166
167
 
167
168
  - `mmr: true` applies Maximal Marginal Relevance re-ranking (kills near-duplicate clusters in top-K). `mmr_lambda` 0-1, default 0.7.
168
- - `category_mode: "boost"` (default) gives matching-category entries a 1.25× score multiplier instead of dropping non-matches. Pass `"filter"` for legacy hard-filter behavior.
169
+ - `category_mode: "boost"` (default) gives matching-category entries a 1.25× score multiplier instead of dropping non-matches. Pass `"filter"` for hard-filter behavior.
169
170
  - `explain: true` attaches `score_components: {bm25, decay, maturity, confidence, category_boost, mmr_penalty}` to every knowledge hit.
170
171
 
171
172
  ### Sessions
@@ -213,11 +214,11 @@ v1.8 search knobs:
213
214
  | | `rebuild_embeddings` | Re-embed all knowledge entries (useful on provider switch) | -- |
214
215
  | | `prune_orphans` | Delete embeddings for sessions no longer on disk | `vacuum?`, `force_vacuum?` |
215
216
  | | `vacuum` | Reclaim free pages in the vector store | -- |
216
- | | `promote` | Scored + gated promoter (v1.8) | `promote_mode?` (`apply`\|`explain`), `min_score?`, `min_recall_count?`, `min_unique_queries?` |
217
+ | | `promote` | Scored + gated promoter | `promote_mode?` (`apply`\|`explain`), `min_score?`, `min_recall_count?`, `min_unique_queries?` |
217
218
 
218
- ### Scored promoter (v1.8)
219
+ ### Scored promoter
219
220
 
220
- Session insights no longer drop into the knowledge base via regex distillation. Instead, every project-level candidate is scored on six signals (relevance 0.30, frequency 0.24, query-diversity 0.15, recency 0.15, consolidation 0.10, conceptual-richness 0.06) and gated on `minScore ≥ 0.5`, `minRecallCount ≥ 2`, `minUniqueQueries ≥ 2`. All three gates must pass. Background auto-promotion is controlled by the same `auto_distill` config flag; invoke on demand with `knowledge_admin(action: "promote")`.
221
+ Every project-level candidate is scored on six signals (relevance 0.30, frequency 0.24, query-diversity 0.15, recency 0.15, consolidation 0.10, conceptual-richness 0.06) and gated on `minScore ≥ 0.5`, `minRecallCount ≥ 2`, `minUniqueQueries ≥ 2`. All three gates must pass. Background auto-promotion is controlled by the same `auto_distill` config flag; invoke on demand with `knowledge_admin(action: "promote")`.
221
222
 
222
223
  - `promote_mode: "explain"` (default) — score + gate candidates, write diary, DO NOT touch the KB.
223
224
  - `promote_mode: "apply"` — promote candidates that pass, write diary, git-commit.
@@ -382,9 +383,11 @@ This enables HTTP-based writes from other services without an MCP connection.
382
383
  ## Testing
383
384
 
384
385
  ```bash
385
- npm test # 352 tests across 20 files
386
+ npm test # 558 tests across 35 files
386
387
  npm run test:watch # Watch mode
387
- npm run lint # Type-check (tsc --noEmit)
388
+ npm run lint # ESLint on src/ and tests/
389
+ npm run typecheck # tsc --noEmit
390
+ npm run check # typecheck + lint + format + test
388
391
  ```
389
392
 
390
393
  ## Environment Variables
@@ -423,7 +426,7 @@ Project-scoped overrides win over the standard keys. Set either; the scoped form
423
426
  | `AGENT_KNOWLEDGE_ANTHROPIC_API_KEY` | `ANTHROPIC_API_KEY` | Claude / Voyage embeddings |
424
427
  | `AGENT_KNOWLEDGE_GEMINI_API_KEY` | `GEMINI_API_KEY` | Gemini embeddings |
425
428
 
426
- ### Hooks (v1.8 lifecycle integration)
429
+ ### Hooks
427
430
 
428
431
  | Variable | Default | Description |
429
432
  | -------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -2,7 +2,7 @@
2
2
  "id": "agent-knowledge",
3
3
  "name": "Knowledge",
4
4
  "icon": "psychology",
5
- "version": "1.9.1",
5
+ "version": "1.9.3",
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.1",
3
+ "version": "1.9.3",
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
  `);