This document explains the design decisions behind the knowledge-ingestion-agent — what it is, why it exists, and how to think about it when adapting it to a new project.
When multiple Claude agents work on a project, they each start with no shared memory. Without a structured knowledge layer, every agent operates on incomplete information: guessing at business rules, duplicating research, and making decisions that contradict each other.
The knowledge-ingestion-agent solves this by acting as the single source of truth. It is the only agent that writes to .claude/knowledge/. All other agents read from it.
This separation of concerns is intentional:
- Implementation agents (engineers, architects, test writers) read knowledge and act on it
- The knowledge agent captures decisions and keeps the record accurate
The agent never guesses. Every claim is either drawn from a file it has read, or explicitly labeled as an assumption. This prevents hallucinated "facts" from polluting the knowledge base.
Session files at .claude/tasks/ are append-only. This preserves the full audit trail of what was researched and decided, which is essential when debugging agent decisions later.
Each knowledge file has a target token count. Smaller files load faster and stay focused. When a file approaches its budget, create a new file rather than expanding the old one.
The agent is the sole writer to .claude/knowledge/. Other agents may read these files, but they never write to them directly. This prevents inconsistency.
If new information contradicts existing knowledge, the agent stops and asks the user which takes precedence. It never silently overwrites a rule.
Any claim that isn't directly grounded in a read file is labeled as an assumption. This keeps the knowledge base honest and makes it clear what needs verification.
Before any significant implementation decision, an agent (or the user) can ask the knowledge agent to produce a context report. This report:
- Summarizes the current state of the relevant system
- Analyzes alignment with project constraints
- Lists confirmed facts and explicitly labeled assumptions
- Provides a recommendation with trade-off analysis
The report goes to .claude/plans/ and is appended to the session context. It is read-only input for the agent requesting it — the implementation agent reads the report and proceeds, but does not modify it.
When the user shares something the project needs to remember — a business rule, an architecture decision, a naming convention — the knowledge agent:
- Reads the relevant existing knowledge file
- Checks for conflicts
- Writes the new content in a structured format
- Updates the CLAUDE.md Documentation Map if a new file was created
- Confirms exactly what was stored
The key insight: if it wasn't ingested, it doesn't exist for other agents. The knowledge agent makes this explicit.
- It does not write application code (controllers, services, models, views, etc.)
- It does not run shell commands
- It does not push to git
- It does not make implementation decisions — it informs them
The agent is a researcher and archivist, not an implementer.
- Copy
agent/knowledge-ingestion-agent.mdinto your project's.claude/agents/directory - Replace all
{PLACEHOLDER}values with project-specific content - Define your project's non-negotiable constraints in the Project Constraints section
- Set up your initial knowledge files in
.claude/knowledge/(start withcritical-constraints.mdandtech-stack.md) - Add the knowledge base Documentation Map to your
CLAUDE.md
See references/customization-guide.md for a detailed walkthrough.
| Directory | Owner | Consumers |
|---|---|---|
.claude/knowledge/ |
knowledge-ingestion-agent | All agents |
.claude/plans/ |
knowledge-ingestion-agent | All agents, user |
.claude/tasks/ |
All agents (append-only) | All agents, user |
src/ / apps/ |
Implementation agents | — |