Skip to content

Architecture overview

Angelo is four MCP servers over stdio plus an install CLI, sharing two file-backed knowledge stores in the project repo.

┌─────────────┐     records to      ┌─────────────┐
│ coordinator │────────────────────▶│   memory    │
│ (task DAGs) │                     │ (.memory/)  │
└──────┬──────┘                     └─────────────┘
       │ drives extraction
       ▼
┌─────────────┐     writes to       ┌──────────────┐
│   stream    │────────────────────▶│ zettelkasten │
│ (ingestion) │                     │(.zettelkasten)│
└─────────────┘                     └──────────────┘

Design principles

  • Files are the source of truth. .memory/ and .zettelkasten/ are markdown
  • YAML, committed to git. Caches under .angelo/ are disposable.
  • Lean MCP surface. Cursor caps total tools across servers, so each server keeps a deliberately small, dispatch-style tool set.
  • Editable-install dev loop. The servers import from the workspace; see .cursor/rules/dev-environment.mdc.
  • Two dashboards, one per store. Each knowledge store has its own read-mostly web UI, launched from its own MCP server: the memory dashboard (console script angelo-dashboard, from the memory MCP's launch_dashboard) over .memory/, and the zettelkasten dashboard (console script angelo-zk-dashboard, from the zettelkasten MCP's launch_dashboard) over .zettelkasten/. They are separate processes and separate UIs — see Dashboard and Zettelkasten.

Decision record

Design choices recorded during development are promoted into browsable architecture decision records, generated from the memory graph. Mark an entry with publish: true in its frontmatter to publish it there.

Semantically related entries from the memory graph.