Epic: Automatic long-term memory for OpenCode sessions via Graphiti knowledge graph

[geier]

Context

OpenCode has no long-term memory — every session starts from scratch. Knowledge about architectural decisions, coding patterns, error solutions, and project context is lost between sessions. This is especially painful across multiple machines where sessions happen in different environments but should contribute to the same knowledge base.

This epic implements automatic, background session ingestion into a centralized Graphiti temporal knowledge graph. Graphiti was chosen over alternatives (Mem0, LangMem, custom RAG) because:

• Temporal awareness: tracks how facts change over time ("switched from React to SolidJS in March")
• Hybrid retrieval: semantic search + BM25 keyword search + graph traversal
• Async ingestion: non-blocking background processing via queue
• Custom entity types: configurable for coding-specific knowledge (frameworks, patterns, error solutions)
• MCP server: native Model Context Protocol support — OpenCode connects directly

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Machine A  │     │  Machine B  │     │  Machine C  │
│  (OpenCode) │     │  (OpenCode) │     │  (OpenCode) │
└──────┬──┬───┘     └──────┬──┬───┘     └──────┬──┬───┘
       │  │                │  │                │  │
   MCP │  │ SSE        MCP │  │ SSE        MCP │  │ SSE
 (read)│  │(watch)  (read) │  │(watch)  (read) │  │(watch)
       │  │                │  │                │  │
       │  └────────┬───────┘  └────────┬───────┘  │
       │           │                   │           │
       │  ┌────────▼───────────────────▼────────┐  │
       │  │  Background Watcher(s)              │  │
       │  │  Detects session.status: busy→idle  │  │
       │  │  Fetches transcript via OpenCode API│  │
       │  │  Posts to Graphiti REST API         │  │
       │  └────────────────┬────────────────────┘  │
       │                   │                        │
       │        ┌──────────▼──────────┐            │
       └───────►│  Graphiti MCP Server│◄───────────┘
                │  (centralized)      │
                └──────────┬──────────┘
                           │
                ┌──────────▼──────────┐
                │  FalkorDB           │
                │  (graph database)   │
                └─────────────────────┘

Key design decisions:

• The AI only reads from memory (via MCP tools: search_nodes, search_memory_facts)
• The AI never writes to memory — a background watcher handles all ingestion automatically
• This ensures every session is captured, every time, without relying on AI behavior or prompt engineering
• Scoping is via group_id per project; cross-project queries are supported
• Sessions can be marked private to exclude them from memory ingestion

What Does NOT Change

• No changes to the OpenCode backend — MCP and session APIs already exist
• Minimal config change — one mcp entry in opencode.json pointing to the Graphiti server

Estimated LLM Cost

Graphiti uses multiple LLM calls per ingestion (entity extraction, deduplication, relationship extraction, summarization). Using gpt-4.1-mini:

• ~$0.01-0.05 per session ingestion
• ~$0.50-1.00/day for ~20 sessions/day across machines
• Configurable: can use Ollama for local/free extraction at the cost of quality

Phase 1: Infrastructure

• Create Graphiti + FalkorDB deployment configuration #240 Create Graphiti + FalkorDB deployment configuration

Phase 2: Core Pipeline

• Build background session ingestion watcher #241 Build background session ingestion watcher
• Configure OpenCode MCP integration with Graphiti memory server #242 Configure OpenCode MCP integration with Graphiti memory server
• Add private session mode to exclude sessions from memory ingestion #247 Add private session mode to exclude sessions from memory ingestion

Phase 3: Production Readiness

• Add session ingestion watcher as s6 service in Kubeflow image #243 Add session ingestion watcher as s6 service in Kubeflow image
• Define custom Graphiti entity types for coding session knowledge #244 Define custom Graphiti entity types for coding session knowledge

Phase 4: Validation

• End-to-end test and validate memory system #245 End-to-end test and validate memory system

Recommended Execution Order

1. Create Graphiti + FalkorDB deployment configuration #240 (Graphiti deployment) — foundation, everything depends on this
2. Define custom Graphiti entity types for coding session knowledge #244 (custom entity types) — define before ingesting real data
3. Build background session ingestion watcher #241 (watcher) — the core pipeline
4. Add private session mode to exclude sessions from memory ingestion #247 (private mode) — depends on watcher state file design from Build background session ingestion watcher #241
5. Configure OpenCode MCP integration with Graphiti memory server #242 (MCP config) — connect OpenCode to the memory system
6. Add session ingestion watcher as s6 service in Kubeflow image #243 (Kubeflow s6 service) — production deployment
7. End-to-end test and validate memory system #245 (e2e testing) — validate everything works together

Reference

• Graphiti: https://github.com/getzep/graphiti
• Graphiti MCP server: mcp_server/ in the Graphiti repo
• FalkorDB: https://github.com/FalkorDB/FalkorDB
• OpenCode MCP support: already built into the backend and Web UI
• OpenCode SSE events: session.status with idle/busy/retry states
• OpenCode session API: GET /session/{id}/message for full transcript
• Upstream memory feature requests: Feature Request: Model-Agnostic Memory Layer (Global & Per-Project) anomalyco/opencode#8043, #16077, #20322