Skip to content

Reference

Architecture

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

Overview


  ┌─────────────────────────────────────────────────────┐
  │                  AI Tool (Claude, Cursor…)           │
  │                                                     │
  │  session start: get_state()                         │
  │  session end:   update_state()                      │
  └──────────────┬──────────────────────────────────────┘
                 │ stdio (MCP)
        ┌────────┴──────────┐
        │                   │
   ┌────▼──────┐    ┌───────▼────────┐
   │egc-memory │    │  egc-guardian  │
   │           │    │                │
   │ get_state │    │validate_command│
   │update_state    │ validate_write │
   │store_decis│    │ reduce_context │
   │query_hist │    │orchestrate_task│
   └────┬──────┘    └────────────────┘
        │
   ┌────▼──────────────────────────┐
   │  ~/.egc/                      │
   │  ├── state/                   │
   │  │   └── project/branch.md    │
   │  ├── metrics/crusher.jsonl    │
   │  ├── encryption.key           │
   │  └── db.sqlite                │
   └───────────────────────────────┘

Layers

1

AI Tool Layer

Claude Code, Cursor, Codex, Gemini CLI, Antigravity CLI, OpenCode, Windsurf, Amp, VS Code Copilot, Zed, Kiro, Trae, CodeBuddy, Continue.dev, Junie, Goose, Amazon Q, OpenHands, Aider, and Warp: 20+ managed install targets. Each tool reads state at session start and writes at session end via the MCP protocol. The cognitive bootstrap injected by the installer writes this protocol into each tool's global instruction file.

2

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.

3

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.

4

egc-guardian

Validates commands and file writes before execution 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).

5

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.

6

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.