Opencode Mem

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 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

• latest stable Rust
• PostgreSQL with pgvector extension
• 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.

License

MIT