Opencode Mem
High-performance MCP memory server for AI coding agents. Rust, PostgreSQL, pgvector, hybrid search, hierarchical summarization.
Ask AI about Opencode Mem
Powered by Claude Β· Grounded in docs
I know everything about Opencode Mem. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
opencode-mem
Persistent, semantic memory for AI coding agents.
Give your AI agents long-term memory that actually works β hybrid search, hierarchical summaries, and infinite recall, all from a single Rust binary.
opencode-mem is a type-safe Rust MCP (Model Context Protocol) server that gives AI coding agents persistent memory. It combines full-text BM25 search with BGE-M3 1024-dimensional vector embeddings for semantic retrieval, backed by PostgreSQL and pgvector. A hierarchical infinite memory system lets agents recall context across sessions, drill down from daily summaries to 5-minute event intervals, and maintain long-term project coherence.
A Rust port of claude-mem with full feature parity and additional capabilities.
Why opencode-mem?
| Feature | opencode-mem | Typical TS/SQLite |
|---|---|---|
| Runtime | Native binary (Rust) | Node.js / Bun |
| Database | PostgreSQL + pgvector | SQLite + ChromaDB |
| Search | Hybrid FTS BM25 + Vector | Separate engines |
| Memory model | Infinite (never deleted) | Fixed window / FIFO |
| Crash recovery | DLQ + visibility timeout | None |
| Privacy | Built-in <private> filtering | None |
| Multilingual | 100+ languages (BGE-M3) | English-centric |
Key Features
- Infinite Memory & Deep Zoom β Raw events are never deleted. A hierarchical summarization pipeline (5min β hour β day) creates readable overviews, while the drill-down API lets you zoom from any summary back to raw events.
- Hybrid Search β Combines FTS BM25 (50%) and vector similarity (50%) directly within PostgreSQL. Powered by
fastembed-rsusing BGE-M3 (1024d, 100+ languages). - Structured Metadata Extraction β The LLM extracts
SummaryEntities(files, functions, libraries, errors, decisions) via strict JSON schema, enabling fact-based search even when text summaries are vague. - Context-Aware Compression β The AI agent analyzes existing observations before creating new ones. It decides to CREATE, UPDATE, or SKIP, eliminating duplicates before they hit the database.
- 18 MCP Tools for seamless AI agent integration (search, fetch, analyze, drill-down).
- 65+ HTTP API endpoints for external integrations and dashboards.
- CLI with full hook system (context injection, session init, observation, summarization).
- Privacy tags β Built-in
<private>content filtering across all ingest paths. - Circuit breaker β Graceful degradation when PostgreSQL is unavailable, with automatic recovery on reconnect.
- Single binary β Zero runtime dependencies beyond PostgreSQL.
Architecture
graph LR
A[AI Agent / IDE] -->|MCP stdio| B[opencode-mem]
A -->|HTTP :37777| B
B --> C[Queue Processor]
C --> D[LLM Compression]
D --> E[(PostgreSQL)]
E -->|pgvector| F[Semantic Search]
E -->|tsvector / GIN| G[Full-Text Search]
F & G --> H[Hybrid Results]
Crate Structure
crates/
βββ core/ # Domain types (Observation, Session, Knowledge, etc.)
βββ storage/ # PostgreSQL + pgvector + migrations + circuit breaker
βββ embeddings/ # Vector embeddings (fastembed BGE-M3, 1024d, multilingual)
βββ search/ # Hybrid search (FTS + keyword + semantic)
βββ llm/ # LLM compression (OpenAI-compatible API)
βββ service/ # Business logic (ObservationService, SessionService, QueueService)
βββ http/ # HTTP API (Axum)
βββ mcp/ # MCP server (stdio)
βββ infinite-memory/ # Hierarchical infinite memory backend
βββ cli/ # CLI binary
Installation
From source
git clone https://github.com/Stranmor/opencode-mem.git
cd opencode-mem
cargo build --release
# Binary: target/release/opencode-mem-cli
Quick Start
Prerequisites: Rust 1.88+ Β· PostgreSQL with pgvector extension
1. Configure
export DATABASE_URL="postgres://user:pass@localhost/opencode_mem"
export OPENCODE_MEM_API_KEY="your-openai-compatible-api-key"
export OPENCODE_MEM_API_URL="https://api.openai.com" # or any compatible endpoint
Migrations run automatically on first start.
2. Run
# MCP server (for IDE integration):
opencode-mem-cli mcp
# HTTP server (for dashboards and external integrations):
opencode-mem-cli serve
3. Integrate with OpenCode
Add to your opencode.json:
{
"mcpServers": {
"memory": {
"type": "stdio",
"command": "/path/to/opencode-mem-cli",
"args": ["mcp"],
"env": {
"DATABASE_URL": "postgres://user:pass@localhost/opencode_mem",
"OPENCODE_MEM_API_KEY": "your-api-key",
"OPENCODE_MEM_API_URL": "https://api.openai.com"
}
}
}
}
MCP Tools
The server exposes 18 MCP tools. The recommended workflow is the 3-Layer Pattern β Search β Timeline β Get Observations β to minimize token usage.
| Tool | Description |
|---|---|
search | Search memory with semantic understanding. Returns index with IDs. |
timeline | Get chronological context within a time range. |
get_observations | Fetch full details for specific observation IDs. |
memory_get | Get a single observation by ID. |
memory_recent | Get the most recent observations. |
memory_hybrid_search | Combined FTS + keyword search. |
memory_semantic_search | Pure semantic search with hybrid fallback. |
save_memory | Save memory directly (bypasses LLM compression). |
knowledge_search | Search the global knowledge base. |
knowledge_save | Save a new knowledge entry (skill, pattern, gotcha). |
knowledge_get | Get a knowledge entry by ID. |
knowledge_list | List knowledge entries by type. |
knowledge_delete | Delete a knowledge entry. |
infinite_expand | Expand a summary to see child events. |
infinite_time_range | Get events within a time range. |
infinite_drill_hour | Drill from day summary to hour summaries. |
infinite_drill_minute | Drill from hour summary to 5-minute summaries. |
__IMPORTANT | Workflow documentation (3-Layer Pattern). |
HTTP API
65+ endpoints organized across 11 handler modules:
observationsβ CRUD and bulk operations for observationssessions/sessions_apiβ Session lifecycle, summaries, retrievalsession_opsβ Advanced operations (merge, split, archive)infiniteβ Deep-zoom endpoints (expand_summary,time_range,drill_hour,drill_minute)searchβ Semantic, FTS, and hybrid searchknowledgeβ Global knowledge base managementqueueβ Pending queue and DLQ inspectioncontextβ Context compilation for agent injectionadminβ Health checks, configuration, diagnostics
CLI
# Server
opencode-mem-cli serve # HTTP API server (port 37777)
opencode-mem-cli mcp # MCP stdio server
# Maintenance
opencode-mem-cli backfill-embeddings # Generate missing vector embeddings
opencode-mem-cli import-insights # Import legacy JSON insights
# Data Access
opencode-mem-cli search <query> # Search observations
opencode-mem-cli get <id> # Get observation by UUID
opencode-mem-cli recent # Recent observations
opencode-mem-cli projects # List tracked projects
opencode-mem-cli stats # Database statistics and queue health
# IDE Hooks
opencode-mem-cli hook context # Retrieve context for prompt injection
opencode-mem-cli hook session-init # Initialize a new session
opencode-mem-cli hook observe # Record an observation
opencode-mem-cli hook summarize # Trigger session summarization
Configuration
All configuration is via environment variables:
| Variable | Required | Default | Description |
|---|---|---|---|
DATABASE_URL | Yes | β | PostgreSQL connection string |
OPENCODE_MEM_API_KEY | Yes | β | API key for the LLM provider |
OPENCODE_MEM_API_URL | No | https://api.openai.com | OpenAI-compatible API base URL |
OPENCODE_MEM_MODEL | No | β | Model for compression (e.g., gpt-4o) |
OPENCODE_MEM_DISABLE_EMBEDDINGS | No | false | Disable vector embeddings (1 or true) |
INFINITE_MEMORY_URL | No | DATABASE_URL | Separate DB for infinite memory |
OPENCODE_MEM_EXCLUDED_PROJECTS | No | β | Glob patterns for excluded projects |
OPENCODE_MEM_FILTER_PATTERNS | No | β | Custom noise filter patterns (regex) |
OPENCODE_MEM_DEDUP_THRESHOLD | No | 0.85 | Cosine similarity for dedup [0.0, 1.0] |
OPENCODE_MEM_INJECTION_DEDUP_THRESHOLD | No | 0.80 | IDE injection loop detection [0.0, 1.0] |
OPENCODE_MEM_EMBEDDING_THREADS | No | cores - 1 | ONNX embedding threads |
OPENCODE_MEM_MAX_RETRY | No | 3 | LLM compression retries |
OPENCODE_MEM_VISIBILITY_TIMEOUT | No | 300s | Queue visibility timeout |
OPENCODE_MEM_QUEUE_WORKERS | No | 10 | Concurrent queue workers |
OPENCODE_MEM_DLQ_TTL_DAYS | No | 7 | Dead letter queue retention |
OPENCODE_MEM_MAX_CONTENT_CHARS | No | 500 | Max chars per observation field |
OPENCODE_MEM_MAX_TOTAL_CHARS | No | 8000 | Max chars for LLM prompt |
OPENCODE_MEM_MAX_EVENTS | No | 200 | Max raw events per memory chunk |
Development
Prerequisites
- Rust 1.88+
- PostgreSQL with
pgvectorextension - An OpenAI-compatible LLM API (for compression features)
Running Tests
export DATABASE_URL="postgres://postgres:postgres@localhost:5432/opencode_mem_test"
# Unit tests (no DB required)
cargo test --workspace
# Integration tests (requires running PostgreSQL)
cargo test --workspace -- --ignored
Code Quality
cargo fmt --all
cargo clippy --workspace -- -D warnings
Architecture Principles
- SPOT β Single Point of Truth. No data duplication.
- Zero Fallback β Missing data returns
ErrororNone, never dummy values. - Compile-time query validation β SQLx verifies all queries against the live DB schema.
- Modular workspace β 10 crates with enforced domain boundaries.
Project Status
Production-ready. Full feature parity with the upstream claude-mem TypeScript implementation (excluding IDE-specific hooks). Infinite memory and semantic search are enabled by default.
Contributing
Contributions welcome! See CONTRIBUTING.md for development setup and guidelines.
