feat: move session memory to Redis hot tier

Author: vicary

.gitignore

@@ -1,4 +1,5 @@
 .opencode/
+.swarm/
 
 dist/
 

README.md

@@ -1,55 +1,86 @@
 # opencode-graphiti
 
-OpenCode plugin that provides persistent memory via a
-[Graphiti](https://github.com/getzep/graphiti) knowledge graph.
+OpenCode plugin that provides persistent memory via
+[FalkorDB](https://www.falkordb.com/)/Redis and asynchronous
+[Graphiti](https://github.com/getzep/graphiti) knowledge-graph consolidation.
 
 ## Motivation
 
 Long-running AI coding sessions depend on persistent memory to stay on track.
-Graphiti's MCP server is the intended backbone for this, but in practice it is
-unreliable — connections drop, queries time out, and ingestion silently fails.
-When the context window fills up and OpenCode triggers compaction, the
-summarizer discards details that were never persisted. The result is **context
-rot**: the agent loses track of recent decisions, re-explores solved problems,
-and drifts away from the original goal.
-
-This plugin exists to close that gap. It captures chat histories and project
-facts into Graphiti when the server is healthy, then **re-injects them at the
-start of every session and before every compaction** so the agent is always
-reminded of recent project context — regardless of what survived the summary.
+Graphiti's MCP server is a powerful knowledge-graph backend, but synchronous
+calls to it on every message add latency and introduce a single point of failure
+— connections drop, queries time out, and ingestion silently fails. When the
+context window fills up and OpenCode triggers compaction, the summarizer
+discards details that were never persisted. The result is **context rot**: the
+agent loses track of recent decisions, re-explores solved problems, and drifts
+away from the original goal.
+
+This plugin exists to close that gap. It uses **FalkorDB/Redis as the hot-path
+store** for structured session events, priority-tiered snapshots, and cached
+memory — all readable in sub-millisecond time. Graphiti remains the long-term
+knowledge graph but is accessed **only asynchronously**, off the critical path.
+The plugin re-injects session context before every LLM call and before every
+compaction so the agent is always reminded of recent project context —
+regardless of what survived the summary and regardless of Graphiti availability.
 
 ## Overview
 
-This plugin connects to a Graphiti MCP server and:
+This plugin uses a two-tier architecture:
 
-- Searches Graphiti for relevant facts and entities on each user message
-- Injects memories into the last user message as a `<memory>` block via
+**Hot path (FalkorDB/Redis — synchronous, sub-ms):**
+
+- Stores structured session events, priority-tiered snapshots, and cached
+  Graphiti results in Redis
+- Reads cached memory on each user message and injects it into the last user
+  message as a `<session_memory>` block via
   `experimental.chat.messages.transform`, keeping the system prompt static for
   prefix caching
-- Detects context drift using Jaccard similarity and re-injects when the
-  conversation topic shifts
-- Buffers user and assistant messages, flushing them to Graphiti on idle or
-  before compaction
-- Preserves key facts during context compaction
+- Composes the same `<session_memory>` envelope for compaction context via
+  `experimental.session.compacting`
+- Detects context drift using Jaccard similarity on cached fact UUIDs and
+  schedules an async cache refresh when the topic shifts
+
+**Async tier (Graphiti MCP — fire-and-forget, non-blocking):**
+
+- Drains buffered session events to Graphiti as episodes on idle or before
+  compaction
+- Refreshes the Redis memory cache from Graphiti search results in the
+  background
+- Provides cross-session recall via vector/graph search, cached in Redis for
+  chat-time injection
 - Saves compaction summaries as episodes so knowledge survives across boundaries
-- Annotates stale facts and filters expired ones automatically
-- Scopes memories per project (and per user) using directory-based group IDs
+
+No Graphiti call ever blocks a hook return.
 
 ## Prerequisites
 
+### FalkorDB / Redis
+
+A running [FalkorDB](https://www.falkordb.com/) instance accessible via the
+Redis protocol. The easiest way to start one:
+
+```bash
+docker run -p 6379:6379 falkordb/falkordb:latest
+```
+
+### Graphiti MCP Server
+
 A running
 [Graphiti MCP server](https://github.com/getzep/graphiti/tree/main/mcp_server)
-accessible over HTTP. The easiest way to set one up:
+accessible over HTTP:
 
 ```bash
-# Clone and start with Docker Compose
 git clone https://github.com/getzep/graphiti.git
 cd graphiti/mcp_server
 docker compose up -d
 ```
 
-This starts the MCP server at `http://localhost:8000/mcp` with a FalkorDB
-backend.
+This starts the MCP server at `http://localhost:8000/mcp`.
+
+> **Note:** Graphiti is optional for basic operation. If Graphiti is
+> unavailable, the plugin continues to function with FalkorDB/Redis-sourced
+> session memory; only the `<persistent_memory>` section (long-term
+> cross-session facts) will be empty until Graphiti comes online.
 
 ## Installation
 
@@ -101,95 +132,151 @@ automatically.
 
 Supported config locations, in lookup order:
 
-1. The provided project directory: `package.json#graphiti`, `.graphitirc`, and other standard `cosmiconfig` `graphiti` filenames
-2. Standard global/home `graphiti` config locations discovered by `cosmiconfig` (for example `~/.graphitirc`)
+1. The provided project directory: `package.json#graphiti`, `.graphitirc`, and
+   other standard `cosmiconfig` `graphiti` filenames
+2. Standard global/home `graphiti` config locations discovered by `cosmiconfig`
+   (for example `~/.graphitirc`)
 3. Legacy fallback: `~/.config/opencode/.graphitirc`
 
-Example `.graphitirc`:
+### Nested Config Shape (recommended)
 
 ```jsonc
 {
-  // Graphiti MCP server endpoint
-  "endpoint": "http://localhost:8000/mcp",
-
-  // Prefix for project group IDs (e.g. "opencode-my-project")
-  "groupIdPrefix": "opencode",
-
-  // Jaccard similarity threshold (0–1) below which memory is re-injected
-  // Lower values mean the topic must drift further before re-injection
-  "driftThreshold": 0.5,
-
-  // Number of days after which facts are annotated as stale
-  "factStaleDays": 30
+  "falkordb": {
+    // FalkorDB Redis URL
+    "redisEndpoint": "redis://localhost:6379",
+    // Max events per drain batch
+    "batchSize": 20,
+    // Max combined body bytes per drain batch
+    "batchMaxBytes": 51200,
+    // Session event TTL in seconds (default: 24 h)
+    "sessionTtlSeconds": 86400,
+    // Memory cache TTL in seconds (default: 10 min)
+    "cacheTtlSeconds": 600,
+    // Max drain retry attempts before dead-lettering
+    "drainRetryMax": 3
+  },
+  "graphiti": {
+    // Graphiti MCP server endpoint
+    "endpoint": "http://localhost:8000/mcp",
+    // Prefix for project group IDs (e.g. "opencode-my-project")
+    "groupIdPrefix": "opencode",
+    // Jaccard similarity threshold (0–1) below which cache is refreshed
+    "driftThreshold": 0.5,
+    // Number of days after which facts are annotated as stale
+    "factStaleDays": 30
+  }
 }
 ```
 
 All fields are optional — defaults (shown above) are used for any missing
-values.
+values. Nested values take precedence when both forms are supplied.
+
+### Legacy Top-Level Keys
+
+For backward compatibility, the following top-level keys are still accepted and
+map to their nested equivalents:
+
+| Legacy key          | Nested equivalent            |
+| ------------------- | ---------------------------- |
+| `endpoint`          | `graphiti.endpoint`          |
+| `groupIdPrefix`     | `graphiti.groupIdPrefix`     |
+| `driftThreshold`    | `graphiti.driftThreshold`    |
+| `factStaleDays`     | `graphiti.factStaleDays`     |
+| `redisEndpoint`     | `falkordb.redisEndpoint`     |
+| `batchSize`         | `falkordb.batchSize`         |
+| `batchMaxBytes`     | `falkordb.batchMaxBytes`     |
+| `sessionTtlSeconds` | `falkordb.sessionTtlSeconds` |
+| `cacheTtlSeconds`   | `falkordb.cacheTtlSeconds`   |
+| `drainRetryMax`     | `falkordb.drainRetryMax`     |
 
 ## How It Works
 
-### Memory Search and Caching (`chat.message`)
+### Injection Format
+
+The plugin injects a single canonical `<session_memory>` XML envelope into the
+last user message. This envelope is assembled from Redis hot-tier state and
+contains structured sections such as `<last_request>`, `<active_tasks>`,
+`<key_decisions>`, `<files_in_play>`, `<project_rules>`, and an optional
+`<session_snapshot>`.
+
+When cached Graphiti results are available, a nested `<persistent_memory>`
+section is included with `fact_uuids` and `node_refs` attributes. On a cold
+first turn or when Graphiti is unreachable, `<persistent_memory>` is simply
+absent — the rest of the session memory is always available from FalkorDB/Redis.
+
+```xml
+<session_memory source="falkordb+graphiti-cache" version="1">
+  <last_request>Continue the current task.</last_request>
+  <active_tasks><task>Implement the new feature.</task></active_tasks>
+  <key_decisions><decision>Use Redis for the hot path.</decision></key_decisions>
+  <files_in_play><file>src/index.ts</file></files_in_play>
+  <project_rules><rule>No synchronous Graphiti calls.</rule></project_rules>
+  <session_snapshot><!-- priority-tiered snapshot --></session_snapshot>
+  <persistent_memory fact_uuids="uuid1,uuid2" node_refs="nodeA">
+    <!-- cached Graphiti facts/nodes, optional -->
+  </persistent_memory>
+</session_memory>
+```
+
+### Hot-Path Memory Preparation (`chat.message`)
 
-On each user message the plugin searches Graphiti for facts and entities
-relevant to the message content. Results are split into project and user scopes
-(70% / 30% budget), deduplicated, filtered for validity, annotated with
-staleness if older than `factStaleDays`, and formatted as Markdown. The
-formatted context is cached on the session state for the messages transform hook
-to pick up.
+On each user message the plugin reads session state from Redis:
 
-On the very first message of a session, the plugin also loads the most recent
-session snapshot episode to prime the conversation with prior context.
+- Recent structured session events (`session:{id}:events`)
+- The priority-tiered snapshot (`session:{id}:snapshot`)
+- The cached Graphiti memory (`memory-cache:{groupId}`)
 
-The injection budget is calculated dynamically: 5% of the model's context limit
-(resolved from the provider list) multiplied by 4 characters per token.
+These are composed into a `<session_memory>` envelope and staged for the
+transform hook. All reads are from Redis (sub-ms); no Graphiti call is made on
+this path.
 
 ### User Message Injection (`experimental.chat.messages.transform`)
 
-A separate hook reads the cached memory context and prepends it to the last user
-message as a `<memory data-uuids="...">` block. The `data-uuids` attribute lists
-the fact UUIDs included in the injection, which are tracked in
-`visibleFactUuids` so subsequent searches can filter out already-visible facts.
-This approach keeps the system prompt static, enabling provider-side prefix
-caching, and avoids influencing session titles. The cache is cleared after
-injection so stale context is not re-injected on subsequent LLM calls within the
-same turn.
+The transform hook reads the prepared `<session_memory>` envelope and prepends
+it to the last user message. Fact UUIDs from the `<persistent_memory>` section
+are tracked in `visibleFactUuids` so subsequent cache refreshes can filter out
+already-visible facts. This approach keeps the system prompt static, enabling
+provider-side prefix caching, and avoids influencing session titles. The
+prepared injection is cleared after use so stale context is not re-injected on
+subsequent LLM calls within the same turn.
 
-### Drift-Based Re-injection (`chat.message`)
+### Drift Detection and Async Cache Refresh
 
-After the first injection, the plugin monitors for context drift on every user
-message. It searches Graphiti for the current message and compares the returned
-fact UUIDs against the previously injected set using Jaccard similarity. When
-similarity drops below `driftThreshold` (default 0.5), the memory cache is
-refreshed with project-scoped results only (no user scope).
+On each user message, the plugin compares the current query against the query
+that produced the cached memory. When Jaccard similarity on cached fact UUIDs
+drops below `driftThreshold` (default 0.5), an **async** cache refresh is
+scheduled via Graphiti MCP. The current cached context is still injected
+immediately; the refreshed cache becomes available on the next message. This
+trades one message of staleness for eliminating synchronous Graphiti latency
+entirely.
 
-### Message Buffering (`event`)
+### Event Extraction and Buffering (`event`)
 
-User and assistant messages are buffered in memory as they arrive. The plugin
-listens on `message.part.updated` to capture assistant text as it streams, and
-on `message.updated` to finalize completed assistant replies. Buffered messages
-are flushed to Graphiti as episodes:
+User and assistant messages are captured as structured `SessionEvent` objects
+and stored in Redis (`session:{id}:events`). The plugin listens on
+`message.part.updated` to buffer assistant text as it streams, and on
+`message.updated` to finalize completed assistant replies.
 
-- **On idle** (`session.idle`): when the session becomes idle with at least 50
-  bytes of buffered content.
-- **Before compaction** (`session.compacted`): all buffered messages are flushed
-  immediately (no minimum size) so nothing is lost.
+Events are also enqueued for async drain to Graphiti:
 
-If the last buffered message is from the user (i.e. no assistant reply was
-captured), the plugin fetches the latest assistant message from the session API
-as a fallback before flushing.
+- **On idle** (`session.idle`): buffered events are drained and the
+  priority-tiered snapshot is rebuilt.
+- **Before compaction** (`session.compacted`): all pending events are drained
+  immediately so nothing is lost.
 
-### Compaction Preservation (`session.compacted` + `experimental.session.compacting`)
+### Compaction Preservation
 
 Compaction is handled entirely by OpenCode's native compaction mechanism. The
 plugin participates in two ways:
 
-1. **Before compaction** (`experimental.session.compacting`): The plugin injects
-   known facts and entities into the compaction context using the same 70% / 30%
-   project/user budget split, so the summarizer preserves important knowledge.
-2. **After compaction** (`session.compacted`): The compaction summary is saved
-   as an episode to Graphiti, ensuring knowledge survives across compaction
-   boundaries.
+1. **Before compaction** (`experimental.session.compacting`): The plugin reads
+   the snapshot and cached memory from Redis and composes the same canonical
+   `<session_memory>` envelope used for chat injection, so the summarizer
+   preserves important knowledge. No Graphiti call is made.
+2. **After compaction** (`session.compacted`): The snapshot is rebuilt from
+   Redis events and the compaction summary is enqueued for async drain to
+   Graphiti, ensuring knowledge survives across compaction boundaries.
 
 ### Project Scoping
 
@@ -207,7 +294,12 @@ process.
 
 MIT
 
-## Acknowledgement
+## Acknowledgements
+
+The structured event extraction, priority-tiered snapshots, and session
+continuity design in this plugin are inspired by
+[context-mode](https://github.com/mksglu/context-mode) by
+[Mert Köseoğlu](https://github.com/mksglu).
 
-This project is inspired by
-[opencode-openmemory](https://github.com/happycastle114/opencode-openmemory)
+The original plugin concept is inspired by
+[opencode-openmemory](https://github.com/happycastle114/opencode-openmemory).

deno.json

@@ -33,6 +33,7 @@
     "@opencode-ai/plugin": "npm:@opencode-ai/plugin@^1.1.53",
     "@opencode-ai/sdk": "npm:@opencode-ai/sdk@^1.1.53",
     "cosmiconfig": "npm:cosmiconfig@9.0.0",
+    "ioredis": "npm:ioredis@^5.7.0",
     "zod": "npm:zod@4.3.6"
   },
   "exports": {