04 / System
System
Architecture, elements, and a worked pattern example at team scale.
The principles describe what a KMS does. The system page describes how it's built. This is the reference architecture I keep arriving back at, with the elements named and the flow explicit.
Architecture
Six stages, left to right:
- Sources — anywhere raw material enters: chat, voice notes, transcripts, integrations, file uploads, scheduled scrapers, agent runs.
- Ingestion — receives raw input, normalises shape, attaches provenance (when, where, who, which agent run).
- Bouncer — applies the quality gate from Bouncer-Promoter. Reject early, before anything touches the store.
- Knowledge store — typed entities, atomic facts, decisions, sources, concepts. Markdown-on-disk for personal; markdown + DB for team; tenant-isolated DB for app-scoped.
- Compilation passes — run on every store mutation: extract facts, link entities, propagate ripple, detect contradictions. See Automatic Compilation.
- Query layer — turns natural-language requests into retrievals over the store. Joins entities, follows links, assembles synthesised answers.
- Interface — the surface where the user shows up. Conversation (Claude in terminal), browse (Obsidian / web), in-product UI, agent-pulled context.
The flow is not strictly linear. Compilation passes run continuously. Query layer can write back to the store (e.g. recording a derived insight). The interface can trigger ingest (a conversation note becomes raw material).
Elements
The store holds a small fixed set of element types:
| Type | Purpose | Mutability |
|---|---|---|
| Entity | A real thing (person, company, project, source) | Append-mostly; structured fields update |
| Concept | A reusable idea or framework | Append-mostly; human-authored or compiled |
| Decision | A choice made, with rationale and alternatives | Immutable; supersession is explicit |
| Insight | A non-obvious learning, often cross-domain | Append-mostly; usually compiled |
| Source | An external reference (article, book, talk) | Immutable; notes attached separately |
| Derived | Compiled summary, digest, view | Regeneratable from sources |
Six types is a deliberate choice. Five would underfit; eight starts to drift. The constraint is the small-categories discipline applied at the schema level.
A worked example at team scale
A small team coordination system I've helped build sits at a tighter scope than a full team KMS, but uses the same pattern end-to-end. It's the cleanest worked example of the architecture above because everything is markdown, every element type is in use, and the compilation passes are visible.
Sources — Slack threads, meeting transcripts, agent session summaries, manual updates.
Knowledge store — typed folders for entities (people, projects, customers), knowledge (insights, concepts), and decisions. All markdown, all wikilinked.
Compilation — every session import triggers entity extraction, link-creation, and a contradiction sweep against existing knowledge.
Query layer — Claude Code sessions opened in the project directory, with a CLAUDE.md declaring the schema and rules.
Interface — Claude conversation for capture and synthesis; Obsidian for browse; periodic team digests for distribution.
The system is not a "team productivity tool." It is a KMS using markdown as the data layer, with team-OS workflows as the interface on top of that data. The right way to think about it is: the team OS is just one interface to the team's KMS.
What the architecture explicitly is not
- A graph database. Wikilinks give you a graph for free; no need for a separate store.
- A vector database. Embeddings help retrieval but are not the primary index. Wikilinks + filesystem are the primary index; embeddings are a fallback for fuzzy queries.
- A queue / workflow system. Compilation passes are functions, not jobs. They run on triggers (file write, hook, cron) but the system is not a workflow engine.
- A UI. The interface layer is interchangeable; the store is the durable artifact.
What's load-bearing
If you cut the architecture down to its smallest viable form:
- Markdown files in folders, with frontmatter and wikilinks.
- A CLAUDE.md that declares the routing table and element schemas.
- A small set of skills for ingest, compile, and query.
- Some way to trigger compilation passes (hooks, cron, manual).
That's it. Everything else is convenience.
Rev. 2026-04-18