Opencode Mem

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.

[](https://github.com/Stranmor/opencode-mem/actions) [](LICENSE) [](https://www.rust-lang.org) [](https://github.com/Stranmor/opencode-mem/stargazers) [](https://github.com/Stranmor/opencode-mem/issues)

---

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 `` 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 `` 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         # Search observations
opencode-mem-cli get               # 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](CONTRIBUTING.md) for development setup and guidelines.

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Stranmor
• Source: Stranmor/opencode-mem
• License: MIT
• Homepage: https://github.com/Stranmor/opencode-mem#readme

Install and usage instructions live in the source repository linked above.