Knowledge Agents

Knowledge agents let you compile a slice of your claude-mem observation history into a queryable "brain" that answers questions conversationally. Instead of getting raw search results back, you get synthesized, grounded answers drawn from your actual project history -- decisions, discoveries, bugfixes, and features.

Quick Start

Three ways to use knowledge agents, from simplest to most powerful.

1. Create a Knowledge Agent

Use the /knowledge-agent skill or the MCP tools directly:

build_corpus name="hooks-expertise" query="hooks architecture" project="claude-mem" limit=200

This searches your observation history, collects matching records, and saves them as a corpus file. Then prime it — this loads the corpus into a Claude session's context window:

prime_corpus name="hooks-expertise"

Your knowledge agent is ready. The returned session_id is the agent — a Claude session with your history baked in.

2. Ask a Single Question

Once primed, ask any question and get a grounded answer:

query_corpus name="hooks-expertise" question="What are the 5 lifecycle hooks and when does each fire?"

The agent answers grounded in its corpus — responses are drawn from your actual project history, reducing hallucination and guessing. Each follow-up question builds on the prior conversation:

query_corpus name="hooks-expertise" question="Which hook handles context injection?"

3. Start a Fresh Conversation

If the conversation drifts, or you want to ask an unrelated question against the same corpus, reprime to start clean:

reprime_corpus name="hooks-expertise"

This creates a new session with the full corpus reloaded — like opening a fresh chat with the same "brain." All prior Q&A context is cleared, but the corpus knowledge remains. Use this when:

• The conversation went off-track and you want a clean slate
• You're switching topics within the same corpus
• You want to ask a question without prior answers biasing the response

Keeping It Current

When new observations are added to your project, rebuild the corpus to pull in the latest, then reprime:

rebuild_corpus name="hooks-expertise"
reprime_corpus name="hooks-expertise"

Rebuild re-runs the original search filters. Reprime loads the refreshed data into a new session.

The Workflow: Build, Prime, Query

BUILD  ──>  PRIME  ──>  QUERY

1. Build a Corpus

A corpus is a filtered collection of observations saved as a JSON file. Use search filters to select exactly the slice of history you want.

curl -X POST http://localhost:37777/api/corpus \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hooks-expertise",
    "query": "hooks architecture",
    "project": "claude-mem",
    "types": ["decision", "discovery"],
    "limit": 200
  }'

Under the hood, CorpusBuilder searches your observations, hydrates full records, parses structured fields (facts, concepts, files), calculates stats, and writes everything to ~/.claude-mem/corpora/hooks-expertise.corpus.json.

2. Prime the Knowledge Agent

Priming loads the entire corpus into a Claude session's context window.

curl -X POST http://localhost:37777/api/corpus/hooks-expertise/prime

The agent renders all observations into full-detail text and feeds them to the Claude Agent SDK. Claude reads the corpus and acknowledges the themes. The returned session_id is the knowledge agent -- a Claude session with your history baked in.

3. Query

Resume the primed session and ask questions.

curl -X POST http://localhost:37777/api/corpus/hooks-expertise/query \
  -H "Content-Type: application/json" \
  -d '{ "question": "What are the 5 lifecycle hooks?" }'

Each follow-up question adds to the conversation naturally. If the session expires, the agent auto-reprimes from the corpus file and retries.

Filter Options

Use these parameters when building a corpus to control which observations are included:

Architecture

                MCP Tools                    HTTP API
            (mcp-server.ts)            (worker on :37777)
                  |                          |
   build_corpus ──┤                          |
   list_corpora ──┤                          |
   prime_corpus ──┤── callWorkerAPIPost() ──>|
   query_corpus ──┤                          |
rebuild_corpus ──┤                          |
reprime_corpus ──┘                          |
                                             v
                                       CorpusRoutes
                                       (8 endpoints)
                                        /    |    \
                              CorpusBuilder  |  KnowledgeAgent
                                  |          |       |
                        SearchOrchestrator   |   Agent SDK V1
                        SessionStore         |   query() + resume
                                             |
                                        CorpusStore
                                    (~/.claude-mem/corpora/)

Key insight: The Agent SDK's resume option lets you prime a session once (upload the corpus), save the session_id, and resume it for every future question. The corpus stays in context permanently -- no re-uploading, no prompt caching tricks. The 1M token context window makes this viable: 2,000 observations at ~300 tokens each fits comfortably.

When to Use /knowledge-agent vs /mem-search

Rule of thumb: Use /mem-search when you need to find something specific. Use /knowledge-agent when you want to understand something broadly.

API Reference

Edge Cases

• Session expiry: If resume fails, the agent auto-reprimes from the corpus file and retries
• SDK process exit: If the Claude process exits after yielding all messages, the agent treats it as success when the session_id or answer was already captured
• Empty corpus: A corpus with 0 observations is valid (just empty)
• Model from settings: Reads CLAUDE_MEM_MODEL from user settings -- no hardcoded model IDs

Next Steps

• Memory Search - The 3-layer search workflow for finding specific observations
• Progressive Disclosure - Philosophy behind token-efficient retrieval
• Architecture Overview - System components