Aegis
Aegis: The Deterministic Context Compiler for AI Agents
As codebases grow, AI coding agents (like Cursor, Claude Code, and Codex) struggle to find the right architectural guidelines. Traditional RAG (Retrieval-Augmented Generation) suffers from a "semantic gap"—searching for feature keywords often fails to retrieve abstract architectural rules or domain models. This leads to poor code quality, hallucinated architectures, and massive token waste as agents endlessly grep through repositories.
Aegis solves this by shifting the paradigm from "probabilistic search" to **"deterministic compilation." **Instead of relying on vector embeddings, Aegis uses a Directed Acyclic Graph (DAG) backed by SQLite to map file paths and layers directly to your Markdown documentation. When an agent plans to edit a specific file, Aegis deterministically traverses the dependency graph and compiles the exact architectural context required for that specific task.
# 🛡️ Key Features
-
Deterministic Context Routing: Say goodbye to AI hallucinations. Aegis maps file paths (e.g., app/UseCases/**) to specific guidelines. Same input, same context. 100% reproducible.
-
Transitive Dependency Resolution: If usecase_guidelines.md depends on entity_guidelines.md, Aegis automatically resolves the edges and fetches both. It feeds the AI exactly what it needs, nothing more.
-
Dual Surface Architecture (Agent vs. Admin): Strict separation of concerns. The agent surface provides read-only context and allows agents to report missing rules. The admin surface is reserved for humans to review and approve knowledge base updates.
-
Human-in-the-Loop Knowledge Evolution: Agents can self-review and trigger aegis_observe if they lack context. Aegis proposes DAG updates based on these observations, but canonical knowledge is only updated upon human approval.
-
Massive Token Efficiency: By directly injecting the correct context, Aegis eliminates the hidden costs of agent exploration. In real-world benchmarks, it reduced token consumption by 12x and improved response times by 3.5x.
-
Optional Local SLM Expansion: Opt-in to the built-in node-llama-cpp engine (Qwen) to extract intent tags from the agent's plan, providing semantic context expansion without compromising the deterministic core.
Stop searching. Start compiling. Aegis acts as your automated Tech Lead, aggressively shielding your codebase's integrity by forcing AI agents to read the rules before they write the code.
Server Config
{
"mcpServers": {
"aegis": {
"command": "npx",
"args": [
"-y",
"@fuwasegu/aegis",
"--surface",
"agent"
]
},
"aegis-admin": {
"command": "npx",
"args": [
"-y",
"@fuwasegu/aegis",
"--surface",
"admin"
]
}
}
}