Skip to content
Architecture

Reference

Architecture

Two MCP servers, local SQLite, plain 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.md   │
   │  └── db.sqlite        │
   └───────────────────────┘

Layers

1

AI Tool Layer

Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Kiro, Trae, CodeBuddy. 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. Persists decisions to SQLite. Returns structured project context to the AI.

4

egc-guardian

Validates commands and file writes before execution. Also provides context utilities (reduce_context, orchestrate_task). Runs transparently — the AI calls it as part of its normal operation.

5

Local Storage (~/.egc/)

State files are plain Markdown, one per project. SQLite database stores structured decision history for querying. Everything is local, human-readable, and version-control friendly.

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, plain Markdown state files, one install command. The branch legacy-runtime preserves the full historical architecture for anyone who wants to study the evolution.