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.
- package/CHANGELOG.md +59 -0
- package/README.md +35 -32
- package/dist/embeddings/local.d.ts.map +1 -1
- package/dist/embeddings/local.js +3 -1
- package/dist/embeddings/local.js.map +1 -1
- package/dist/events.d.ts +6 -0
- package/dist/events.d.ts.map +1 -1
- package/dist/events.js +10 -2
- package/dist/events.js.map +1 -1
- package/dist/index.js +12 -0
- package/dist/index.js.map +1 -1
- package/dist/knowledge/analyze.d.ts.map +1 -1
- package/dist/knowledge/analyze.js +18 -11
- package/dist/knowledge/analyze.js.map +1 -1
- package/dist/knowledge/distill.d.ts.map +1 -1
- package/dist/knowledge/distill.js +28 -16
- package/dist/knowledge/distill.js.map +1 -1
- package/dist/knowledge/git.d.ts +3 -4
- package/dist/knowledge/git.d.ts.map +1 -1
- package/dist/knowledge/git.js +60 -46
- package/dist/knowledge/git.js.map +1 -1
- package/dist/knowledge/graph.d.ts +2 -0
- package/dist/knowledge/graph.d.ts.map +1 -1
- package/dist/knowledge/graph.js +8 -0
- package/dist/knowledge/graph.js.map +1 -1
- package/dist/knowledge/ingest-freshness.d.ts +22 -0
- package/dist/knowledge/ingest-freshness.d.ts.map +1 -0
- package/dist/knowledge/ingest-freshness.js +93 -0
- package/dist/knowledge/ingest-freshness.js.map +1 -0
- package/dist/knowledge/remove.d.ts +11 -0
- package/dist/knowledge/remove.d.ts.map +1 -0
- package/dist/knowledge/remove.js +24 -0
- package/dist/knowledge/remove.js.map +1 -0
- package/dist/knowledge/search.d.ts +74 -8
- package/dist/knowledge/search.d.ts.map +1 -1
- package/dist/knowledge/search.js +321 -40
- package/dist/knowledge/search.js.map +1 -1
- package/dist/knowledge/similar.d.ts +7 -0
- package/dist/knowledge/similar.d.ts.map +1 -0
- package/dist/knowledge/similar.js +51 -0
- package/dist/knowledge/similar.js.map +1 -0
- package/dist/knowledge/store.d.ts +17 -0
- package/dist/knowledge/store.d.ts.map +1 -1
- package/dist/knowledge/store.js +117 -79
- package/dist/knowledge/store.js.map +1 -1
- package/dist/rest-server.d.ts +12 -2
- package/dist/rest-server.d.ts.map +1 -1
- package/dist/rest-server.js +75 -10
- package/dist/rest-server.js.map +1 -1
- package/dist/search/bm25.d.ts +8 -0
- package/dist/search/bm25.d.ts.map +1 -1
- package/dist/search/bm25.js +32 -20
- package/dist/search/bm25.js.map +1 -1
- package/dist/search/excerpt.d.ts +1 -1
- package/dist/search/excerpt.d.ts.map +1 -1
- package/dist/search/excerpt.js +19 -1
- package/dist/search/excerpt.js.map +1 -1
- package/dist/search/lexicon.d.ts +37 -0
- package/dist/search/lexicon.d.ts.map +1 -0
- package/dist/search/lexicon.js +83 -0
- package/dist/search/lexicon.js.map +1 -0
- package/dist/search/mmr.d.ts +9 -3
- package/dist/search/mmr.d.ts.map +1 -1
- package/dist/search/mmr.js +21 -7
- package/dist/search/mmr.js.map +1 -1
- package/dist/search/types.d.ts +2 -0
- package/dist/search/types.d.ts.map +1 -1
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +0 -5
- package/dist/server.js.map +1 -1
- package/dist/sessions/human.d.ts +12 -0
- package/dist/sessions/human.d.ts.map +1 -0
- package/dist/sessions/human.js +52 -0
- package/dist/sessions/human.js.map +1 -0
- package/dist/sessions/parser.d.ts +39 -0
- package/dist/sessions/parser.d.ts.map +1 -1
- package/dist/sessions/parser.js +142 -18
- package/dist/sessions/parser.js.map +1 -1
- package/dist/sessions/search.d.ts +2 -0
- package/dist/sessions/search.d.ts.map +1 -1
- package/dist/sessions/search.js +147 -67
- package/dist/sessions/search.js.map +1 -1
- package/dist/sessions/snapshot.d.ts +19 -0
- package/dist/sessions/snapshot.d.ts.map +1 -0
- package/dist/sessions/snapshot.js +118 -0
- package/dist/sessions/snapshot.js.map +1 -0
- package/dist/sessions/summary.d.ts +24 -5
- package/dist/sessions/summary.d.ts.map +1 -1
- package/dist/sessions/summary.js +106 -145
- package/dist/sessions/summary.js.map +1 -1
- package/dist/slice.d.ts +5 -0
- package/dist/slice.d.ts.map +1 -0
- package/dist/slice.js +28 -0
- package/dist/slice.js.map +1 -0
- package/dist/text.d.ts +9 -0
- package/dist/text.d.ts.map +1 -0
- package/dist/text.js +16 -0
- package/dist/text.js.map +1 -0
- package/dist/tool-handlers.d.ts.map +1 -1
- package/dist/tool-handlers.js +6 -10
- package/dist/tool-handlers.js.map +1 -1
- package/dist/transport/rest.d.ts.map +1 -1
- package/dist/transport/rest.js +152 -35
- package/dist/transport/rest.js.map +1 -1
- package/dist/vectorstore/store.d.ts +9 -0
- package/dist/vectorstore/store.d.ts.map +1 -1
- package/dist/vectorstore/store.js +23 -0
- package/dist/vectorstore/store.js.map +1 -1
- package/dist/wakeup.d.ts +5 -0
- package/dist/wakeup.d.ts.map +1 -1
- package/dist/wakeup.js +10 -1
- package/dist/wakeup.js.map +1 -1
- package/docs/ARCHITECTURE.md +6 -9
- package/docs/HOOKS.md +138 -237
- package/docs/SETUP.md +61 -122
- package/docs/USER-MANUAL.md +45 -31
- package/package.json +6 -6
- package/plugin/skills/knowledge-ingest/scripts/validate.mjs +2 -2
- package/scripts/plugins/opencode/agent-knowledge.ts +32 -81
- package/scripts/setup.js +78 -145
- package/scripts/source-walk.d.mts +12 -0
- package/scripts/source-walk.mjs +94 -0
- package/scripts/tree-sitter-extract.mjs +10 -76
- package/scripts/hooks/first-prompt-inject.mjs +0 -242
- package/scripts/hooks/precompact-distill.mjs +0 -105
- package/scripts/hooks/precompact-flush.mjs +0 -192
- package/scripts/hooks/session-start-ingest.mjs +0 -238
- package/scripts/hooks/session-start.js +0 -211
- package/scripts/hooks/sessionend-distill.mjs +0 -198
package/docs/HOOKS.md
CHANGED
|
@@ -1,248 +1,149 @@
|
|
|
1
|
-
#
|
|
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
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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
|
-
|
|
78
|
-
|
|
8
|
+
```
|
|
9
|
+
claude plugin marketplace add keshrath/agent-knowledge
|
|
10
|
+
claude plugin install agent-knowledge@agent-knowledge
|
|
11
|
+
```
|
|
79
12
|
|
|
80
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
90
|
-
|
|
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
|
-
|
|
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
|
-
|
|
69
|
+
- **Release ritual** (`workflows/release.md`, score 3.42) — Bump, tag, push…
|
|
70
|
+
```
|
|
244
71
|
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
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
|
-
- [
|
|
16
|
-
- [Claude Code
|
|
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
|
-
####
|
|
64
|
+
#### The plugin (recommended)
|
|
65
65
|
|
|
66
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
195
|
-
|
|
196
|
-
### Claude Code Hooks
|
|
194
|
+
### Claude Code
|
|
197
195
|
|
|
198
|
-
|
|
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
|
-
|
|
227
|
+
The Claude Code lifecycle where opencode has an equivalent event:
|
|
289
228
|
|
|
290
|
-
| Claude Code
|
|
291
|
-
|
|
|
292
|
-
|
|
|
293
|
-
|
|
|
294
|
-
|
|
|
295
|
-
|
|
|
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
|
|
236
|
+
Not here (opencode has no equivalent surface):
|
|
298
237
|
|
|
299
|
-
-
|
|
300
|
-
-
|
|
301
|
-
- L0 identity auto-load (no
|
|
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
|
-
|
|
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` | `
|
|
253
|
+
| `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS` | `2` | Max rendered hits, clamped `[1, 2]`. |
|
|
315
254
|
|
|
316
|
-
Every
|
|
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
|
|
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
|
|
396
|
-
| ----------- | ---------------------------------------- |
|
|
397
|
-
| Claude Code |
|
|
398
|
-
| OpenCode | `~/.claude/skills/`, `~/.agents/skills/` |
|
|
399
|
-
| Cursor | `~/.claude/skills/`, `~/.agents/skills/` |
|
|
400
|
-
| Codex CLI | `~/.agents/skills/` |
|
|
401
|
-
| Gemini CLI | `~/.agents/skills/` |
|
|
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
|
|
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
|
-
|
|
|
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 |
|