DAG-based Deterministic Context Compiler for AI Coding Agents

日本語版 README | Technical Guide

Aegis is an MCP server that enforces architecture guidelines on AI coding agents. Instead of RAG, it uses a DAG of dependency edges to deterministically compile exactly which documents an agent needs for a given set of target files. No search. No ranking. Deterministic.

1. Add Aegis to your IDE's MCP config (see Installation)
2. Ask your AI agent: "Initialize Aegis for this project and deploy the adapter rules."
3. The agent runs aegis_init_detect → aegis_init_confirm → npx @fuwasegu/aegis deploy-adapters automatically

The database is stored at .aegis/aegis.db in the project root. The .aegis/ directory includes its own .gitignore — no manual configuration needed.

Aegis uses two MCP surfaces — both are required:

The agent surface alone cannot initialize a project or approve proposals. This separation ensures AI agents cannot modify architecture rules without human approval. (INV-6)

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "agent"]
    },
    "aegis-admin": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "admin"]
    }
  }
}

After initialization, deploy-adapters generates .cursor/rules/aegis-process.mdc — a Cursor rule that instructs the agent to consult Aegis before writing code and report violations afterward.

claude mcp add aegis -- npx -y @fuwasegu/aegis --surface agent
claude mcp add aegis-admin -- npx -y @fuwasegu/aegis --surface admin

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "agent"]
    },
    "aegis-admin": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "admin"]
    }
  }
}

After initialization, deploy-adapters appends an <!-- aegis:start --> section to CLAUDE.md (creates it if missing).

codex mcp add aegis -- npx -y @fuwasegu/aegis --surface agent
codex mcp add aegis-admin -- npx -y @fuwasegu/aegis --surface admin

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "agent"]
    },
    "aegis-admin": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "admin"]
    }
  }
}

After initialization, deploy-adapters appends an <!-- aegis:start --> section to AGENTS.md (creates it if missing).

Note: Codex MCP support depends on the CLI version. If MCP is not available, agents can still follow Aegis guidelines via the generated AGENTS.md instructions.

Using the admin surface, initialize Aegis with an empty knowledge base:

aegis_init_detect({ project_root: "/path/to/your/project", skip_template: true })
aegis_init_confirm({ preview_hash: "<hash from detect>" })

This creates an empty knowledge base. You'll populate it with architecture documents in the next step.

Then deploy adapter rules and Agent Skills for your AI coding tool via CLI:

npx @fuwasegu/aegis deploy-adapters
npx @fuwasegu/aegis deploy-adapters --targets cursor,codex  # specific adapters only

The agent surface provides tools for your AI coding agent. Recommended flow for expanded context (tag-driven documents): call aegis_get_known_tags once per session (cache tag_catalog_hash), then pass intent_tags into compile:

aegis_get_known_tags({})
aegis_compile_context({
  target_files: ["src/core/store/repository.ts"],
  plan: "Add a new query method for archived observations",
  intent_tags: ["<tags from known_tags>"]
})

Omit intent_tags only if you want the optional server-side SLM tagger (when --slm is enabled) to infer tags from plan instead (ADR-004). Pass intent_tags: [] to skip expanded context without SLM.

Base DAG only (skip expanded context; works the same with or without --slm because intent_tags: [] disables expanded and skips SLM tagging):

aegis_compile_context({
  target_files: ["src/core/store/repository.ts"],
  plan: "Add a new query method for archived observations",
  intent_tags: []
})

Returns architecture guidelines, patterns, and constraints relevant to the files being edited.

After initialization, populate the knowledge base by analyzing your codebase. Use aegis_import_doc on the admin surface to add architecture documents with edge_hints that connect them to file paths:

aegis_import_doc({
  file_path: "/absolute/path/to/docs/architecture-guide.md",
  doc_id: "architecture-guide",
  title: "Architecture Guide",
  kind: "guideline",
  tags: ["architecture"],
  edge_hints: [
    { source_type: "path", source_value: "src/domain/**", edge_type: "path_requires" }
  ]
})

Using file_path reads content directly from disk, avoiding truncation by LLM context windows. Each import returns proposal_ids — approve them to activate the documents.

To keep imported documents in sync with source files:

aegis_sync_docs()   # detects changes via content hash, creates update_doc proposals

Both aegis_import_doc and aegis_sync_docs require the admin surface. For a detailed step-by-step bulk import workflow, see the aegis-bulk-import skill (deployed via deploy-adapters).

When the agent notices a missing guideline or a correction:

aegis_observe({
  event_type: "compile_miss",
  related_compile_id: "<from compile_context>",
  related_snapshot_id: "<from compile_context>",
  payload: { target_files: ["..."], review_comment: "Missing error handling guideline" }
})

Observations are analyzed into proposals. Review and approve via admin surface:

aegis_list_proposals({ status: "pending" })
aegis_approve_proposal({ proposal_id: "<id>" })

Aegis supports sharing approved Canonical Knowledge across team members via Git-committed bundle artifacts. This eliminates the need for each developer to build the knowledge base from scratch.

After approving proposals, export the current Canonical state:

npx @fuwasegu/aegis share-export                # writes aegis-share/manifest.json + canonical.json
npx @fuwasegu/aegis share-export --out /path    # custom output directory

Then commit and push aegis-share/.

After pulling changes that include an updated aegis-share/:

npx @fuwasegu/aegis share-hydrate               # rebuild .aegis/aegis.db from aegis-share/
npx @fuwasegu/aegis share-hydrate --replace     # overwrite existing initialized DB
npx @fuwasegu/aegis share-hydrate --bundle-dir /path  # custom bundle directory

Warning: share-hydrate performs a whole-DB replacement. Local operational state (observations, proposals, compile log) is not preserved. This is by design — replica workspaces are consumers of shared knowledge, not authors.

Aegis automatically detects drift between your local DB and the shared bundle:

• npx @fuwasegu/aegis doctor — shows share state (in_sync, bundle_newer, local_ahead, diverged, unreadable_bundle); exits 1 for actionable states
• npx @fuwasegu/aegis stats — includes project_share in JSON output with full status details
• aegis_compile_context notices — agents receive actionable hints (e.g. "Run share-hydrate to update") when the bundle is out of sync

The not_configured state (no aegis-share/ directory) is silent — no noise until sharing is set up.

                    Authoring Workspace                    Replica Workspace
                    ───────────────────                    ─────────────────
  approve proposals ──► share-export ──► git push ──► git pull ──► share-hydrate
                                  aegis-share/ committed

1. Author works on the knowledge base (import docs, approve proposals, sync)
2. Author runs share-export and commits aegis-share/
3. Team runs git pull then share-hydrate --replace
4. compile_context on the replica now returns the same guidelines as the author

In addition to the DB-native workflow above (observe → propose → approve), Aegis supports a source-native collaborative authoring mode. Team members edit human-readable source files in aegis-share/source/, review changes via pull requests, and materialize them into the database.

Key rule: compile_context always reads from the database, not from source files directly. Source files are the authoring format; the DB is the runtime format.

Both lanes coexist. Use whichever fits the situation — or both.

aegis-share/
├── manifest.json              # Distribution bundle manifest (ADR-017)
├── canonical.json             # Distribution bundle data (ADR-017)
└── source/                    # Collaborative authoring source (ADR-018)
    ├── documents/
    │   └── <doc_id>.md        # Frontmatter + Markdown body
    ├── edges/
    │   ├── path-requires.json
    │   ├── layer-requires.json
    │   ├── command-requires.json
    │   └── doc-depends-on.json
    ├── layer-rules.json
    └── tag-mappings.json

# 1. Bootstrap: export current DB to source format (one-time setup)
npx @fuwasegu/aegis share-source-export

# 2. Edit source files (documents, edges, rules, mappings)
#    Create a branch, make changes, open a PR

# 3. Validate before committing
npx @fuwasegu/aegis share-format                 # Normalize formatting (deterministic, in-place)
npx @fuwasegu/aegis share-lint                   # Check for errors (after formatting)

# 4. After PR merge: apply source to DB
npx @fuwasegu/aegis share-materialize            # Applies changes + auto-approves
npx @fuwasegu/aegis share-materialize --dry-run  # Preview changes without applying

# 5. Export updated bundle for replicas
npx @fuwasegu/aegis share-export

Add share-lint to your CI pipeline to catch errors before merge:

npx @fuwasegu/aegis share-lint  # exits 1 on errors — suitable for CI checks

• Local overlays are not supported — all changes go through the shared source
• share-materialize is a full apply (not incremental patch)

Aegis includes a built-in llama.cpp engine for optional SLM-based intent tagging. SLM is disabled by default — the deterministic DAG-based context works perfectly without it.

To enable, add --slm to the agent surface:

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "agent", "--slm", "--model", "qwen3.5-4b"]
    },
    "aegis-admin": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "admin"]
    }
  }
}

On first SLM-enabled startup, the selected model is downloaded to ~/.aegis/models/ (shared across all projects).

You can also pass a HuggingFace URI directly: --model hf:user/repo:file.gguf

Legacy: --ollama flag is available for Ollama-based inference if preferred. Using --ollama implicitly enables SLM.

npx @fuwasegu/aegis deploy-adapters                         # Deploy all adapters
npx @fuwasegu/aegis deploy-adapters --targets cursor,codex  # Deploy specific adapters
npx @fuwasegu/aegis deploy-adapters --project-root /path    # Specify project root
npx @fuwasegu/aegis deploy-adapters --db /path/to/aegis.db  # Use custom DB path
npx @fuwasegu/aegis maintenance                             # Process observations, sync, archive
npx @fuwasegu/aegis maintenance --dry-run                   # Report only (no writes)
npx @fuwasegu/aegis stats                                   # JSON health and usage data
npx @fuwasegu/aegis doctor                                  # Health check summary
npx @fuwasegu/aegis share-export                            # Export to aegis-share/
npx @fuwasegu/aegis share-hydrate --replace                 # Rebuild DB from bundle
npx @fuwasegu/aegis share-source-export                     # Export DB to aegis-share/source/
npx @fuwasegu/aegis share-lint                              # Validate shared source
npx @fuwasegu/aegis share-format                            # Normalize shared source
npx @fuwasegu/aegis share-materialize                       # Apply source to DB
npx @fuwasegu/aegis share-materialize --dry-run             # Preview changes
npx @fuwasegu/aegis --list-models                           # List available SLM models

Note: Version tracking is only updated on full deployments (without --targets). Partial deployments will not update the version record, so the "adapter templates may be outdated" notice will persist until a full deployment is run.

npm run build    # Compile TypeScript
npm test         # Run all tests (406+)
npm run test:watch

git clone https://github.com/fuwasegu/aegis.git
cd aegis
npm install && npm run build

┌─ MCP Layer (src/mcp/) ──────────────────┐
│ Tool registration, surface separation   │
└──────────────┬──────────────────────────┘
               │
┌─ Core Layer (src/core/) ────────────────┐
│ ContextCompiler, Repository, Init,      │
│ Automation (Analyzers), Tagging         │
└──────────────┬──────────────────────────┘
               │
┌─ Adapters (src/adapters/) ──────────────┐
│ Cursor, Claude rule generation          │
└──────────────┬──────────────────────────┘
               │
┌─ Expansion (src/expansion/) ────────────┐
│ llama.cpp engine, IntentTagger          │
└─────────────────────────────────────────┘

Dependencies flow downward. Core never imports from MCP, Adapters, or Expansion.

• Canonical Knowledge: Approved architecture documents + DAG edges
• Observation Layer: Agent-reported events (compile misses, corrections, PR merges)
• Proposed Layer: Automated proposals requiring human approval
• Snapshots: Immutable, content-addressable versions of Canonical Knowledge

ISC