Knowledge Flywheel

The Problem: Session Amnesia

The single biggest productivity drain with AI coding tools is not model capability — it's memory loss. Every new session starts from zero. The agent that spent 20 minutes understanding your authentication middleware yesterday has no memory of it today. The architectural decision you explained in session #47 must be re-explained in session #200. The bug pattern your team discovered last month is invisible to this morning's agent.

This is not a minor inconvenience. For codebases with years of accumulated architectural decisions, migration history, and domain knowledge, the cold-start penalty dominates session time. The agent spends 30-50% of each session re-discovering context that was already known in previous sessions. Across hundreds of sessions, this represents enormous waste — not just of compute, but of the developer's attention spent re-explaining the same things.

The industry's current answer is CLAUDE.md files: static documents that developers manually maintain with project conventions and rules. This is better than nothing but fundamentally limited. Static documents can't capture the evolving understanding that emerges from hundreds of debugging sessions, code reviews, and architectural discussions. They represent what the developer remembers to write down, not what the system actually learned.

Related Work

Retrieval-Augmented Generation (RAG) augments LLM prompts with retrieved documents. Standard RAG systems index a static corpus (documentation, code files) and retrieve relevant chunks at query time. The knowledge flywheel extends this in two directions: the corpus is dynamic (continuously growing from session interactions) and typed (architecture memories are weighted differently from debug patterns, which are weighted differently from policy decisions).

Reflexion (Shinn et al., 2023) implements self-reflection within a single episode, using verbal feedback to improve subsequent attempts. The knowledge flywheel generalizes this to cross-session reflection: patterns extracted from session N improve session N+100. Reflexion's insights are ephemeral; ours are persistent and accumulating.

Experience replay in reinforcement learning stores past transitions for training. The knowledge flywheel applies the same principle at the infrastructure level: past session experiences (tool call patterns, error resolutions, architectural discoveries) are stored and replayed as context for future sessions.

MemGPT (Packer et al., 2023) implements tiered memory management for LLMs, with a virtual context that pages information in and out. This focuses on managing a single long conversation's memory. We solve a different problem: aggregating knowledge across hundreds of independent sessions into a shared, searchable, growing knowledge base.

Episodic memory in cognitive architectures (SOAR, ACT-R) maintains records of specific experiences for analogical reasoning. The knowledge flywheel's conversation history + retrospective extraction serves a similar function, but optimized for the software engineering domain: experiences are indexed by code symbols, file paths, and architectural concepts rather than general semantic similarity alone.

Architecture: Four Knowledge Layers

Layer 1: Structured Knowledge Base

The primary store: 1,400+ entries across typed categories. Each entry has a title, body, category, tags, and an embedding vector. Categories include:

Search uses hybrid retrieval: FTS5 full-text search for keyword matching + embedding vector search for semantic similarity, combined via ranked fusion. This handles both exact queries (“UNIQUE constraint migration 0036”) and conceptual queries (“how does authentication work in this project?”).

Entries are connected via typed edges: prerequisite (A must be understood before B), supersedes (A replaces outdated B), relates-to (A and B concern the same concept). These edges enable graph traversal during retrieval: when an entry is retrieved, its related entries are included in the context, providing the full decision neighborhood.

Layer 2: Code Intelligence

Beacons — Named code landmarks that map human-readable names to file paths and symbols. “Show me the auth middleware” resolves to a specific file and function through beacon lookup, not codebase-wide search.

AST nodes — Every function, struct, enum, and trait in the codebase is tracked with its definition, file path, and embedding vector. The AST Sync worker maintains this index continuously, enabling semantic code search: “find functions that handle rate limiting” returns results based on meaning, not just naming conventions.

Layer 3: Conversation History

Every message from every session is persisted with: full text, role (human/assistant/tool), timestamp, conversation ID, summary embedding, and topic vectors. This enables:

• Conversation recall — “What did we discuss about the database migration last week?” retrieves the relevant conversation segments.
• Topic threading — Conversations about the same topic across different sessions are linked through topic vector similarity.
• Decision archaeology — “Why did we choose Redis over PostgreSQL for the task queue?” finds the conversation where this was discussed, even if no explicit knowledge entry was created.

Layer 4: Automated Extraction

The three layers above are populated automatically by background workers:

• Experience Harvester — Runs every 60 seconds, scanning new messages for extractable knowledge. Identifies patterns: bug descriptions, architectural explanations, convention statements, debugging insights. Extracts these into structured knowledge entries with category, tags, and relationships.
• Retrospective Worker — Runs at session end. Analyzes the complete session: tool call patterns, error rates, operation trajectories. Identifies repeated mistakes, inefficient sequences, and novel discoveries. Produces structured retrospective results that are persisted to the KB.
• AST Sync Worker — Monitors codebase changes and updates the AST node index. When a function is added, renamed, or deleted, the index reflects it within one worker cycle.
• Embedding Worker — Processes new content (knowledge entries, conversation messages, AST nodes) and generates embedding vectors for semantic search.

Context Pipeline: Budget-Constrained Assembly

When a new session starts, the Context Pipeline assembles a prompt from all four knowledge layers, constrained by token budget:

Priority order (highest to lowest):
  1. Slot environment    — current task, working directory, active files
  2. Skill context       — loaded skill definitions for the current project
  3. KB entries          — most relevant architecture/policy/debug entries
  4. Conversation history — recent relevant conversations
  5. Topology map        — service dependency graph
  6. CLAUDE.md           — static project conventions

Budget allocator:
  Total budget: N tokens (configurable)
  Each source gets a priority-weighted share
  Higher-priority sources are never truncated for lower-priority ones
  Within a source, entries are ranked by relevance score
  Truncation happens at entry boundaries, never mid-entry

The result: every session starts with the most relevant accumulated knowledge, automatically selected and budget-fitted. No manual curation. No stale CLAUDE.md files. The context reflects what the system actually knows, not what someone remembered to document.

The Flywheel Effect

The system exhibits a compounding learning dynamic:

1. Session N encounters a novel situation. The agent explores, makes mistakes, eventually solves the problem. The session is expensive in time and compute.
2. Experience Harvester extracts the key insight and persists it as a knowledge entry. The Retrospective Worker identifies the inefficient exploration path and records the efficient one.
3. Session N+1 encounters a related situation. The Context Pipeline includes the extracted knowledge. The agent skips the exploration phase and goes directly to the solution. The session is cheaper and faster.
4. Session N+100 has accumulated so many related entries that the agent handles the entire category of problems fluently, as if it had years of experience with this specific codebase.

This is the flywheel: each session makes every future session more effective. Knowledge accumulates monotonically (entries are added, not lost). Search quality improves as the corpus grows (more entries = better hybrid retrieval coverage). Cold starts become warm starts.

The analogy is institutional knowledge in an engineering organization. A senior engineer who has been on the team for 5 years carries context that no documentation captures: why certain decisions were made, what approaches were tried and rejected, which code paths are fragile, which conventions are enforced by culture rather than tooling. The knowledge flywheel gives AI agents access to this kind of accumulated wisdom.

Dual Storage Backend

The knowledge system is backed by a MissionDB trait that abstracts over PostgreSQL and SQLite. SQLite provides zero-setup local operation; PostgreSQL provides production-grade durability and concurrent access. The same daemon code runs against either backend, selected at startup.

The database schema (37 tables across 4 pillars) is generated via Forge codegen with a Generation Gap pattern: machine-generated CRUD in gen/ directories, hand-written complex queries alongside. This ensures the storage layer scales with the knowledge model without manual boilerplate maintenance.

Limitations

• Extraction quality — The Experience Harvester uses LLM-based extraction, which can produce low-quality entries from low-signal conversations. Quality filtering (confidence thresholds, duplicate detection) mitigates but doesn't eliminate this.
• Knowledge staleness — Code evolves faster than knowledge entries. An architecture memory from 3 months ago may describe a system that has since been refactored. The supersedes edge type and manual invalidation handle known obsolescence, but automated freshness detection is incomplete.
• Context window pressure — As the KB grows, the budget allocator must be increasingly selective. The risk is that important but low-scoring entries are excluded. The current mitigation is hierarchical summarization: detailed entries + condensed summaries at different budget levels.
• Single-project scope — The current implementation maintains one knowledge base per project. Cross-project knowledge sharing (e.g., a debugging pattern discovered in Service A that applies to Service B) is handled manually through shared KB categories, not automated.

The Thesis

The cold-start problem in AI coding tools is not a model problem. Larger models, better prompts, and longer context windows do not solve it — they make each individual session more capable but leave the cross-session knowledge gap intact. It is an infrastructure problem: the missing layer is persistent, searchable, automatically-populated storage that accumulates knowledge across sessions and injects it into new sessions at startup.

The knowledge flywheel demonstrates that this infrastructure is buildable with existing technology (hybrid FTS + vector search, background workers, budget-constrained context assembly) and produces compounding returns: each session enriches the knowledge base, which makes the next session cheaper, faster, and more accurate. The developer's accumulated context — previously locked inside human memory — becomes externalized, searchable, and automatically applied.

The implication for AI coding tool design: invest in the memory layer. A mediocre model with excellent memory outperforms a frontier model with no memory on real-world codebases, because real-world codebases are defined by their history, not their current snapshot.