Capstone: Build a Knowledge OS

What This Track Built

Nine lessons ago, this track started with a framing: a 24/7 agent platform where every correction evaporated at session end. The same errors recurred across dozens of sessions. Fixes had to be re-applied, rules had to be re-discovered, quality stayed flat regardless of how many sessions the agent had run.

The through-line of this track — every lesson contributed one load-bearing component to the system that solves that problem. This is the assembly lesson: not new concepts, but a precise account of how each component connects to the next, what fails at each seam if the connection is wrong, and what the assembled system looks like at each maturity level.

The architecture diagram maps every lesson to its component. Read it as a dependency chain: the canonical store is the substrate everything else reads and writes; the write path's quality constrains what the store contains; the store's quality constrains what recall can surface; recall's relevance constrains what the hydrator can give the agent; the hydrator's budget constrains what the agent can act on; the hygiene jobs and health monitor ensure the whole system stays accurate over time.

The Seven Components, Assembled

Canonical store (the why-agents-forget lesson). Postgres + pgvector, the canonical memories DDL. The schema columns are not arbitrary: memory_type enables type-filtered recall; namespace enables authority isolation; supersedes enables the audit chain; expires_at enables working memory TTLs; deleted_at enables soft deletion with auditability; embedding enables semantic search; confidence enables recall ranking. Every other component reads from or writes to this schema. Do not fork it.

Memory classifier (the memory-taxonomy lesson). Episodic memories record what happened — events, observed failures, timestamped facts. Semantic memories record what is true — architecture, tool behaviors, world facts. Procedural memories record what to do — rules, protocols, constraints. Working memories record current-task scratch — they carry expires_at and are not expected to outlast the task. Provenance (raw, derived, output) and confidence are first-class columns, not metadata. A derived memory with confidence 0.6 should be treated differently from a raw observation with confidence 0.95.

Dedupe-gated write path (the write-path lesson). The write path is the first quality gate. Embed the candidate heading and content. Search the store for near-matches within the same namespace. If cosine distance < 0.08 (similarity > 0.92), supersede — insert the new memory with supersedes pointing to the old row's memory_id, then soft-delete the old row. If no near-match, insert fresh. An unchecked write path is worse than no write path: it produces the duplicate spiral at automated scale.

Progressive recall (the recall lesson). Recall is rationed, not dumped. Search returns compact summaries — heading plus the first 80 characters of content. The agent scans the summaries and fetches full content by memory_id for the 1–2 that matter. Every recalled token competes with the task context. Progressive disclosure keeps the recall cost predictable and the task context uncluttered.

Namespace and authority (the namespaces lesson). Each memory belongs to a namespace: global (every agent), per-agent (one agent's private learning), or shared (a working group). Write authority is enforced structurally: an agent writes to its own namespace freely; the global namespace requires higher authority (the orchestrator, or high-confidence lessons). Recall is filtered with WHERE namespace IN (allowed_namespaces) at query time — not post-hoc. Cross-agent contamination is impossible by construction.

Hygiene jobs (the memory-hygiene lesson). Three hygiene operations. Expire working memories: set deleted_at on rows where expires_at < now and deleted_at IS NULL. Resolve supersede chains: walk chains longer than two hops and compact them (the original and all intermediate rows are soft-deleted; only the current version is live). Flag stale semantic memories: surface rows older than a configurable threshold for manual re-verification. A wrong memory is worse than no memory. Hygiene is the system's immune function.

Session hydrator (the session-assembly lesson). At session start, the hydrator receives the task description and a token budget. It runs a semantic search, builds compact index lines for the full result set, and fetches full content for the top-k most relevant entries. If the index lines exceed the token budget, it trims from the bottom (lowest relevance) until the budget fits. Hydrated context is background, not instructions — the agent draws on it, but it does not override the session's task prompt.

Compounding loop and health monitor (the compound-learning and memory-ops lessons). The compounding loop automates the retro: every session end triggers a structured extraction of candidate lessons, each of which passes through the dedupe-gated write path. The health monitor runs nightly: staleness distribution, duplicate rate, recall hit rate, and index drift. These are the receipts that prove the system is working — not just running.

What Breaks at the Seams

The most dangerous failure modes are not within components. They are between them.

Between write path and store. A write that bypasses the dedupe gate — a direct database insert, a secondary write path, a migration script — appends without checking. Every bypass is a leak in the gate. Enforce the gate at the application layer; do not rely on database constraints to catch duplicates.

Between store and hydrator. The hydrator runs a semantic search. If the store has stale embeddings (rows updated after the last embed job), those rows return the old vector and may score poorly against current queries — or score well against queries they no longer match. The embed job must run before the hydrator can be trusted.

Between recall and agent. The agent receives index lines and full-content memories. If the index line format is wrong — if the heading is truncated, if the preview omits the key fact — the agent may fetch the wrong memory for full content. Test the exact string the agent receives, not just the raw database row.

Between hygiene and recall. Soft-deleting a row sets deleted_at in the store — nothing else changes. The row stays in the table and in the HNSW index by design; no rebuild ever removes it. The only thing standing between a soft-deleted row and the agent's context is the WHERE deleted_at IS NULL filter on every recall query. One query path that omits the filter — a dashboard, a debug script, a secondary recall route — re-surfaces every retired memory.

The Maturity Model

Most agent systems are at L1 — a notes file that grows until it is too large to read. The jump from L1 to L2 is a sprint: stand up Postgres and pgvector, implement the canonical schema, build the write path and recall. L2 gives you semantic search, namespace isolation, and type-filtered recall.

L2 to L3 is the lifecycle investment: the dedupe gate, the hygiene jobs, the verify-before-trust pattern. Without L3, an L2 system accumulates duplicates and stale working memories at the write velocity of an active fleet. L3 is the minimum viable tier for a production agent system.

L3 to L4 is the automation investment: the retro pipeline, the escalation ladder, the compounding receipts. L4 is where the system starts to pay compound interest — the quality of every session is built on the accumulated corrections of every prior session, and the receipts prove it.

Building the Knowledge OS

The capstone challenge assembles the core: canonical store (in-memory for the exercise) + write path with authority check and dedupe gate + progressive recall with namespace filtering + hygiene sweep + budgeted session hydrator.

Work through it in dependency order: implement checkWriteAuthority first (the gate's prerequisite), then writeMemory (the gate itself), then searchMemories and fetchMemory (recall), then hygieneSweep (lifecycle), then hydrateSession last (it depends on recall).

At each stage, verify the handoff before proceeding. A writeMemory that inserts correctly but does not soft-delete the superseded row leaves ghost entries. A searchMemories that returns correct memory_id values but truncates the preview at the wrong length breaks the hydrator's index line format. Test the exact strings produced at each seam.

The mock functions — embedText, the in-memory MEMORY_STORE array — are the interfaces you replace with real implementations. OpenAI text-embedding-3-small for embeddings. Postgres + pgvector for the store. The canonical DDL from the first lesson in this track. The structure holds; the implementations swap in.

This is the architecture that powers a 24/7 agent platform where quality compounds instead of resetting. Every lesson you completed in this track was preparing you to build this. The components are real. Now you can assemble them yourself.