The agent knowledge architecture
Our posts keep referencing the same underlying system: agent memory, a curated wiki, an immutable source layer, loops, gates. This page is the full picture in one place, as a diagram and an annotated file tree. It is the representative shape of what we run, and it stays in sync with the posts that describe it.
Manifest last verified 2026-07-07 · the date moves only when the content moves
One system, four parts, one gate
Sources flow up into synthesis. The agent works from retrieval over the synthesis and a small always-loaded memory index. Everything the agent wants to change about the record goes through a human merge. Maintenance runs underneath, and it reports; it never edits.
The layers
Each layer has one job, and the boundaries are the point: sources are never rewritten, synthesis is never unsourced, memory is never unbounded, and the contract makes all three checkable.
raw/ · Immutable sources
Original documents, transcripts, research dossiers, and evidence. Never rewritten in meaning. When synthesis and source disagree, the source wins.
wiki/ · Curated synthesis
The compounding asset: interlinked pages for entities, concepts, engagements, milestones, and one summary per ingested source. Compiled once, kept current, searched many ways. Every load-bearing claim carries its provenance.
memory/ · The agent's typed memory
Small, curated, always-loaded index on top of a full catalog. Entries are typed (user, feedback, project, reference), and new lesson entries name the failure that created them. Demoted entries move to the archive; nothing is silently deleted.
the contract · Schema + conventions
Templates, frontmatter rules, and the operating conventions, written down. An undocumented convention is not a rule. This is what keeps a thousand pages consistent enough to trust.
The file structure
The whole record is markdown in one git repository. No proprietary store: files a person can read, diff, and correct, which is what makes the human gate real. Search indexes are derived from these files and rebuildable, never the source of truth. This is the representative structure; each line annotated with what it is for.
knowledge-base/one git repo; markdown all the way down├── CONTRACT.mdthe operating rules the agent works under├── index.mdhand-curated catalog of every page├── log.mdappend-only ledger: every change, dated├── raw/immutable source layer, never rewritten│ ├── sources/originals: documents, transcripts, research│ └── work/dated research dossiers with cited evidence├── wiki/the curated synthesis graph│ ├── _schema/page templates + what makes a page valid│ ├── entities/one page per person, org, or tool│ ├── concepts/durable ideas, methods, principles│ ├── topics/engagements and running threads│ ├── timeline/dated milestones, written the same day│ └── sources/one summary per ingested source└── memory/the typed memory store ├── MEMORY.mdalways-loaded curated index, kept small ├── archive.mdfull catalog; demoted, never deleted └── skill-memory/per-skill lessons, read at skill loadThe loops that keep it current
A knowledge base is not a project, it is an operation. These loops run on a cadence, and the discipline of the maintenance is where the value comes from.
Ingest
A source enters raw/, gets read fully, becomes a source summary plus updates to every synthesis page it touches, then the catalog and the ledger. Porting is ingesting; nothing enters silently.
Query
Questions are answered from retrieved pages with citations, and good answers are filed back as pages. Exploration compounds instead of vanishing into chat history.
Lint
A periodic health check: contradictions, stale claims, orphan pages, missing cross-references, schema drift. Findings are a worklist, never a deletion trigger.
Self-maintenance
Automated jobs re-index search, flag new orphans, and stage draft suggestions. Report-only by invariant: automation never edits a curated page, never deletes, never ships.
The intervention ledger
Every change the agent makes to its own system is logged with three fields: which surface changed (memory, a skill, the harness, tooling, or the curated knowledge itself), what changed, and what failure triggered it. A change that cannot explain itself is drift.
The gates that keep it honest
Everything above compounds only because of what is not allowed. These rules are the reason the store gets more correct over time instead of just more confident.
Agent proposes, human confirms
Curated knowledge changes ship by pull request a person merges. The agent never has silent write access to the record.
Exogenous verification
The producer never certifies its own work. Independent review traces claims to sources it opens itself; self-review is not review.
Provenance or reject
A load-bearing claim either carries its source or is explicitly marked as inference. Unsourced assertions do not enter curated pages, however right they sound.
Invalidate, do not delete
A contradicted claim is stamped superseded and kept. History stays intact; the search layer prefers the successor.
No fake freshness
Dates move only when content moves. This page shows the date its manifest was last verified, and that date follows the same rule.
Where the pieces are explained
Each part of this picture has a post or method that goes deep on it.
- Agent Memory Is Infrastructure, Not a Feature
- Does Better AI Agent Memory Come From Training or From Structure?
- Why Does Your AI Keep Making the Same Mistake? We Audited Ours to Find Out.
- AI Agents That Improve Themselves: What the Evidence Actually Supports
- How we run agent memory in production
- The Intervention Surface Framework
- The Agent Memory Disciplines
Want this running on your knowledge?
The architecture is public because the shape is not the hard part; the operating discipline is. If you want a system like this stood up on your business knowledge and maintained on a cadence, that is a conversation.