opencode-mem
Persistent memory infrastructure for AI coding agents.
A Rust MCP server combining PostgreSQL full-text search, optional vector retrieval, and hierarchical summaries.
opencode-mem is a Rust MCP (Model Context Protocol) server for storing and retrieving agent observations. PostgreSQL is the canonical store; pgvector-backed embeddings and hierarchical summaries provide additional retrieval paths when configured.
Inspired by claude-mem, with a PostgreSQL-first architecture for OpenCode and MCP clients.
Core design
Implemented paths
- Hierarchical summaries can be expanded back to their stored source events.
- Hybrid retrieval combines PostgreSQL full-text results with vector similarity when embeddings are enabled.
- Structured metadata extraction records files, functions, libraries, errors, and decisions from model output.
- Context-aware compression can create a new observation, update a supplied candidate, or skip a low-value result.
- MCP, HTTP, and CLI entrypoints share the same PostgreSQL-backed service layer.
- Database connection failures are surfaced through circuit-breaker and degraded-mode paths.
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: latest stable Rust · PostgreSQL with pgvector extension
1. Configure
export DATABASE_URL="postgresql://localhost/opencode_mem"
read -rsp "Provider API key: " OPENCODE_MEM_API_KEY && printf '\n'
export OPENCODE_MEM_API_KEY
export OPENCODE_MEM_API_URL="https://api.openai.com" # or any compatible endpoint
Use a credential manager or protected environment file for persistent secrets;
do not commit database passwords or provider keys to opencode.json.
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. OpenCode substitutes the already exported
environment variables at runtime, so the config remains safe to commit:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"memory": {
"type": "local",
"command": ["/path/to/opencode-mem-cli", "mcp"],
"environment": {
"DATABASE_URL": "{env:DATABASE_URL}",
"OPENCODE_MEM_API_KEY": "{env:OPENCODE_MEM_API_KEY}",
"OPENCODE_MEM_API_URL": "{env:OPENCODE_MEM_API_URL}"
}
}
}
}
MCP Tools
The server exposes MCP tools for search, retrieval, knowledge, and summary drill-down. The recommended workflow is Search → Timeline → Get Observations so clients fetch full records only when needed.
HTTP API
HTTP endpoints are organized across the following 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:
Development
Prerequisites
- latest stable Rust
- PostgreSQL with
pgvectorextension - An OpenAI-compatible LLM API (for compression features)
Running Tests
export DATABASE_URL="postgresql://localhost/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
Development constraints
- PostgreSQL remains the canonical persistence path.
- Missing or invalid data returns an explicit error or absence, not a fabricated value.
- Schema changes use forward migrations and preserve existing data.
- Privacy filtering must remain ahead of persistence, queues, embeddings, summaries, logs, and external model calls.
Project Status
Active pre-release project. Core MCP, HTTP, PostgreSQL, queue, and search paths are implemented, but release readiness depends on the current CI result and validation against a real OpenCode consumer. IDE-specific hooks remain outside the current scope. Infinite memory and semantic search should be treated as experimental until their deployment requirements and failure modes are documented and exercised end to end.
Contributing
Contributions welcome! See CONTRIBUTING.md for development setup and guidelines.
