Reference

Architecture

Two MCP servers, local SQLite, encrypted Markdown state files, one install command. No cloud, no daemon, no config server.

Overview

AI coding tools read the memory protocol from tool instruction files. Where MCP is registered, tools connect over stdio to egc-memory and egc-guardian. egc-memory reads and writes encrypted branch-scoped Markdown state and a local SQLite decision and session store. — Tools use the installed memory protocol. Where registered, they also connect to the two local MCP servers over stdio. Open the full-size diagram (new tab) to zoom.

Layers

AI Tool Layer

Claude Code, Cursor, Codex, Antigravity CLI, OpenCode, Devin Desktop, Amp, VS Code Copilot, Zed, Kiro, Trae, CodeBuddy, Junie, Goose, OpenHands, Aider, Warp, Cline, and Qwen Code: 19 managed install targets. Each tool reads state at session start and writes at session end: through the MCP servers where they are registered, and through the propagated context files everywhere else. The cognitive bootstrap injected by the installer writes this protocol into each tool's global instruction file.

MCP Transport (stdio)

Both servers communicate over stdio. The tool spawns them as child processes. No ports, no network, no daemon. Starts in under 100ms.

egc-memory

Handles all memory operations. Reads and writes Markdown state files scoped per project and git branch. Persists decisions to SQLite with BM25 full-text search. Runs the session bus so parallel sessions announce presence, claim paths, and hand work off without collisions.

egc-guardian

Validates commands and file writes before execution, scans untrusted content for prompt-injection patterns (validate_content, advisory only) and provides context utilities (reduce_context, orchestrate_task, auto_learn). Enforcement is wired at the harness level too: prompt routing and pre-tool hooks run on every session, and the Token Crusher compresses shell output before it reaches the model, with savings tracked in a local ledger (egc gain).

Local Storage (~/.egc/)

State files are Markdown, one per project branch, encrypted at rest with AES-256-GCM and integrity-checked with HMAC-SHA256. SQLite stores structured decision history for querying, and the crusher ledger records every token saving. Everything is local and never leaves your machine.

Dashboard (localhost:7890)

Real-time mission control launched right after install: live tool calls, token usage, provider comparison, session replay, and export to CSV/JSON. IDE hook emitters stream events from Cursor, Kiro, OpenCode, and CodeBuddy.

Design notes

Architectural consolidation

Earlier versions of EGC explored distributed runtime concepts: FederationManager, ReplayEngine, cognitive orchestration layers, multi-provider dispatching. Those experiments were real explorations, not deception. They helped define what the project actually needed to be.

The current runtime reflects that consolidation. Two MCP servers, local SQLite, encrypted Markdown state files, one install command. The branch legacy-runtime preserves the full historical architecture for anyone who wants to study the evolution.