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?

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.

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:

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