feat: Knowledge Agents — queryable corpora from claude-mem (#1653)

* feat: add knowledge agent types, store, builder, and renderer

Phase 1 of Knowledge Agents feature. Introduces corpus compilation
pipeline that filters observations from the database into portable
corpus files stored at ~/.claude-mem/corpora/.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add corpus CRUD HTTP endpoints and wire into worker service

Phase 2 of Knowledge Agents. Adds CorpusRoutes with 5 endpoints
(build, list, get, delete, rebuild) and registers them during
worker background initialization alongside SearchRoutes.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add KnowledgeAgent with V1 SDK prime/query/reprime

Phase 3 of Knowledge Agents. Uses Agent SDK V1 query() with
resume and disallowedTools for Q&A-only knowledge sessions.
Auto-reprimes on session expiry. Adds prime, query, and reprime
HTTP endpoints to CorpusRoutes.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add MCP tools and skill for knowledge agents

Phase 4 of Knowledge Agents. Adds build_corpus, list_corpora,
prime_corpus, and query_corpus MCP tools delegating to worker
HTTP endpoints. Includes /knowledge-agent skill with workflow docs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: handle SDK process exit in KnowledgeAgent, add e2e test

The Agent SDK may throw after yielding all messages when the
Claude process exits with a non-zero code. Now tolerates this
if session_id/answer were already captured. Adds comprehensive
e2e test script (31 assertions) orchestrated via tmux-cli.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: use settings model ID instead of hardcoded model in KnowledgeAgent

Reads CLAUDE_MEM_MODEL from user settings via getModelId(), matching
the existing SDKAgent pattern. No more hardcoded model assumptions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: improve knowledge agents developer experience

Add public documentation page, rebuild/reprime MCP tools, and actionable
error messages. DX review scored knowledge agents 4/10 — core engineering
works (31/31 e2e) but the feature was invisible. This addresses
discoverability (docs, cross-links), API completeness (missing MCP tools),
and error quality (fix/example fields in error responses).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add quick start guide to knowledge agents page

Covers the three main use cases upfront: creating an agent, asking a
single question, and starting a fresh conversation with reprime. Includes
keeping-it-current section for rebuild + reprime workflow.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address code review issues — path traversal, session safety, prompt injection

- Block path traversal in CorpusStore with alphanumeric name validation and resolved path check
- Harden system prompt against instruction injection from untrusted corpus content
- Validate question field as non-empty string in query endpoint
- Only persist session_id after successful prime (not null on failure)
- Persist refreshed session_id after query execution
- Only auto-reprime on session resume errors, not all query failures
- Add fenced code block language tags to SKILL.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address remaining code review issues — e2e robustness, MCP validation, docs

- Harden e2e curl wrappers with connect-timeout, fallback to HTTP 000 on transport failure
- Use curl_post wrapper consistently for all long-running POST calls
- Add runtime name validation to all corpus MCP tool handlers
- Fix docs: soften hallucination guarantee to probabilistic claim
- Fix architecture diagram: add missing rebuild_corpus and reprime_corpus tools

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: enforce string[] type in safeParseJsonArray for corpus data integrity

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: add blank line before fenced code blocks in SKILL.md maintenance section

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

plugin/skills/knowledge-agent/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: knowledge-agent
+description: Build and query AI-powered knowledge bases from claude-mem observations. Use when users want to create focused "brains" from their observation history, ask questions about past work patterns, or compile expertise on specific topics.
+---
+
+# Knowledge Agent
+
+Build and query AI-powered knowledge bases from claude-mem observations.
+
+## What Are Knowledge Agents?
+
+Knowledge agents are filtered corpora of observations compiled into a conversational AI session. Build a corpus from your observation history, prime it (loads the knowledge into an AI session), then ask it questions conversationally.
+
+Think of them as custom "brains": "everything about hooks", "all decisions from the last month", "all bugfixes for the worker service".
+
+## Workflow
+
+### Step 1: Build a corpus
+
+```text
+build_corpus name="hooks-expertise" description="Everything about the hooks lifecycle" project="claude-mem" concepts="hooks" limit=500
+```
+
+Filter options:
+- `project` — filter by project name
+- `types` — comma-separated: decision, bugfix, feature, refactor, discovery, change
+- `concepts` — comma-separated concept tags
+- `files` — comma-separated file paths (prefix match)
+- `query` — semantic search query
+- `dateStart` / `dateEnd` — ISO date range
+- `limit` — max observations (default 500)
+
+### Step 2: Prime the corpus
+
+```text
+prime_corpus name="hooks-expertise"
+```
+
+This creates an AI session loaded with all the corpus knowledge. Takes a moment for large corpora.
+
+### Step 3: Query
+
+```text
+query_corpus name="hooks-expertise" question="What are the 5 lifecycle hooks and when does each fire?"
+```
+
+The knowledge agent answers from its corpus. Follow-up questions maintain context.
+
+### Step 4: List corpora
+
+```text
+list_corpora
+```
+
+Shows all corpora with stats and priming status.
+
+## Tips
+
+- **Focused corpora work best** — "hooks architecture" beats "everything ever"
+- **Prime once, query many times** — the session persists across queries
+- **Reprime for fresh context** — if the conversation drifts, reprime to reset
+- **Rebuild to update** — when new observations are added, rebuild then reprime
+
+## Maintenance
+
+### Rebuild a corpus (refresh with new observations)
+
+```text
+rebuild_corpus name="hooks-expertise"
+```
+
+After rebuilding, reprime to load the updated knowledge:
+
+### Reprime (fresh session)
+
+```text
+reprime_corpus name="hooks-expertise"
+```
+
+Clears prior Q&A context and reloads the corpus into a new session.

plugin/skills/mem-search/SKILL.md

@@ -173,3 +173,7 @@ Add custom tree-sitter grammars for languages not in the bundled set. Place `.cl
 - User grammars do NOT override bundled languages. If a language is already bundled, the entry is ignored.
 - The npm package must be installed in the project (`npm install tree-sitter-gleam`).
 - Config is cached per project root. Changes to `.claude-mem.json` take effect on next worker restart.
+
+## Knowledge Agents
+
+Want synthesized answers instead of raw records? Use `/knowledge-agent` to build a queryable corpus from your observation history. The knowledge agent reads all matching observations and answers questions conversationally.