pi-knowledge 0.4.1 → 0.4.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.
Files changed (55) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/README.md +29 -8
  3. package/dist/index.d.ts +38 -0
  4. package/dist/index.js +435 -0
  5. package/dist/src/diagnostics/health.d.ts +19 -0
  6. package/dist/src/diagnostics/health.js +110 -0
  7. package/dist/src/embedding/provider.d.ts +5 -0
  8. package/dist/src/embedding/provider.js +99 -0
  9. package/dist/src/embedding/vectors.d.ts +15 -0
  10. package/dist/src/embedding/vectors.js +111 -0
  11. package/dist/src/engine.d.ts +90 -0
  12. package/dist/src/engine.js +1370 -0
  13. package/dist/src/indexer/chunker.d.ts +53 -0
  14. package/dist/src/indexer/chunker.js +498 -0
  15. package/dist/src/indexer/chunkers/code-ast.d.ts +3 -0
  16. package/dist/src/indexer/chunkers/code-ast.js +179 -0
  17. package/dist/src/model-worker-client.d.ts +10 -0
  18. package/dist/src/model-worker-client.js +138 -0
  19. package/dist/src/model-worker.d.ts +1 -0
  20. package/dist/src/model-worker.js +61 -0
  21. package/dist/src/search/bm25.d.ts +8 -0
  22. package/dist/src/search/bm25.js +38 -0
  23. package/dist/src/search/fusion.d.ts +19 -0
  24. package/dist/src/search/fusion.js +34 -0
  25. package/dist/src/search/query.d.ts +5 -0
  26. package/dist/src/search/query.js +57 -0
  27. package/dist/src/search/ranking.d.ts +27 -0
  28. package/dist/src/search/ranking.js +180 -0
  29. package/dist/src/search/reranker.d.ts +10 -0
  30. package/dist/src/search/reranker.js +66 -0
  31. package/dist/src/search/vector.d.ts +14 -0
  32. package/dist/src/search/vector.js +58 -0
  33. package/dist/src/storage/sqlite.d.ts +99 -0
  34. package/dist/src/storage/sqlite.js +330 -0
  35. package/dist/src/watcher/file-watcher.d.ts +4 -0
  36. package/dist/src/watcher/file-watcher.js +108 -0
  37. package/extension.js +9 -0
  38. package/package.json +20 -6
  39. package/index.ts +0 -500
  40. package/src/diagnostics/health.ts +0 -145
  41. package/src/embedding/provider.ts +0 -106
  42. package/src/embedding/vectors.ts +0 -119
  43. package/src/engine.ts +0 -1592
  44. package/src/indexer/chunker.ts +0 -612
  45. package/src/indexer/chunkers/code-ast.ts +0 -209
  46. package/src/model-worker-client.ts +0 -146
  47. package/src/model-worker.ts +0 -88
  48. package/src/search/bm25.ts +0 -55
  49. package/src/search/fusion.ts +0 -48
  50. package/src/search/query.ts +0 -59
  51. package/src/search/ranking.ts +0 -201
  52. package/src/search/reranker.ts +0 -74
  53. package/src/search/vector.ts +0 -81
  54. package/src/storage/sqlite.ts +0 -489
  55. package/src/watcher/file-watcher.ts +0 -116
package/CHANGELOG.md CHANGED
@@ -1,5 +1,23 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.4.3] - 2026-06-23
4
+
5
+ ### Fixed
6
+ - Added a packaged `extension.js` entry shim that loads built `dist/` output when available and falls back to source during local development.
7
+ - Fixed packaged model-worker startup so built JavaScript loads `dist/src/model-worker.js` without TypeScript strip flags while source development still uses `model-worker.ts`.
8
+ - Added OMP-aware knowledge storage path resolution with explicit `PI_KNOWLEDGE_DIR` / `OMP_KNOWLEDGE_DIR` overrides and legacy Pi knowledge-dir preservation for the default home OMP root.
9
+ - Fixed strict TypeScript build issues in the extension entry, engine indexing path, AST chunker, and model worker.
10
+
11
+ ### Changed
12
+ - Added a real `typecheck` release gate and made `prepack` run typecheck plus build before npm packaging.
13
+ - Updated contributor and architecture docs for the packaged `extension.js` entry, `dist/` package contents, and release validation flow.
14
+
15
+ ## [0.4.2] - 2026-06-18
16
+
17
+ ### Changed
18
+ - Added the `pi-package` npm keyword so the published package can be discovered by Pi's package catalog.
19
+ - Published the updated product positioning metadata introduced after v0.4.1, including local-first RAG, hybrid code/doc search, reranking, diagnostics, and large-project indexing keywords.
20
+
3
21
  ## [0.4.1] - 2026-06-16
4
22
 
5
23
  ### Fixed
package/README.md CHANGED
@@ -1,16 +1,33 @@
1
1
  # pi-knowledge
2
2
 
3
- **Vector knowledge base extension for Pi** — index any file, directory, or text into persistent, searchable knowledge bases with hybrid semantic + keyword search.
3
+ Local-first RAG knowledge base for Pi agents.
4
4
 
5
- Built as a native [Pi extension](https://pi.dev/docs/latest/extensions), deeply integrated with the agent lifecycle. Designed to match and exceed what kiro-cli's built-in knowledge tool offers, while being 100% local and provider-agnostic.
5
+ Index your codebase, docs, PDFs, URLs, and notes into persistent knowledge bases that Pi can search across sessions. `pi-knowledge` combines semantic embeddings, BM25 keyword search, code-aware chunking, reranking, diagnostics, and stable large-project indexing so agents can answer from your actual project knowledge instead of guessing.
6
6
 
7
- ## Why
7
+ Built as a native [Pi extension](https://pi.dev/docs/latest/extensions), deeply integrated with the agent lifecycle. Designed for local-first project memory, agentic code search, and retrieval-augmented development workflows.
8
8
 
9
- Coding agents forget everything outside their context window. `pi-knowledge` gives Pi persistent, searchable long-term memory over your documentation, codebases, specs, and notes — across sessions, across projects.
9
+ ## Why It Matters
10
+
11
+ Agents lose project context between sessions and cannot fit large repositories into one prompt. `pi-knowledge` gives Pi durable, searchable project memory:
12
+
13
+ - Search code and documentation by meaning, exact symbols, or both.
14
+ - Keep private source data local by default.
15
+ - Re-index changed files incrementally.
16
+ - Diagnose stale, stuck, or low-quality indexes.
17
+ - Handle large repositories with persisted progress instead of silent hangs.
10
18
 
11
19
  Unlike `pi-memory` (which manages the agent's own notes), `pi-knowledge` indexes **your existing files** and makes them semantically searchable by the agent.
12
20
 
13
- ## Features
21
+ ## Highlights
22
+
23
+ - **Local-first project memory**: stores indexes under `~/.pi/knowledge/`; no project files are modified.
24
+ - **Hybrid retrieval**: semantic vectors + BM25 keyword search + normalized weighted score fusion.
25
+ - **Code-aware indexing**: AST-aware chunking for TypeScript/JavaScript, Python, Go, Rust, and Java.
26
+ - **Better agent answers**: adaptive context windows, diversity reranking, optional cross-encoder reranking, and diagnostics.
27
+ - **Large-project stability**: persisted indexing progress, capped batches, streaming vector scans, and stuck-job detection.
28
+ - **Private by default**: local embeddings run without an API key.
29
+
30
+ ## Feature Comparison
14
31
 
15
32
  | Feature | pi-knowledge | kiro-cli knowledge | pi-memory |
16
33
  |---------|:---:|:---:|:---:|
@@ -33,9 +50,11 @@ Unlike `pi-memory` (which manages the agent's own notes), `pi-knowledge` indexes
33
50
  | Pi extension native | ✅ | N/A | ✅ |
34
51
  | Context injection per turn | ✅ | ❌ | ✅ |
35
52
  | Search result TUI rendering | ✅ | N/A | ❌ |
36
- | Full tool TUI rendering | planned | N/A | ❌ |
53
+ | Full tool TUI rendering | partial | N/A | ❌ |
37
54
  | RPC mode support | ✅ | N/A | N/A |
38
55
 
56
+ TUI rendering currently uses Pi's stable default tool rendering plus targeted result formatting. A fuller custom renderer is intentionally not enabled yet because custom renderers must be width-safe across terminal sizes and Pi TUI modes.
57
+
39
58
  ## Research-Backed Retrieval
40
59
 
41
60
  `pi-knowledge` turns retrieval research into product behavior that agents can actually use:
@@ -157,12 +176,14 @@ Before publishing, update `package.json`, `package-lock.json`, and `CHANGELOG.md
157
176
 
158
177
  ```bash
159
178
  npm run check
179
+ npm run typecheck
160
180
  npm test
181
+ npm run build
161
182
  npm run test:e2e
162
183
  PI_KNOWLEDGE_E2E_PDF=/path/to/file.pdf PI_KNOWLEDGE_E2E_DOCX=/path/to/file.docx npm run test:e2e
163
- node --experimental-strip-types -e "import('./index.ts')"
184
+ node -e "import('./extension.js')"
164
185
  npm pack --dry-run
165
- pi -e ./index.ts
186
+ pi -e ./extension.js
166
187
  git push origin main
167
188
  gh release create vX.Y.Z --title "vX.Y.Z" --notes-file /path/to/release-notes.md
168
189
  npm publish
@@ -0,0 +1,38 @@
1
+ type ToolResult = {
2
+ content: Array<{
3
+ type: "text";
4
+ text: string;
5
+ }>;
6
+ details?: unknown;
7
+ isError?: boolean;
8
+ };
9
+ type ToolUpdate = (result: ToolResult) => void;
10
+ type ToolDefinition = {
11
+ name: string;
12
+ label: string;
13
+ description: string;
14
+ promptSnippet?: string;
15
+ promptGuidelines?: string[];
16
+ parameters: Schema;
17
+ execute?: (toolCallId: string, params: Record<string, unknown>, signal: AbortSignal | undefined, onUpdate: ToolUpdate | undefined, ctx: unknown) => ToolResult | Promise<ToolResult>;
18
+ };
19
+ type ContextEvent = {
20
+ messages: Array<{
21
+ role: string;
22
+ content?: unknown;
23
+ }>;
24
+ };
25
+ type BeforeAgentStartEvent = {
26
+ systemPrompt: string;
27
+ };
28
+ type ExtensionAPI = {
29
+ on(event: "context", handler: (event: ContextEvent, ctx: unknown) => unknown): void;
30
+ on(event: "before_agent_start", handler: (event: BeforeAgentStartEvent, ctx: unknown) => unknown): void;
31
+ on(event: "session_start" | "session_shutdown", handler: (event: unknown, ctx: unknown) => unknown): void;
32
+ registerTool(tool: ToolDefinition): void;
33
+ };
34
+ type Schema = Record<string, unknown> & {
35
+ optional?: true;
36
+ };
37
+ export default function (pi: ExtensionAPI): void;
38
+ export {};
package/dist/index.js ADDED
@@ -0,0 +1,435 @@
1
+ import { KnowledgeEngine } from "./src/engine.js";
2
+ import { getDefaultKnowledgeDir } from "./src/storage/sqlite.js";
3
+ import { getActiveWatcherCount, startWatcher, stopAllWatchers } from "./src/watcher/file-watcher.js";
4
+ const Type = {
5
+ Object(properties) {
6
+ const required = Object.entries(properties)
7
+ .filter(([, schema]) => !schema.optional)
8
+ .map(([name]) => name);
9
+ const normalized = Object.fromEntries(Object.entries(properties).map(([name, schema]) => {
10
+ const { optional: _optional, ...rest } = schema;
11
+ return [name, rest];
12
+ }));
13
+ return { type: "object", properties: normalized, required, additionalProperties: false };
14
+ },
15
+ String(options = {}) {
16
+ return { type: "string", ...options };
17
+ },
18
+ Number(options = {}) {
19
+ return { type: "number", ...options };
20
+ },
21
+ Boolean(options = {}) {
22
+ return { type: "boolean", ...options };
23
+ },
24
+ Literal(value) {
25
+ return { const: value };
26
+ },
27
+ Union(items) {
28
+ return { anyOf: items };
29
+ },
30
+ Array(item) {
31
+ return { type: "array", items: item };
32
+ },
33
+ Optional(schema) {
34
+ return { ...schema, optional: true };
35
+ },
36
+ };
37
+ const engine = new KnowledgeEngine();
38
+ const WATCH_ENABLED = process.env.PI_KNOWLEDGE_WATCH === "true";
39
+ const AUTO_INJECT = process.env.PI_KNOWLEDGE_AUTO_INJECT === "true";
40
+ export default function (pi) {
41
+ pi.on("session_start", async () => {
42
+ await engine.initialize(getDefaultKnowledgeDir());
43
+ if (WATCH_ENABLED) {
44
+ for (const kb of engine.list()) {
45
+ if (kb.source_path && kb.source_type === "directory") {
46
+ startWatcher(kb.id, kb.source_path, (kbId) => {
47
+ engine.update(kbId).catch(() => { });
48
+ });
49
+ }
50
+ }
51
+ }
52
+ });
53
+ pi.on("session_shutdown", async () => {
54
+ stopAllWatchers();
55
+ await engine.dispose({ disposeModels: false });
56
+ });
57
+ // Auto-inject: search KB for relevant context before each LLM call (opt-in)
58
+ if (AUTO_INJECT) {
59
+ pi.on("context", async (event) => {
60
+ const kbs = engine.list();
61
+ if (kbs.length === 0)
62
+ return;
63
+ // Find last user message
64
+ const lastUser = [...event.messages].reverse().find((m) => m.role === "user");
65
+ if (!lastUser)
66
+ return;
67
+ const text = "content" in lastUser && typeof lastUser.content === "string" ? lastUser.content : "";
68
+ if (!text || text.length < 5)
69
+ return;
70
+ try {
71
+ const results = await engine.search(text, { mode: "fast", limit: 3 });
72
+ if (results.results.length === 0)
73
+ return;
74
+ const context = results.results.map((r) => `[${r.file_path}]: ${r.snippet}`).join("\n\n");
75
+ return {
76
+ messages: [{ role: "user", content: `[Knowledge context]\n${context}` }, ...event.messages],
77
+ };
78
+ }
79
+ catch {
80
+ /* silent fail */
81
+ }
82
+ });
83
+ }
84
+ pi.on("before_agent_start", (event) => {
85
+ const kbs = engine.list();
86
+ if (kbs.length === 0)
87
+ return undefined;
88
+ const desc = kbs.map((kb) => `"${kb.name}" (${kb.chunk_count} chunks, ${kb.file_count} files)`).join(", ");
89
+ const guidance = `Available knowledge bases: ${desc}. Use knowledge_search before answering domain questions.`;
90
+ return {
91
+ systemPrompt: `${event.systemPrompt}\n\n${guidance}`,
92
+ };
93
+ });
94
+ pi.registerTool({
95
+ name: "knowledge_plan",
96
+ label: "Knowledge Plan",
97
+ description: "Inspect an indexing source without writing a KB, showing scannable files, suggested exclusions, and technical skips",
98
+ promptSnippet: "Plan a knowledge-base indexing scope before calling knowledge_add",
99
+ promptGuidelines: [
100
+ "Use knowledge_plan before knowledge_add for broad directories, large repositories, or sources that may contain private or low-signal text",
101
+ "Show the user suggested exclusions and technical skips before asking whether to include risky or low-signal text",
102
+ "After the user confirms scope, call knowledge_add with matching include_suggested_text, include_paths, or exclude_paths",
103
+ "Do not use knowledge_plan as a substitute for knowledge_search; it only plans indexing scope",
104
+ ],
105
+ parameters: Type.Object({
106
+ source: Type.String({ description: "File path, directory path, URL, or inline text to inspect before indexing" }),
107
+ include_suggested_text: Type.Optional(Type.Boolean({
108
+ description: "Preview the scope if suggested-excluded text such as vendor/build/runtime/cache/secret-named text is included",
109
+ })),
110
+ include_paths: Type.Optional(Type.Array(Type.String({
111
+ description: "Relative paths under a directory source to include even when they match suggested-exclude patterns",
112
+ }))),
113
+ exclude_paths: Type.Optional(Type.Array(Type.String({ description: "Relative paths under a directory source to exclude from this plan" }))),
114
+ }),
115
+ execute(_id, params) {
116
+ const { source, include_suggested_text, include_paths, exclude_paths } = params;
117
+ const plan = engine.plan(source, {
118
+ include_suggested_text: include_suggested_text === true,
119
+ include_paths: Array.isArray(include_paths)
120
+ ? include_paths.filter((item) => typeof item === "string")
121
+ : undefined,
122
+ exclude_paths: Array.isArray(exclude_paths)
123
+ ? exclude_paths.filter((item) => typeof item === "string")
124
+ : undefined,
125
+ });
126
+ const samples = plan.skipped.samples
127
+ .map((sample) => `- ${sample.reason}: ${sample.path}${sample.size ? ` (${sample.size} bytes)` : ""}`)
128
+ .join("\n");
129
+ return {
130
+ content: [
131
+ {
132
+ type: "text",
133
+ text: [
134
+ plan.summary,
135
+ `Source type: ${plan.source_type}`,
136
+ `Skipped summary: ${JSON.stringify(plan.skipped.by_reason)}`,
137
+ samples ? `Skipped samples:\n${samples}` : "Skipped samples: none",
138
+ ].join("\n"),
139
+ },
140
+ ],
141
+ };
142
+ },
143
+ });
144
+ pi.registerTool({
145
+ name: "knowledge_add",
146
+ label: "Knowledge Add",
147
+ description: "Index files, directories, or text into a named knowledge base for semantic search",
148
+ promptSnippet: "Index files/dirs/text into a searchable knowledge base",
149
+ promptGuidelines: [
150
+ "Use knowledge_plan first for broad directories, large repositories, or sources that may contain private or low-signal text",
151
+ "Use knowledge_add when the user asks to index, remember, or learn from files or documentation",
152
+ "Prefer one knowledge_add call for the project root or relevant directory with include_paths/exclude_paths; do not call it once per file",
153
+ "If a knowledge base with the same name already exists, use knowledge_update or ask before replacing it",
154
+ "Index source, documentation, and ordinary configuration files that explain how the project works",
155
+ "Default directory indexing suggests excluding generated, vendor, browser runtime, obvious secret, and low-signal text artifacts; these are not permanent blocks",
156
+ "For ambiguous or risky text such as .env, private keys, certificates, credential-named files, settings.json, appsettings.json, cloud config, editor config, generated reports, lockfiles, or vendor text, explain the tradeoff and ask the user before including it",
157
+ "If the user confirms a suggested-excluded text file or directory should be indexed, call knowledge_add with include_suggested_text or a focused include_paths value so the tool follows the confirmed scope",
158
+ "Non-text, unsupported binary, oversized, unreadable, and inaccessible files remain technical skips even when the user wants broad indexing",
159
+ "Provide a descriptive name for this single knowledge base",
160
+ ],
161
+ parameters: Type.Object({
162
+ source: Type.String({ description: "File path, directory path, or inline text to index" }),
163
+ name: Type.String({ description: "Display name for this knowledge base" }),
164
+ include_suggested_text: Type.Optional(Type.Boolean({
165
+ description: "Include text files that are normally suggested for exclusion, such as vendor/build/runtime/cache/secret-named text, after user confirmation",
166
+ })),
167
+ include_paths: Type.Optional(Type.Array(Type.String({
168
+ description: "Relative paths under a directory source to include even when they match suggested-exclude patterns",
169
+ }))),
170
+ exclude_paths: Type.Optional(Type.Array(Type.String({ description: "Relative paths under a directory source to exclude from this KB" }))),
171
+ }),
172
+ async execute(_id, params, _signal, onUpdate) {
173
+ const { source, name, include_suggested_text, include_paths, exclude_paths } = params;
174
+ const { kb, chunkCount } = await engine.add(source, name, (msg) => {
175
+ onUpdate?.({ content: [{ type: "text", text: msg }] });
176
+ }, _signal, {
177
+ include_suggested_text: include_suggested_text === true,
178
+ include_paths: Array.isArray(include_paths)
179
+ ? include_paths.filter((item) => typeof item === "string")
180
+ : undefined,
181
+ exclude_paths: Array.isArray(exclude_paths)
182
+ ? exclude_paths.filter((item) => typeof item === "string")
183
+ : undefined,
184
+ });
185
+ // Start watcher for new directory KB
186
+ if (WATCH_ENABLED && kb.source_path && kb.source_type === "directory") {
187
+ startWatcher(kb.id, kb.source_path, (kbId) => {
188
+ engine.update(kbId).catch(() => { });
189
+ });
190
+ }
191
+ return {
192
+ content: [
193
+ {
194
+ type: "text",
195
+ text: `Indexed "${kb.name}": ${chunkCount} chunks from ${kb.file_count} files. KB ID: ${kb.id}`,
196
+ },
197
+ ],
198
+ };
199
+ },
200
+ });
201
+ pi.registerTool({
202
+ name: "knowledge_search",
203
+ label: "Knowledge Search",
204
+ description: "Search indexed knowledge bases using hybrid semantic + keyword search",
205
+ promptSnippet: "Search knowledge bases (hybrid BM25 + semantic + weighted score fusion)",
206
+ promptGuidelines: [
207
+ "Use knowledge_search to find relevant context before answering domain questions",
208
+ "Default to mode 'hybrid' for most project questions because it combines lexical anchors with semantic recall",
209
+ "Use mode 'fast' for exact symbols, filenames, commands, error codes, API names, config keys, or quoted strings",
210
+ "Use mode 'semantic' for broad conceptual questions when exact terms may differ from the indexed wording",
211
+ "Use mode 'adaptive' when the user needs surrounding implementation context, related nearby sections, or enough context to make a code change",
212
+ "Use mode 'deep' for high-stakes answers, ambiguous top results, or final verification where slower cross-encoder reranking is acceptable",
213
+ "If a search returns no results or obviously weak results, retry once with a different mode before concluding the KB lacks the answer",
214
+ "If top results are repetitive, retry with diversity 'strong' or mode 'adaptive' instead of increasing the limit first",
215
+ ],
216
+ parameters: Type.Object({
217
+ query: Type.String({ description: "Search query" }),
218
+ mode: Type.Optional(Type.Union([
219
+ Type.Literal("auto"),
220
+ Type.Literal("fast"),
221
+ Type.Literal("semantic"),
222
+ Type.Literal("hybrid"),
223
+ Type.Literal("deep"),
224
+ Type.Literal("adaptive"),
225
+ ])),
226
+ limit: Type.Optional(Type.Number({ description: "Max results (default 10)" })),
227
+ kb_id: Type.Optional(Type.String({ description: "Limit search to a specific KB by ID or exact name" })),
228
+ offset: Type.Optional(Type.Number({ description: "Pagination offset" })),
229
+ file_type: Type.Optional(Type.String({ description: "Filter by file type (e.g. typescript, markdown, python)" })),
230
+ diversity: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("balanced"), Type.Literal("strong")])),
231
+ diagnostics: Type.Optional(Type.Boolean({ description: "Include ranking diagnostics and mode/fallback details in the result" })),
232
+ }),
233
+ async execute(_id, params) {
234
+ const { query, mode, limit, kb_id, offset, file_type, diversity, diagnostics } = params;
235
+ const filters = file_type ? { file_type } : undefined;
236
+ const response = await engine.search(query, { mode, limit, kb_id, offset, filters, diversity });
237
+ if (response.results.length === 0) {
238
+ const details = [
239
+ "No results found.",
240
+ response.mode_used ? `Mode used: ${response.mode_used}` : "",
241
+ response.retry_modes?.length ? `Retried: ${response.retry_modes.join(", ")}` : "",
242
+ response.warnings?.length ? `Warnings: ${response.warnings.join(" | ")}` : "",
243
+ response.suggestions?.length ? `Suggestions: ${response.suggestions.join(" | ")}` : "",
244
+ ]
245
+ .filter(Boolean)
246
+ .join("\n");
247
+ return { content: [{ type: "text", text: details }] };
248
+ }
249
+ let output = `${response.total_count} results (showing ${response.results.length})`;
250
+ if (response.mode_used)
251
+ output += ` — mode: ${response.mode_used}`;
252
+ if (response.retry_modes?.length)
253
+ output += ` — retried: ${response.retry_modes.join(", ")}`;
254
+ output += ":\n\n";
255
+ if (response.warnings?.length) {
256
+ output = `Warnings:\n- ${response.warnings.join("\n- ")}\n\n${output}`;
257
+ }
258
+ output += response.results
259
+ .map((r, i) => {
260
+ const diag = diagnostics && r.ranking
261
+ ? `\nDiagnostics: base=${r.ranking.base_score.toFixed(3)}, adjusted=${r.ranking.adjusted_score.toFixed(3)}, coverage=${r.ranking.coverage.toFixed(2)}, path_boost=${r.ranking.path_boost.toFixed(2)}, source_boost=${r.ranking.source_boost.toFixed(2)}, test=${r.ranking.is_test}`
262
+ : "";
263
+ return `[${i + 1}] ${r.file_path} (${r.kb_name}, score: ${r.score.toFixed(3)})\n${r.snippet}${diag}`;
264
+ })
265
+ .join("\n\n");
266
+ return { content: [{ type: "text", text: output }] };
267
+ },
268
+ });
269
+ pi.registerTool({
270
+ name: "knowledge_update",
271
+ label: "Knowledge Update",
272
+ description: "Incrementally re-index a knowledge base (only re-embeds changed content)",
273
+ promptSnippet: "Incrementally update a knowledge base (only changed files re-embedded)",
274
+ parameters: Type.Object({
275
+ target: Type.String({ description: "KB name or ID to update" }),
276
+ }),
277
+ async execute(_id, params, _signal, onUpdate) {
278
+ const { added, removed, unchanged } = await engine.update(params.target, (msg) => {
279
+ onUpdate?.({ content: [{ type: "text", text: msg }] });
280
+ }, _signal);
281
+ return {
282
+ content: [{ type: "text", text: `Updated: +${added} added, -${removed} removed, ${unchanged} unchanged.` }],
283
+ };
284
+ },
285
+ });
286
+ pi.registerTool({
287
+ name: "knowledge_status",
288
+ label: "Knowledge Status",
289
+ description: "Show knowledge engine status with health diagnostics: staleness, orphans, and coverage",
290
+ parameters: Type.Object({}),
291
+ async execute() {
292
+ const kbs = engine.list();
293
+ const watchCount = getActiveWatcherCount();
294
+ const diagnostics = engine.diagnose();
295
+ const lines = [
296
+ `Storage: ${getDefaultKnowledgeDir()}`,
297
+ `Knowledge bases: ${kbs.length}`,
298
+ `Active watchers: ${watchCount}`,
299
+ "",
300
+ ];
301
+ for (const kb of kbs) {
302
+ const age = Math.round((Date.now() - kb.updated_at) / 60000);
303
+ const diag = diagnostics.find((d) => d.kb_id === kb.id);
304
+ lines.push(` "${kb.name}" — ${kb.status} — ${kb.chunk_count} chunks, ${kb.file_count} files — updated ${age}m ago`);
305
+ if (kb.source_path)
306
+ lines.push(` source: ${kb.source_path}`);
307
+ if (diag) {
308
+ if (diag.job) {
309
+ const jobAge = Math.round((Date.now() - diag.job.last_progress_at) / 1000);
310
+ const progress = [
311
+ `${diag.job.processed_files} files`,
312
+ `${diag.job.processed_chunks} chunks`,
313
+ diag.job.skipped_total > 0 ? `${diag.job.skipped_total} skipped` : "",
314
+ diag.job.added_chunks > 0 ? `+${diag.job.added_chunks}` : "",
315
+ diag.job.removed_chunks > 0 ? `-${diag.job.removed_chunks}` : "",
316
+ diag.job.unchanged_chunks > 0 ? `=${diag.job.unchanged_chunks}` : "",
317
+ ]
318
+ .filter(Boolean)
319
+ .join(", ");
320
+ lines.push(` job: ${diag.job.status}/${diag.job.phase} — ${progress || "no processed items yet"} — last progress ${jobAge}s ago`);
321
+ if (diag.job.message)
322
+ lines.push(` last: ${diag.job.message}`);
323
+ if (diag.job.error_message)
324
+ lines.push(` error: ${diag.job.error_message}`);
325
+ }
326
+ lines.push(` coverage: ${diag.coverage_percent}% (${diag.indexed_files}/${diag.total_source_files} files)`);
327
+ if (diag.stale_files.length > 0)
328
+ lines.push(` ⚠️ stale: ${diag.stale_files.length} files modified since last index`);
329
+ if (diag.orphan_files.length > 0)
330
+ lines.push(` ⚠️ orphans: ${diag.orphan_files.length} chunks reference deleted files`);
331
+ if (diag.stuck_indexing)
332
+ lines.push(` ⚠️ indexing appears stuck for ${Math.round(diag.last_progress_age_ms / 60000)}m; remove and rebuild if no pi process is actively indexing it`);
333
+ if (diag.skipped_files.total > 0)
334
+ lines.push(` skipped: ${diag.skipped_files.total} files (${Object.entries(diag.skipped_files.by_reason)
335
+ .filter(([, count]) => count > 0)
336
+ .map(([reason, count]) => `${reason}: ${count}`)
337
+ .join(", ")})`);
338
+ }
339
+ }
340
+ const totalStale = diagnostics.reduce((n, d) => n + d.stale_files.length, 0);
341
+ const totalOrphans = diagnostics.reduce((n, d) => n + d.orphan_files.length, 0);
342
+ const totalStuck = diagnostics.filter((d) => d.stuck_indexing).length;
343
+ if (totalStale === 0 && totalOrphans === 0 && totalStuck === 0 && kbs.length > 0)
344
+ lines.push("", "Health: ✓ all indexes up to date");
345
+ else if (totalStale > 0 || totalOrphans > 0 || totalStuck > 0)
346
+ lines.push("", `Health: ⚠️ ${totalStale} stale, ${totalOrphans} orphans, ${totalStuck} stuck indexing — run knowledge_update or rebuild affected KBs`);
347
+ return { content: [{ type: "text", text: lines.join("\n") }] };
348
+ },
349
+ });
350
+ pi.registerTool({
351
+ name: "knowledge_doctor",
352
+ label: "Knowledge Doctor",
353
+ description: "Diagnose knowledge base health, skipped files, stale indexes, stuck jobs, and recommended fixes",
354
+ promptSnippet: "Diagnose knowledge base health and recommended actions",
355
+ parameters: Type.Object({}),
356
+ async execute() {
357
+ const report = engine.doctor();
358
+ const lines = [`Health score: ${report.health_score}/100`, report.summary, ""];
359
+ if (report.issues.length === 0) {
360
+ lines.push("No issues found.");
361
+ }
362
+ else {
363
+ for (const issue of report.issues) {
364
+ const scope = issue.kb_name ? ` [${issue.kb_name}]` : "";
365
+ lines.push(`- ${issue.severity.toUpperCase()}${scope}: ${issue.message}`);
366
+ lines.push(` Action: ${issue.action}`);
367
+ }
368
+ }
369
+ return { content: [{ type: "text", text: lines.join("\n") }] };
370
+ },
371
+ });
372
+ pi.registerTool({
373
+ name: "knowledge_show",
374
+ label: "Knowledge Show",
375
+ description: "List all indexed knowledge bases",
376
+ parameters: Type.Object({}),
377
+ async execute() {
378
+ const kbs = engine.list();
379
+ if (kbs.length === 0)
380
+ return { content: [{ type: "text", text: "No knowledge bases." }] };
381
+ const lines = kbs.map((kb) => `• ${kb.name} — ${kb.chunk_count} chunks, ${kb.file_count} files (${kb.status})`);
382
+ return { content: [{ type: "text", text: lines.join("\n") }] };
383
+ },
384
+ });
385
+ pi.registerTool({
386
+ name: "knowledge_remove",
387
+ label: "Knowledge Remove",
388
+ description: "Remove a knowledge base by name or ID",
389
+ parameters: Type.Object({
390
+ target: Type.String({ description: "KB name or ID to remove" }),
391
+ }),
392
+ async execute(_id, params) {
393
+ const ok = engine.remove(params.target);
394
+ return { content: [{ type: "text", text: ok ? "Removed." : "Not found." }] };
395
+ },
396
+ });
397
+ pi.registerTool({
398
+ name: "knowledge_export",
399
+ label: "Knowledge Export",
400
+ description: "Export a knowledge base to a JSONL file (shareable, git-friendly)",
401
+ parameters: Type.Object({
402
+ target: Type.String({ description: "KB name or ID to export" }),
403
+ output: Type.String({ description: "Output file path (.jsonl)" }),
404
+ }),
405
+ async execute(_id, params) {
406
+ const { target, output } = params;
407
+ const count = await engine.exportKB(target, output);
408
+ return { content: [{ type: "text", text: `Exported ${count} chunks to ${output}` }] };
409
+ },
410
+ });
411
+ pi.registerTool({
412
+ name: "knowledge_import",
413
+ label: "Knowledge Import",
414
+ description: "Import a knowledge base from a JSONL file (re-embeds content)",
415
+ parameters: Type.Object({
416
+ input: Type.String({ description: "Input JSONL file path" }),
417
+ }),
418
+ async execute(_id, params, _signal, onUpdate) {
419
+ const { kb, chunkCount } = await engine.importKB(params.input, (msg) => {
420
+ onUpdate?.({ content: [{ type: "text", text: msg }] });
421
+ }, _signal);
422
+ return { content: [{ type: "text", text: `Imported "${kb.name}": ${chunkCount} chunks (re-embedded)` }] };
423
+ },
424
+ });
425
+ pi.registerTool({
426
+ name: "knowledge_clear",
427
+ label: "Knowledge Clear",
428
+ description: "Remove all knowledge bases",
429
+ parameters: Type.Object({}),
430
+ async execute() {
431
+ engine.clear();
432
+ return { content: [{ type: "text", text: "All knowledge bases cleared." }] };
433
+ },
434
+ });
435
+ }
@@ -0,0 +1,19 @@
1
+ import type Database from "better-sqlite3";
2
+ import { type ScanResult } from "../indexer/chunker.ts";
3
+ import { type IndexingJob, type KnowledgeBase } from "../storage/sqlite.ts";
4
+ export interface DiagnosticResult {
5
+ kb_id: string;
6
+ kb_name: string;
7
+ status: KnowledgeBase["status"];
8
+ status_age_ms: number;
9
+ last_progress_age_ms: number;
10
+ stuck_indexing: boolean;
11
+ stale_files: string[];
12
+ orphan_files: string[];
13
+ coverage_percent: number;
14
+ total_source_files: number;
15
+ indexed_files: number;
16
+ skipped_files: ScanResult["skipped"];
17
+ job?: IndexingJob;
18
+ }
19
+ export declare function diagnoseKB(db: Database.Database, kb: KnowledgeBase): DiagnosticResult;