Agent learns "Alice got promoted"
  → mutate_state({ op: "update", node_id: "alice", set: { role: "lead" } })
  → One row updated. Old value preserved in history. Event log chained.

Agent needs context about Alice
  → get_context({ entities: ["Alice"], max_tokens: 2000 })
  → Alice [person] (conf: 0.95)
     Lead engineer on platform team
     → works_on: Engram
     → knows: Bob
     ← manages: Charlie

                         ┌────────────────────────┐
                         │      Access Modes      │
                         │ MCP / CLI / REST API   │
                         └───────────┬────────────┘
                                     │
                         ┌───────────▼────────────┐
                         │     Service Layer      │
                         │  (src/service.ts)      │
                         └───────────┬────────────┘
                                     │
          ┌──────────────────────────┼──────────────────────────┐
          │                          │                          │
   ┌──────▼───────┐          ┌───────▼────────┐         ┌───────▼────────┐
   │   Engine     │          │   DB Layer     │         │  Embeddings    │
   │              │          │                │         │                │
   │ BFS graph    │          │ EventLog       │         │ OpenAI API     │
   │ Context bld  │          │ StateTree      │         │ Local (hash)   │
   │ LRU cache    │          │ VectorStore    │         │ Auto-embed on  │
   │ Maintenance  │          │ (namespaced)   │         │  mutation      │
   │ Conflict res │          │                │         │                │
   └──────┬───────┘          └───────┬────────┘         └────────────────┘
          │                          │
          │                  ┌───────▼────────────────────────────┐
          │                  │         SQLite (WAL mode)          │
          │                  ├────────────────────┬───────────────┤
          │                  │   engram.db        │ engram-vec.db │
          │                  │                    │               │
          │                  │ events             │ embeddings    │
          │                  │ nodes              │ vec_embeddings│
          │                  │ edges              │  (sqlite-vec) │
          │                  │ node_history       │               │
          │                  │ nodes_fts (FTS5)   │               │
          │                  │ _migrations        │               │
          └──────────────────┴────────────────────┴───────────────┘

src/
  config/                      Zod-validated config, env precedence
  db/                          SQLite layer (namespace-scoped)
    migrations/                SQL schema migrations (tracked)
    event-log.ts               Immutable log with per-namespace SHA-256 chain
    state-tree.ts              Node/edge CRUD, history, FTS5, merge
    vector-store.ts            sqlite-vec KNN
  engine/                      Pure algorithms
    graph-traversal.ts         BFS (≤ depth 5), cycle detection
    context-builder.ts         Token-budgeted serialization
    cache.ts                   In-memory node + LRU context
    maintenance.ts             Decay, archive, orphan GC
    conflict-resolver.ts       Duplicate detection
  embeddings/                  Provider abstraction
    openai.ts                  OpenAI embedding API
    local.ts                   Deterministic hash (testing)
  tools/                       7 MCP tool handlers
  cli/                         CLI commands + colorized formatters
  api/                         Hono REST app (auth, rate-limit, CORS)
  service.ts                   Shared layer for CLI + REST + MCP
  server.ts                    MCP server factory
  metrics.ts                   Prometheus registry (zero-dep)
  logger.ts                    Structured JSON logger
  rate-limit.ts                Token-bucket limiter
  port.ts                      JSON import/export
  utils.ts                     safeJsonParse
  index.ts                     Entry — auto-routes MCP (piped stdin) vs CLI
tests/
  unit/                        Per-module tests
  integration/                 End-to-end lifecycle
  fixtures/                    Test graph data
scripts/
  populate-test-data.ts        Seed data for manual E2E
  populate-ns.ts               Multi-namespace test data
  verify-advanced.ts           Advanced feature verification
  bench-fts.ts                 FTS5 benchmark

User: "Alice just moved to the platform team."

Agent flow:
1. get_context({ entities: ["Alice"] })
   → Engram returns Alice's current state + 1-hop neighbors

2. mutate_state({
     operations: [{ op: "update", node_id: "...", set: { team: "platform" } }]
   })
   → Atomic transaction:
     - Snapshot old state to node_history (rowid tracked)
     - UPDATE nodes SET ... WHERE id = ? AND namespace = ?
     - Append mutation event (per-namespace SHA-256 chain)
     - Link event_id back to both node and history row
     - Invalidate cache entries for this node
     - Fire onMutate callback → re-embed in background

3. Next conversation:
   get_context({ topic: "platform team" })
   → FTS5 finds Alice (name + summary + properties match)
   → Semantic search finds semantically related nodes
   → BFS expands 1 hop from anchors
   → Context builder serializes within token budget