How Context Hydration Works

The Problem It Solves

Every AI agent session that starts from scratch wastes tokens. Reading the same files. Re-learning the same conventions. Re-discovering the same architectural decisions that the last agent already surfaced.

In a single-agent workflow, this is annoying but manageable. In a multi-agent system where 36 agents might run across a project in a single day, the waste compounds. The same README. The same architecture doc. The same CLAUDE.md. Read and tokenized dozens of times per day.

Context hydration is the system that eliminates this.

The Three Databases

CHAOS maintains three persistent context stores that agents read before starting work:

1. SQLite Context Store (per project)

The per-project context store is a SQLite database with FTS5 full-text search. It holds:

• Session logs and agent findings from previous runs
• File-level summaries indexed by path and content hash
• Discovered conventions and coding patterns
• Previous decisions with rationale

When an agent starts, the context system queries this store for entries relevant to the current task and injects them as pre-context. A security agent inherits findings from the last review agent. A test agent knows which files were recently changed.

2. Praxis Store (cross-project)

The Praxis Store is a shared context database that persists across all your projects. It accumulates:

• Best practices discovered through real agent work
• Framework patterns that recur across codebases
• Common error signatures and their fixes
• Language-specific conventions that apply universally

This is what makes CHAOS smarter over time. The more you use it, the more its cross-project knowledge base grows — and every new project benefits from what past projects taught it.

3. PostgreSQL Knowledge Graph

The knowledge graph is a structured semantic network with 268 entries and 89 relationship edges (seeded from real agent work). Nodes represent concepts — files, modules, patterns, decisions. Edges represent relationships — "depends on", "implements", "conflicts with".

The engine uses a PageRank-style algorithm to rank nodes by relevance to the current task, then injects the highest-ranked context entries before each agent session.

Retrieval: Hybrid FTS5 + Semantic RRF

Context retrieval uses a hybrid approach: FTS5 keyword search and semantic similarity, with Reciprocal Rank Fusion (RRF) to combine the ranked results.

This means context injection is not just keyword matching. "Fix the async session bug" might surface entries about session lifecycle, async patterns, recent database changes, and the last time a similar bug was fixed — all without exact keyword overlap.

The Token Math

A typical project context injection before an agent session costs roughly 800–2,000 tokens. That sounds expensive until you compare it to what it replaces: an agent reading 20+ files from scratch at 1,000–5,000 tokens each.

Net result: 50%+ token reduction per agent session, compounding across every agent in a pipeline.

What Gets Injected

Before each agent session, CHAOS injects:

1. Project metadata (name, stack, entry points, recent changes)
2. Relevant convention entries from the context store
3. Top-N knowledge graph nodes ranked for the current task
4. Summary of recent agent findings on related code paths

The agent starts with full situational awareness. No bootstrapping. No repeated file reads. Just work.

The Feedback Loop

After each session, agent findings flow back into the context store automatically. Every agent run makes the next run cheaper and better informed. This feedback loop is what separates CHAOS from a wrapper around a single LLM API call.