agent-knowledge 2.0.0 → 3.1.1

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.
Files changed (129) hide show
  1. package/CHANGELOG.md +59 -0
  2. package/README.md +35 -32
  3. package/dist/embeddings/local.d.ts.map +1 -1
  4. package/dist/embeddings/local.js +3 -1
  5. package/dist/embeddings/local.js.map +1 -1
  6. package/dist/events.d.ts +6 -0
  7. package/dist/events.d.ts.map +1 -1
  8. package/dist/events.js +10 -2
  9. package/dist/events.js.map +1 -1
  10. package/dist/index.js +12 -0
  11. package/dist/index.js.map +1 -1
  12. package/dist/knowledge/analyze.d.ts.map +1 -1
  13. package/dist/knowledge/analyze.js +18 -11
  14. package/dist/knowledge/analyze.js.map +1 -1
  15. package/dist/knowledge/distill.d.ts.map +1 -1
  16. package/dist/knowledge/distill.js +28 -16
  17. package/dist/knowledge/distill.js.map +1 -1
  18. package/dist/knowledge/git.d.ts +3 -4
  19. package/dist/knowledge/git.d.ts.map +1 -1
  20. package/dist/knowledge/git.js +60 -46
  21. package/dist/knowledge/git.js.map +1 -1
  22. package/dist/knowledge/graph.d.ts +2 -0
  23. package/dist/knowledge/graph.d.ts.map +1 -1
  24. package/dist/knowledge/graph.js +8 -0
  25. package/dist/knowledge/graph.js.map +1 -1
  26. package/dist/knowledge/ingest-freshness.d.ts +22 -0
  27. package/dist/knowledge/ingest-freshness.d.ts.map +1 -0
  28. package/dist/knowledge/ingest-freshness.js +93 -0
  29. package/dist/knowledge/ingest-freshness.js.map +1 -0
  30. package/dist/knowledge/remove.d.ts +11 -0
  31. package/dist/knowledge/remove.d.ts.map +1 -0
  32. package/dist/knowledge/remove.js +24 -0
  33. package/dist/knowledge/remove.js.map +1 -0
  34. package/dist/knowledge/search.d.ts +74 -8
  35. package/dist/knowledge/search.d.ts.map +1 -1
  36. package/dist/knowledge/search.js +321 -40
  37. package/dist/knowledge/search.js.map +1 -1
  38. package/dist/knowledge/similar.d.ts +7 -0
  39. package/dist/knowledge/similar.d.ts.map +1 -0
  40. package/dist/knowledge/similar.js +51 -0
  41. package/dist/knowledge/similar.js.map +1 -0
  42. package/dist/knowledge/store.d.ts +17 -0
  43. package/dist/knowledge/store.d.ts.map +1 -1
  44. package/dist/knowledge/store.js +117 -79
  45. package/dist/knowledge/store.js.map +1 -1
  46. package/dist/rest-server.d.ts +12 -2
  47. package/dist/rest-server.d.ts.map +1 -1
  48. package/dist/rest-server.js +75 -10
  49. package/dist/rest-server.js.map +1 -1
  50. package/dist/search/bm25.d.ts +8 -0
  51. package/dist/search/bm25.d.ts.map +1 -1
  52. package/dist/search/bm25.js +32 -20
  53. package/dist/search/bm25.js.map +1 -1
  54. package/dist/search/excerpt.d.ts +1 -1
  55. package/dist/search/excerpt.d.ts.map +1 -1
  56. package/dist/search/excerpt.js +19 -1
  57. package/dist/search/excerpt.js.map +1 -1
  58. package/dist/search/lexicon.d.ts +37 -0
  59. package/dist/search/lexicon.d.ts.map +1 -0
  60. package/dist/search/lexicon.js +83 -0
  61. package/dist/search/lexicon.js.map +1 -0
  62. package/dist/search/mmr.d.ts +9 -3
  63. package/dist/search/mmr.d.ts.map +1 -1
  64. package/dist/search/mmr.js +21 -7
  65. package/dist/search/mmr.js.map +1 -1
  66. package/dist/search/types.d.ts +2 -0
  67. package/dist/search/types.d.ts.map +1 -1
  68. package/dist/server.d.ts.map +1 -1
  69. package/dist/server.js +0 -5
  70. package/dist/server.js.map +1 -1
  71. package/dist/sessions/human.d.ts +12 -0
  72. package/dist/sessions/human.d.ts.map +1 -0
  73. package/dist/sessions/human.js +52 -0
  74. package/dist/sessions/human.js.map +1 -0
  75. package/dist/sessions/parser.d.ts +39 -0
  76. package/dist/sessions/parser.d.ts.map +1 -1
  77. package/dist/sessions/parser.js +142 -18
  78. package/dist/sessions/parser.js.map +1 -1
  79. package/dist/sessions/search.d.ts +2 -0
  80. package/dist/sessions/search.d.ts.map +1 -1
  81. package/dist/sessions/search.js +147 -67
  82. package/dist/sessions/search.js.map +1 -1
  83. package/dist/sessions/snapshot.d.ts +19 -0
  84. package/dist/sessions/snapshot.d.ts.map +1 -0
  85. package/dist/sessions/snapshot.js +118 -0
  86. package/dist/sessions/snapshot.js.map +1 -0
  87. package/dist/sessions/summary.d.ts +24 -5
  88. package/dist/sessions/summary.d.ts.map +1 -1
  89. package/dist/sessions/summary.js +106 -145
  90. package/dist/sessions/summary.js.map +1 -1
  91. package/dist/slice.d.ts +5 -0
  92. package/dist/slice.d.ts.map +1 -0
  93. package/dist/slice.js +28 -0
  94. package/dist/slice.js.map +1 -0
  95. package/dist/text.d.ts +9 -0
  96. package/dist/text.d.ts.map +1 -0
  97. package/dist/text.js +16 -0
  98. package/dist/text.js.map +1 -0
  99. package/dist/tool-handlers.d.ts.map +1 -1
  100. package/dist/tool-handlers.js +6 -10
  101. package/dist/tool-handlers.js.map +1 -1
  102. package/dist/transport/rest.d.ts.map +1 -1
  103. package/dist/transport/rest.js +152 -35
  104. package/dist/transport/rest.js.map +1 -1
  105. package/dist/vectorstore/store.d.ts +9 -0
  106. package/dist/vectorstore/store.d.ts.map +1 -1
  107. package/dist/vectorstore/store.js +23 -0
  108. package/dist/vectorstore/store.js.map +1 -1
  109. package/dist/wakeup.d.ts +5 -0
  110. package/dist/wakeup.d.ts.map +1 -1
  111. package/dist/wakeup.js +10 -1
  112. package/dist/wakeup.js.map +1 -1
  113. package/docs/ARCHITECTURE.md +6 -9
  114. package/docs/HOOKS.md +138 -237
  115. package/docs/SETUP.md +61 -122
  116. package/docs/USER-MANUAL.md +45 -31
  117. package/package.json +6 -6
  118. package/plugin/skills/knowledge-ingest/scripts/validate.mjs +2 -2
  119. package/scripts/plugins/opencode/agent-knowledge.ts +32 -81
  120. package/scripts/setup.js +78 -145
  121. package/scripts/source-walk.d.mts +12 -0
  122. package/scripts/source-walk.mjs +94 -0
  123. package/scripts/tree-sitter-extract.mjs +10 -76
  124. package/scripts/hooks/first-prompt-inject.mjs +0 -242
  125. package/scripts/hooks/precompact-distill.mjs +0 -105
  126. package/scripts/hooks/precompact-flush.mjs +0 -192
  127. package/scripts/hooks/session-start-ingest.mjs +0 -238
  128. package/scripts/hooks/session-start.js +0 -211
  129. package/scripts/hooks/sessionend-distill.mjs +0 -198
package/docs/HOOKS.md CHANGED
@@ -1,248 +1,149 @@
1
- # Hooks (Claude Code)
2
-
3
- agent-knowledge ships six hook scripts that integrate with Claude Code's
4
- lifecycle events. They live under `scripts/hooks/` and are installed by
5
- `scripts/setup.js` into `~/.claude/settings.json`.
6
-
7
- All hooks fail open — any internal error is logged to stderr and the hook
8
- returns an empty JSON object so the user is never blocked.
9
-
10
- | Script | Event | Purpose |
11
- | -------------------------- | ---------------- | ------------------------------------------------------------------------ |
12
- | `session-start.js` | SessionStart | Names the `/knowledge` pane + auto-loads the L0 identity 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) |
18
-
19
- ## session-start.js
20
-
21
- Four jobs:
22
-
23
- 1. Says where the person browses the knowledge base (the `/knowledge` pane of
24
- the agent-knowledge plugin), in the `systemMessage` and in SessionStart
25
- `additionalContext`.
26
- 2. Auto-loads the **L0 identity** section (who the user is — query-agnostic
27
- facts from `~/agent-knowledge/identity.md`) into the same
28
- `additionalContext`, so every session starts with that context without a
29
- manual `knowledge(action="wakeup")` call.
30
- 3. Clears the `first-prompt-inject.mjs` marker file for this `session_id` on
31
- every SessionStart event (startup / resume / clear). Resumed sessions
32
- reuse the same `session_id`, so without this the inject hook silently
33
- skips on the next prompt because the prior run's marker is still on disk.
34
- 4. **Identity onboarding**: if neither `identity.md` nor `IDENTITY.md` exists
35
- in the memory dir AND there is no `.identity-declined` opt-out marker,
36
- appends a short instruction to `additionalContext` telling the agent to
37
- ask the user three questions (name/role, stack, projects) and save the
38
- answers via the host's `Write` tool. The agent drives the conversation;
39
- the user never has to manually create the file. If the user says "skip"
40
- or "not now", the agent creates `~/agent-knowledge/.identity-declined` and
41
- the onboarding prompt stops firing. Delete that file to re-enable.
42
-
43
- L1 top-weighted facts are **not** auto-loaded here. The companion
44
- `first-prompt-inject.mjs` runs a query-targeted KB search on the session's
45
- first real prompt and injects a better-matched slice than any
46
- query-agnostic pre-load would. Users who want the full legacy L0+L1 pack can
47
- still call `knowledge(action="wakeup")` manually, or flip
48
- `AGENT_KNOWLEDGE_WAKEUP_BUDGET` up to re-enable larger identity sections.
49
-
50
- Also emits a user-visible `systemMessage` on every session start with a
51
- status suffix so the user can always tell the hook ran:
52
-
53
- - `agent-knowledge: /knowledge | identity: 312 chars` — when a
54
- user-authored `identity.md` was loaded.
55
- - `agent-knowledge: /knowledge | identity: onboarding pending` —
56
- when no identity file exists and onboarding is queued (agent will ask
57
- the user on the next prompt).
58
- - `agent-knowledge: /knowledge | identity: declined (delete ~/agent-knowledge/.identity-declined to redo)` —
59
- when the user previously opted out.
60
- - `agent-knowledge: /knowledge | identity: placeholder (no identity.md) · inject rearmed` —
61
- fallback for edge cases (e.g. stat errors), with `· inject rearmed` when
62
- the first-prompt-inject marker was cleared.
63
- - `agent-knowledge: /knowledge | autowake off · resume` — when
64
- `AGENT_KNOWLEDGE_AUTOWAKE=0` disables auto-injection.
65
-
66
- The model-facing context and the user-facing line are separate channels —
67
- the `systemMessage` is purely a UX signal so the user can see what got
68
- pre-loaded and whether the next prompt will trigger query-targeted injection.
69
-
70
- ### Environment variables
1
+ # The session lifecycle (Claude Code)
71
2
 
72
- | Variable | Default | Description |
73
- | ------------------------------- | ------- | ------------------------------------------------------- |
74
- | `AGENT_KNOWLEDGE_AUTOWAKE` | `1` | Set `0` / `false` to skip the identity auto-injection |
75
- | `AGENT_KNOWLEDGE_WAKEUP_BUDGET` | `200` | Max tokens (chars/4 estimate) for the L0 identity slice |
3
+ In Claude Code the agent-knowledge plugin's mod (`plugin/hooks/register.tsx`,
4
+ Claude Code 2.1.289+) ties the knowledge base into each session. There are no
5
+ command hooks to install and nothing to add to `settings.json`: install the
6
+ plugin and the lifecycle comes with it.
76
7
 
77
- Requires `npm run build` to have succeeded — if `dist/wakeup.js` is missing,
78
- only the `/knowledge` line is emitted (fail-open).
8
+ ```
9
+ claude plugin marketplace add keshrath/agent-knowledge
10
+ claude plugin install agent-knowledge@agent-knowledge
11
+ ```
79
12
 
80
- ## session-start-ingest.mjs
13
+ Every part goes through the local REST server (`127.0.0.1:3423`, see the
14
+ README) and fails open: a server that is down or slow, or an error anywhere,
15
+ leaves the session exactly as it would be without the plugin. No part waits
16
+ more than 2 s for the server (a snapshot 10 s): a process that holds the port
17
+ and never answers costs a prompt at most that, and the holder itself lets the
18
+ port go after two unanswered self-checks, 30 s apart.
19
+
20
+ | When | What the mod does | REST it calls |
21
+ | -------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------- |
22
+ | The conversation's first message | One context block: what the knowledge base holds, who the person is, ingest state | `GET /api/overview`, `/api/wakeup`, `/api/ingest` |
23
+ | The first real prompt | The entries matching it ride beside it, once per conversation | `GET /api/knowledge/search?mmr=true` |
24
+ | A compaction of the main thread | Snapshot of the session; the summary keeps what is still to be saved | `POST /api/sessions/:id/snapshot` (`compact`) |
25
+ | The session ending (or `/clear`) | The session's last snapshot | `POST /api/sessions/:id/snapshot` (`end`) |
26
+
27
+ ## The context block (`prompt.context`)
28
+
29
+ The model's first message carries one block named `agent-knowledge`. It is
30
+ computed again after a compaction and after `/clear`.
31
+
32
+ 1. **What the knowledge base holds**: entry and session counts by category,
33
+ and how to reach it (`knowledge_search`, `knowledge` action `read`,
34
+ `/knowledge` for the person).
35
+ 2. **Who the person is** (the L0 identity): the identity section of the
36
+ wakeup bundle, from `identity.md` in the knowledge base, headed
37
+ `--- Knowledge wakeup (identity only; call `knowledge action=wakeup` for L1 facts) ---`.
38
+ 3. **Identity onboarding**: while there is neither `identity.md` nor a
39
+ `.identity-declined` marker, the block asks the model to ask the person three
40
+ questions (name and role, stack, projects) and save the answers to
41
+ `identity.md` with the Write tool, or to create `.identity-declined` when
42
+ they say not now. Delete that file to be asked again.
43
+ 4. **Ingest freshness** of the session's folder (the knowledge-ingest skill's
44
+ `.knowledge-ingest-cache.json`, compared by SHA-256): a folder with three or
45
+ more source files that was never ingested is offered `/knowledge-ingest`;
46
+ one with files changed, new or deleted since says how many. A current
47
+ ingest, or a folder with fewer source files, adds nothing. Hashing only,
48
+ no tokens.
49
+
50
+ L1 facts are not loaded here: the first-prompt injection brings the entries
51
+ that match what is asked, which a query-agnostic pack cannot.
81
52
 
82
- Second SessionStart hook, paired with `session-start.js`. On session start:
53
+ | Variable | Default | Description |
54
+ | ------------------------------- | ------- | ------------------------------------------------------- |
55
+ | `AGENT_KNOWLEDGE_AUTOWAKE` | `1` | `0` / `false` / `off`: no identity and no onboarding |
56
+ | `AGENT_KNOWLEDGE_WAKEUP_BUDGET` | `200` | Tokens (chars/4) for the identity section, `[50, 4000]` |
83
57
 
84
- 1. Detects the current project from `cwd`.
85
- 2. Checks whether a `knowledge-ingest` cache exists for it.
86
- 3. If no cache → suggests bootstrapping (the `/knowledge-ingest` skill).
87
- 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.
58
+ ## The first real prompt (`prompt.submit`)
88
59
 
89
- Zero LLM tokens, reads/hashes only. Fail-open: all errors logged to stderr,
90
- always outputs valid JSON.
60
+ The conversation's first real prompt is searched against the knowledge base
61
+ (MMR re-ranked, so the hits are not five copies of one thing) and the top hits
62
+ ride beside it, where the model reads them and the person does not:
91
63
 
92
- ## first-prompt-inject.mjs
93
-
94
- Fires on UserPromptSubmit. When the session's FIRST real user prompt arrives,
95
- runs it through `searchKnowledge(prompt, { mmr: true })` and injects the top-K
96
- hits into `additionalContext` before the model reads the prompt. Complements
97
- the wakeup pack (which is query-agnostic) with query-targeted context.
98
-
99
- Gates (all must pass to fire):
100
-
101
- - Prompt length ≥ 10 characters.
102
- - Prompt does NOT start with `/` (slash command) or `!` (bash shortcut).
103
- - No marker file exists yet for this session ID.
104
-
105
- The marker file (`{dataDir}/.first-prompt-seen/<session_id>`) is only written
106
- AFTER a real search has run — skip-gates like `/clear` do NOT burn the shot,
107
- so the user's next real question still gets injection.
108
-
109
- When injection fires, the hook also emits a user-visible `systemMessage`:
110
- `knowledge: injected 4 hits (decisions/database-choice.md, sessions/foo.md, +2 more)`.
111
- This is separate from the model-facing `additionalContext` — the user sees a
112
- one-line summary in the transcript, the model sees the full rendered hit list.
113
-
114
- ### Environment variables
115
-
116
- | Variable | Default | Description |
117
- | -------------------------------------- | ------------------- | ------------------------------------------------------- |
118
- | `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT` | `1` | Set `0` / `false` / `off` to disable |
119
- | `AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET` | `600` | Max tokens (chars/4 estimate), clamped to `[100, 8000]` |
120
- | `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS` | `4` | Max rendered entries, clamped to `[1, 20]` |
121
- | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Knowledge base to search |
122
-
123
- ## precompact-flush.mjs
124
-
125
- Called right before the host compacts the transcript. Two jobs:
126
-
127
- 1. Imports `dist/sessions/summary.js` from the built library, pulls a rich
128
- session summary via `getSessionSummary(sessionId)`, and writes it to
129
- `~/agent-knowledge/sessions/<project-slug>/precompact-<timestamp>-<id>.md`.
130
- If `dist/` is missing, the disk dump is skipped (fail-open).
131
- 2. Injects a short "save-unsaved-context" nudge into the PreCompact
132
- `additionalContext` so the agent is prompted to write anything important
133
- to the knowledge base BEFORE compaction summarises the transcript away.
134
-
135
- ### Environment variables
136
-
137
- | Variable | Default | Description |
138
- | ---------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
139
- | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Where rich summaries are written |
140
- | `AGENT_KNOWLEDGE_PRECOMPACT_NUDGE` | `1` | Set `0` / `false` to disable the nudge only. Set `off` to suppress both the nudge AND the disk dump. |
141
-
142
- ## precompact-distill.mjs
143
-
144
- A simpler heuristic companion to `precompact-flush.mjs`. Reads the last
145
- ~200 KB of the transcript JSONL, extracts the last 10 user prompts, and
146
- writes them to
147
- `~/agent-knowledge/projects/precompact-<slug>-<session>.md`. This one does
148
- not require the library to be built, so it still works when `dist/` is
149
- missing. Running both is fine — they target different files.
150
-
151
- ### Environment variables
152
-
153
- | Variable | Default | Description |
154
- | ---------------------------- | ------------------- | ------------------------------------------------- |
155
- | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Where the snapshot is written (`<dir>/projects/`) |
156
-
157
- ## sessionend-distill.mjs
158
-
159
- On `SessionEnd`, walks the whole transcript JSONL, counts user / assistant
160
- turns and `tool_use` blocks, collects the first 20 user prompts, and writes
161
- a markdown summary to
162
- `~/agent-knowledge/projects/session-<slug>-<session>.md`. Gives
163
- agent-knowledge a breadcrumb for later session search/recall.
164
-
165
- Also emits a user-visible `systemMessage` on stdout so you can tell the
166
- hook actually ran — receipt of the turn / tool-use counts and the target
167
- file path, or the reason for skipping (missing transcript, write failure).
168
- A one-line breadcrumb is appended to
169
- `~/agent-knowledge/sessions/index.md` on every successful distill, so
170
- the receipt is durable even when the host tears the transcript down
171
- before painting the message.
172
-
173
- On a successful distill the hook also POSTs the receipt to the REST
174
- server's `POST /api/events` (port from `AGENT_KNOWLEDGE_PORT`, default
175
- 3423), where the `/knowledge` pane picks it up — covers hosts (like Claude
176
- Code `/exit`) that swallow `systemMessage` on SessionEnd. Fails open on
177
- ECONNREFUSED / timeout; set `AGENT_KNOWLEDGE_EVENTS=0` to suppress the POST
178
- entirely.
179
-
180
- ## Manual configuration
181
-
182
- `scripts/setup.js` writes the hooks into `~/.claude/settings.json`
183
- automatically. If you need to configure them by hand, add entries like:
184
-
185
- ```json
186
- {
187
- "hooks": {
188
- "SessionStart": [
189
- {
190
- "hooks": [
191
- {
192
- "type": "command",
193
- "command": "node \"/abs/path/to/agent-knowledge/scripts/hooks/session-start.js\"",
194
- "timeout": 5
195
- }
196
- ]
197
- }
198
- ],
199
- "UserPromptSubmit": [
200
- {
201
- "hooks": [
202
- {
203
- "type": "command",
204
- "command": "node \"/abs/path/to/agent-knowledge/scripts/hooks/first-prompt-inject.mjs\"",
205
- "timeout": 10
206
- }
207
- ]
208
- }
209
- ],
210
- "PreCompact": [
211
- {
212
- "hooks": [
213
- {
214
- "type": "command",
215
- "command": "node \"/abs/path/to/agent-knowledge/scripts/hooks/precompact-flush.mjs\"",
216
- "timeout": 10
217
- },
218
- {
219
- "type": "command",
220
- "command": "node \"/abs/path/to/agent-knowledge/scripts/hooks/precompact-distill.mjs\"",
221
- "timeout": 10
222
- }
223
- ]
224
- }
225
- ],
226
- "SessionEnd": [
227
- {
228
- "hooks": [
229
- {
230
- "type": "command",
231
- "command": "node \"/abs/path/to/agent-knowledge/scripts/hooks/sessionend-distill.mjs\"",
232
- "timeout": 10
233
- }
234
- ]
235
- }
236
- ]
237
- }
238
- }
239
64
  ```
65
+ ## Knowledge — top hits for your first prompt
240
66
 
241
- Replace `/abs/path/to/agent-knowledge` with your clone path.
67
+ _Injected automatically by agent-knowledge. Query these entries with `knowledge` (action=read, path=…) before deciding whether to issue a wider `knowledge_search`._
242
68
 
243
- ## Testing the hooks
69
+ - **Release ritual** (`workflows/release.md`, score 3.42) — Bump, tag, push…
70
+ ```
244
71
 
245
- `tests/hooks/hooks.test.ts` covers the six scripts with shape-correct
246
- fail-open assertions plus a positive-path render test for
247
- `first-prompt-inject.mjs`. Run `npm test -- tests/hooks/` to execute them
248
- in isolation.
72
+ Under the prompt the transcript shows one line naming them by title, e.g.
73
+ `agent-knowledge: 2 entries for this prompt: Release ritual, Tag before you push`.
74
+
75
+ - A prompt shorter than 10 characters, a slash command, a `!` shell line, a
76
+ background task's notice or another session's message is not searched and
77
+ leaves the injection for the next prompt.
78
+ - The first search the server answers spends it, hits or none. A server that
79
+ is down leaves it for the next prompt.
80
+ - Once per conversation: again after `/clear` (a new conversation) and in a
81
+ restarted or resumed session.
82
+
83
+ | Variable | Default | Description |
84
+ | -------------------------------------- | ------- | -------------------------------------------- |
85
+ | `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT` | `1` | `0` / `false` / `off` to turn it off |
86
+ | `AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET` | `600` | Tokens (chars/4) for the hits, `[100, 8000]` |
87
+ | `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS` | `2` | Entries at most, `[1, 2]` |
88
+
89
+ ## The session snapshot (`session.compact`, `session.end`)
90
+
91
+ When the main conversation is compacted (`/compact`, or at the threshold) and
92
+ when the session ends (exit, `/clear`, resume elsewhere), the server writes
93
+ the session's gist into the knowledge base:
94
+
95
+ `sessions/<project>/<YYYY-MM-DD>-<session id, 8 chars>.md`
96
+
97
+ One file per session, rewritten at each compaction and at the end, titled by
98
+ the project, the day and the first thing asked (`demo · 2026-11-13 · fix the
99
+ sync`), with the session id, folder, branch (none outside git) and times in
100
+ its frontmatter, and sections **What was asked** (the first and last ten
101
+ prompts), **Tools used**, **Files** (the ones an editing or writing tool call
102
+ changed), **Commits** (the ones `git commit` reported) and **Errors**. In the
103
+ `/knowledge` pane they are the `sessions` category, left out of `all`. It is built by the session parser
104
+ (every host the adapters read), with secrets, e-mail addresses and system
105
+ noise (reminders, task notifications, command wrappers) scrubbed as the
106
+ distiller scrubs them. A session where nothing was asked writes nothing. The
107
+ file is searchable at once and reaches other machines with the next git sync.
108
+
109
+ After a compaction a toast names the snapshot (`Session saved at compaction: demo · 2026-11-13 ·
110
+ fix the sync`): a transcript line would land in the middle of the turn. After `/clear` the new
111
+ conversation's first line names it (`Session saved: …`): a toast is drawn neither in the
112
+ conversation ending nor on the screen `/clear` just emptied. Every other open session toasts it
113
+ as a live event.
114
+
115
+ At a compaction the summary is also asked to keep, under **Knowledge to
116
+ save**, each durable fact not yet written to the knowledge base (decisions,
117
+ gotchas, hard-won commands, people and ownership, project state), so the model
118
+ can still save them with `knowledge` (action `write`) afterwards.
119
+
120
+ | Variable | Default | Description |
121
+ | ---------------------------------- | ------- | ------------------------------------------------------------------------------------ |
122
+ | `AGENT_KNOWLEDGE_PRECOMPACT_NUDGE` | `1` | `0` / `false`: the summary is left as asked. `off`: no snapshot at compaction either |
123
+
124
+ Subagents' compactions are left alone.
125
+
126
+ ## From 2.x command hooks
127
+
128
+ agent-knowledge 2.x installed six command hooks (`scripts/hooks/*.js|mjs`)
129
+ into `~/.claude/settings.json`. 3.0 removes the scripts. Run
130
+ `node scripts/setup.js --host=claude` once to take their entries out of
131
+ `settings.json` (or delete every hook command naming
132
+ `agent-knowledge/scripts/hooks/`), then install the plugin. Remove a
133
+ hand-written `agent-knowledge` entry from `~/.claude.json` too, so the tools do
134
+ not appear twice.
135
+
136
+ ## Other hosts
137
+
138
+ OpenCode gets the first-prompt injection, the compaction nudge and a session
139
+ summary from its own plugin (`agent-knowledge/opencode`, see
140
+ [SETUP.md](SETUP.md#opencode-plugins)). Any host can call the REST routes above.
141
+
142
+ ## Tests
143
+
144
+ `plugin/tests/knowledge.test.ts` (`claude plugin test plugin`) covers each
145
+ part of the lifecycle against a scripted server: the context block's parts and
146
+ switches, the injection's gates, budget and once-per-conversation rule, the
147
+ compaction's snapshot and summary, the end. `tests/rest-lifecycle.test.ts`
148
+ covers the routes against real files and transcripts, and
149
+ `tests/e2e-claude/` runs them in the real Claude Code CLI.
package/docs/SETUP.md CHANGED
@@ -12,8 +12,8 @@ Detailed instructions for installing, configuring, and integrating agent-knowled
12
12
  - [Cursor](#cursor)
13
13
  - [Windsurf](#windsurf)
14
14
  - [REST API](#rest-api)
15
- - [Hooks](#hooks)
16
- - [Claude Code Hooks](#claude-code-hooks)
15
+ - [Session lifecycle](#session-lifecycle)
16
+ - [Claude Code](#claude-code-1)
17
17
  - [OpenCode Plugins](#opencode-plugins)
18
18
  - [Cursor and Windsurf](#cursor-and-windsurf)
19
19
  - [Knowledge Base Setup](#knowledge-base-setup)
@@ -61,17 +61,26 @@ agent-knowledge works with any MCP client (stdio) or HTTP client (REST API). Pic
61
61
 
62
62
  ### Claude Code
63
63
 
64
- #### Quick setup (recommended)
64
+ #### The plugin (recommended)
65
65
 
66
- From the agent-knowledge clone:
66
+ ```bash
67
+ claude plugin marketplace add keshrath/agent-knowledge
68
+ claude plugin install agent-knowledge@agent-knowledge
69
+ ```
70
+
71
+ It runs the MCP server (`npx agent-knowledge@^3`), adds the `knowledge-ingest` skill and a mod (Claude Code 2.1.289+): the `/knowledge` pane and the [session lifecycle](HOOKS.md). Nothing goes into `settings.json`.
72
+
73
+ Coming from 2.x, run once from the clone:
67
74
 
68
75
  ```bash
69
- node scripts/setup.js
76
+ node scripts/setup.js --host=claude
70
77
  ```
71
78
 
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.
79
+ It removes the six command hooks 2.x installed into `~/.claude/settings.json` (their scripts are gone in 3.0) and grants `mcp__agent-knowledge__*`. Remove a hand-written `agent-knowledge` entry from `~/.claude.json` as well, so the tools do not appear twice.
80
+
81
+ #### Register the MCP server alone (manual)
73
82
 
74
- #### Register the MCP server (manual)
83
+ Without the plugin there is no pane and no lifecycle, only the tools:
75
84
 
76
85
  ```bash
77
86
  claude mcp add agent-knowledge -s user \
@@ -178,83 +187,13 @@ curl -X POST http://localhost:3423/api/knowledge \
178
187
 
179
188
  ---
180
189
 
181
- ## Hooks
182
-
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.
190
+ ## Session lifecycle
184
191
 
185
- | Hook | Event | Purpose |
186
- | -------------------------- | ---------------- | -------------------------------------------------------------------------------- |
187
- | `session-start.js` | SessionStart | Names the `/knowledge` pane + auto-loads the L0 identity 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
+ What happens around each session, beyond the tools the model calls. Support varies by client.
193
193
 
194
- See [`docs/HOOKS.md`](HOOKS.md) for the full hook reference including environment variables and test coverage.
195
-
196
- ### Claude Code Hooks
194
+ ### Claude Code
197
195
 
198
- ```json
199
- {
200
- "hooks": {
201
- "SessionStart": [
202
- {
203
- "hooks": [
204
- {
205
- "type": "command",
206
- "command": "node \"/path/to/agent-knowledge/scripts/hooks/session-start.js\"",
207
- "timeout": 5
208
- },
209
- {
210
- "type": "command",
211
- "command": "node \"/path/to/agent-knowledge/scripts/hooks/session-start-ingest.mjs\"",
212
- "timeout": 10
213
- }
214
- ]
215
- }
216
- ],
217
- "UserPromptSubmit": [
218
- {
219
- "hooks": [
220
- {
221
- "type": "command",
222
- "command": "node \"/path/to/agent-knowledge/scripts/hooks/first-prompt-inject.mjs\"",
223
- "timeout": 10
224
- }
225
- ]
226
- }
227
- ],
228
- "PreCompact": [
229
- {
230
- "hooks": [
231
- {
232
- "type": "command",
233
- "command": "node \"/path/to/agent-knowledge/scripts/hooks/precompact-flush.mjs\"",
234
- "timeout": 10
235
- },
236
- {
237
- "type": "command",
238
- "command": "node \"/path/to/agent-knowledge/scripts/hooks/precompact-distill.mjs\"",
239
- "timeout": 10
240
- }
241
- ]
242
- }
243
- ],
244
- "SessionEnd": [
245
- {
246
- "hooks": [
247
- {
248
- "type": "command",
249
- "command": "node \"/path/to/agent-knowledge/scripts/hooks/sessionend-distill.mjs\"",
250
- "timeout": 10
251
- }
252
- ]
253
- }
254
- ]
255
- }
256
- }
257
- ```
196
+ The plugin's mod: each conversation starts knowing what the knowledge base holds, who the person is (or asks them once) and the project's ingest state; the first real prompt carries the matching entries; the session is snapshotted into `sessions/<project>/` when it is compacted and when it ends. No command hooks. See [HOOKS.md](HOOKS.md) for every part and its switches.
258
197
 
259
198
  ### OpenCode Plugins
260
199
 
@@ -285,24 +224,24 @@ node scripts/setup.js --host=all # both Claude Code an
285
224
 
286
225
  #### What the plugin does
287
226
 
288
- Mirrors the Claude Code hooks where opencode has an equivalent event:
227
+ The Claude Code lifecycle where opencode has an equivalent event:
289
228
 
290
- | Claude Code hook | OpenCode analog | Behavior |
291
- | ------------------------- | --------------------------------- | --------------------------------------------------------------------- |
292
- | `session-start.js` | `event: session.created` | Knowledge-base toast + clears stale first-prompt marker on resume. |
293
- | `first-prompt-inject.mjs` | `chat.message` | Searches the KB and prepends a rendered hits block to the user parts. |
294
- | `precompact-flush.mjs` | `experimental.session.compacting` | Pushes a "save unsaved knowledge before compaction" nudge. |
295
- | `sessionend-distill.mjs` | `event: session.deleted` | Writes `~/agent-knowledge/projects/session-opencode-<slug>.md`. |
229
+ | Claude Code (mod) | OpenCode analog | Behavior |
230
+ | -------------------------------- | --------------------------------- | --------------------------------------------------------------------- |
231
+ | the context block | `event: session.created` | Knowledge-base toast + clears stale first-prompt marker on resume. |
232
+ | the first real prompt | `chat.message` | Searches the KB and prepends a rendered hits block to the user parts. |
233
+ | compaction: keep what is unsaved | `experimental.session.compacting` | Pushes a "save unsaved knowledge before compaction" nudge. |
234
+ | the session snapshot at the end | `event: session.deleted` | Writes `~/agent-knowledge/projects/session-opencode-<slug>.md`. |
296
235
 
297
- Not ported (opencode has no equivalent surface):
236
+ Not here (opencode has no equivalent surface):
298
237
 
299
- - `session-start-ingest.mjs` (paired with the `/knowledge-ingest` skill flow).
300
- - `precompact-distill.mjs` (opencode compaction does not expose the transcript to plugins).
301
- - L0 identity auto-load (no `additionalContext` equivalent — put identity in `AGENTS.md` or call `knowledge(action="wakeup")` manually).
238
+ - The ingest freshness of the project (pair `/knowledge-ingest` by hand).
239
+ - The snapshot at compaction (opencode compaction does not expose the transcript to plugins).
240
+ - L0 identity auto-load (no context-block equivalent — put identity in `AGENTS.md` or call `knowledge(action="wakeup")` manually).
302
241
 
303
242
  #### Environment variables
304
243
 
305
- Same as the Claude hooks, all optional:
244
+ As for the Claude Code mod, all optional:
306
245
 
307
246
  | Variable | Default | Description |
308
247
  | -------------------------------------- | ------------------- | ------------------------------------------------------- |
@@ -311,9 +250,9 @@ Same as the Claude hooks, all optional:
311
250
  | `AGENT_KNOWLEDGE_PORT` | `3423` | REST port (plugin queries `/api/knowledge/search`). |
312
251
  | `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT` | `1` | Set `0` / `false` / `off` to disable inject entirely. |
313
252
  | `AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET` | `600` | Max inject tokens (chars/4), clamped `[100, 8000]`. |
314
- | `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS` | `4` | Max rendered hits, clamped `[1, 20]`. |
253
+ | `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS` | `2` | Max rendered hits, clamped `[1, 2]`. |
315
254
 
316
- Every hook fails open — errors during search, toast, session walk, or disk write are swallowed and the user is never blocked.
255
+ Every part fails open — errors during search, toast, session walk, or disk write are swallowed and the user is never blocked.
317
256
 
318
257
  Combine with `AGENTS.md` instructions (see below).
319
258
 
@@ -390,15 +329,15 @@ agent-knowledge ships a **knowledge-ingest** skill for bootstrapping or updating
390
329
 
391
330
  ### Automatic installation
392
331
 
393
- `node scripts/setup.js` installs the skill to both `~/.claude/skills/` and `~/.agents/skills/`, covering all major platforms:
332
+ The Claude Code plugin carries the skill. `node scripts/setup.js` installs it to `~/.agents/skills/` for the other platforms:
394
333
 
395
- | Platform | Discovery path | Covered by setup.js |
396
- | ----------- | ---------------------------------------- | ------------------- |
397
- | Claude Code | `~/.claude/skills/` | Yes |
398
- | OpenCode | `~/.claude/skills/`, `~/.agents/skills/` | Yes |
399
- | Cursor | `~/.claude/skills/`, `~/.agents/skills/` | Yes |
400
- | Codex CLI | `~/.agents/skills/` | Yes |
401
- | Gemini CLI | `~/.agents/skills/` | Yes |
334
+ | Platform | Discovery path | Covered by |
335
+ | ----------- | ---------------------------------------- | ----------------------- |
336
+ | Claude Code | the plugin | `claude plugin install` |
337
+ | OpenCode | `~/.claude/skills/`, `~/.agents/skills/` | setup.js |
338
+ | Cursor | `~/.claude/skills/`, `~/.agents/skills/` | setup.js |
339
+ | Codex CLI | `~/.agents/skills/` | setup.js |
340
+ | Gemini CLI | `~/.agents/skills/` | setup.js |
402
341
 
403
342
  ### Manual installation
404
343
 
@@ -463,24 +402,24 @@ Architecture notes, deployment info, etc.
463
402
 
464
403
  ## Environment Variables
465
404
 
466
- | Variable | Default | Description |
467
- | --------------------------------------------------------- | ------------------- | ---------------------------------------------------------------- |
468
- | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Path to git-synced knowledge base |
469
- | `AGENT_KNOWLEDGE_DATA_DIR` | (platform config) | Override primary host data root (adapters auto-detect otherwise) |
470
- | `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` | -- | Additional session directories, comma-separated |
471
- | `OPENCODE_DATA_DIR` | (platform default) | Override OpenCode data dir (default `~/.local/share/opencode`) |
472
- | `AGENT_KNOWLEDGE_PORT` | `3423` | Local REST API port (the `/knowledge` pane, hooks, agent-tasks) |
473
- | `AGENT_KNOWLEDGE_HOST` | `127.0.0.1` | REST bind address |
474
- | `AGENT_KNOWLEDGE_EMBEDDING_PROVIDER` | `local` | Embedding provider (local, openai, claude, gemini) |
475
- | `AGENT_KNOWLEDGE_EMBEDDING_ALPHA` | `0.5` | Blend weight for semantic vs TF-IDF search (0-1) |
476
- | `AGENT_KNOWLEDGE_EMBEDDING_IDLE_TIMEOUT` | — | Idle timeout for embedding worker (ms) |
477
- | `AGENT_KNOWLEDGE_EMBEDDING_THREADS` | — | Number of ONNX threads for local embeddings |
478
- | `AGENT_KNOWLEDGE_EMBEDDING_MODEL` | — | Model name for embedding provider |
479
- | `AGENT_KNOWLEDGE_GIT_URL` | — | Remote git URL for knowledge base sync |
480
- | `AGENT_KNOWLEDGE_AUTO_DISTILL` | — | Enable auto-distillation of sessions (true/false) |
481
- | `AGENT_KNOWLEDGE_OPENAI_API_KEY` / `OPENAI_API_KEY` | — | API key for OpenAI embeddings |
482
- | `AGENT_KNOWLEDGE_ANTHROPIC_API_KEY` / `ANTHROPIC_API_KEY` | — | API key for Claude/Voyage embeddings |
483
- | `AGENT_KNOWLEDGE_GEMINI_API_KEY` / `GEMINI_API_KEY` | — | API key for Gemini embeddings |
405
+ | Variable | Default | Description |
406
+ | --------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------- |
407
+ | `AGENT_KNOWLEDGE_MEMORY_DIR` | `~/agent-knowledge` | Path to git-synced knowledge base |
408
+ | `AGENT_KNOWLEDGE_DATA_DIR` | (platform config) | Override primary host data root (adapters auto-detect otherwise) |
409
+ | `AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS` | -- | Additional session directories, comma-separated |
410
+ | `OPENCODE_DATA_DIR` | (platform default) | Override OpenCode data dir (default `~/.local/share/opencode`) |
411
+ | `AGENT_KNOWLEDGE_PORT` | `3423` | Local REST API port (the Claude Code and opencode plugins, agent-tasks) |
412
+ | `AGENT_KNOWLEDGE_HOST` | `127.0.0.1` | REST bind address |
413
+ | `AGENT_KNOWLEDGE_EMBEDDING_PROVIDER` | `local` | Embedding provider (local, openai, claude, gemini) |
414
+ | `AGENT_KNOWLEDGE_EMBEDDING_ALPHA` | `0.5` | Blend weight for semantic vs TF-IDF search (0-1) |
415
+ | `AGENT_KNOWLEDGE_EMBEDDING_IDLE_TIMEOUT` | — | Idle timeout for embedding worker (ms) |
416
+ | `AGENT_KNOWLEDGE_EMBEDDING_THREADS` | — | Number of ONNX threads for local embeddings |
417
+ | `AGENT_KNOWLEDGE_EMBEDDING_MODEL` | — | Model name for embedding provider |
418
+ | `AGENT_KNOWLEDGE_GIT_URL` | — | Remote git URL for knowledge base sync |
419
+ | `AGENT_KNOWLEDGE_AUTO_DISTILL` | — | Enable auto-distillation of sessions (true/false) |
420
+ | `AGENT_KNOWLEDGE_OPENAI_API_KEY` / `OPENAI_API_KEY` | — | API key for OpenAI embeddings |
421
+ | `AGENT_KNOWLEDGE_ANTHROPIC_API_KEY` / `ANTHROPIC_API_KEY` | — | API key for Claude/Voyage embeddings |
422
+ | `AGENT_KNOWLEDGE_GEMINI_API_KEY` / `GEMINI_API_KEY` | — | API key for Gemini embeddings |
484
423
 
485
424
  Set in your shell profile or pass via MCP config:
486
425
 
@@ -621,7 +560,7 @@ If your session data is in a non-standard location, use `AGENT_KNOWLEDGE_EXTRA_S
621
560
  | -------------------- | ----------- | -------------------- | ------------- | ---------- | ------------ | -------------- | -------------- |
622
561
  | MCP stdio transport | Yes | Yes | Yes | Yes | Yes | -- | Yes |
623
562
  | Session reading | Yes (JSONL) | Yes (JSONL) | Yes (SQLite) | Yes (JSON) | Yes (JSON) | Yes (MD/JSONL) | -- |
624
- | Lifecycle hooks | Yes (JSON) | No | Yes (plugins) | No | No | -- | No |
563
+ | Session lifecycle | Yes (mod) | No | Yes (plugins) | No | No | -- | No |
625
564
  | Session auto-distill | Yes | Yes | Yes | Yes | Yes | Yes | -- |
626
565
  | System prompt file | CLAUDE.md | .cursor/rules/\*.mdc | AGENTS.md | -- | -- | -- | .windsurfrules |
627
566
  | REST API fallback | Yes | Yes | Yes | Yes | Yes | Yes | Yes |