---

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-rs using 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 observations
• sessions / sessions_api — Session lifecycle, summaries, retrieval
• session_ops — Advanced operations (merge, split, archive)
• infinite — Deep-zoom endpoints (expand_summary, time_range, drill_hour, drill_minute)
• search — Semantic, FTS, and hybrid search
• knowledge — Global knowledge base management
• queue — Pending queue and DLQ inspection
• context — Context compilation for agent injection
• admin — 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 pgvector extension
• 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 Error or None, 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.

License

MIT