remem

Give your AI assistant a memory that learns, adapts and reasons.

---

remem provides agents with persistent, reasoned memory that spans across sessions. It enhances AI assistants and agents with an intelligent memory layer that enables truly personalized AI interactions — it remembers user preferences, adapts to individual needs, and continuously learns over time, turning stateless AI tools into persistent, context-aware partners.

Unlike traditional vector stores that rely solely on semantic similarity, remem incorporates an LLM reasoning layer to distinguish between what is semantically close and what is actually useful for solving problems. Whether you're using Claude Code, Codex, Cursor, Copilot, Antigravity CLI, or OpenCode, remem gives your AI a durable, cross-session memory that grows smarter with every interaction.

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                        Agent Consumers                               │
│  Claude Code · Codex · Cursor · Copilot · Antigravity CLI · OpenCode │
│  Python agents · TypeScript agents · Any MCP-compatible client       │
└──────────┬──────────────────────┬────────────────────────────────────┘
           │ MCP stdio            │ REST API / SDK
┌──────────▼──────────────────────▼────────────────────────────────────┐
│                    Interface Layer (Rust)                            │
│       rememhq-mcp (stdio) · rememhq-api (Axum REST)                  │
│       Python SDK (httpx)  · TypeScript SDK (fetch)                   │
└────────────────────────────┬─────────────────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────────────────┐
│                Reasoning Engine (rememhq-core)                       │
│    Consolidation · Guided Retrieval · Contradiction Detection        │
│    Importance Scoring · Knowledge Graph · Preference Learning        │
└──────────┬─────────────────────────────┬──────────────────────────── ┘
           │                             │
┌──────────▼──────────┐       ┌──────────▼────────────────────────────┐
│ LLM Providers       │       │  Storage Layer                        │
│ OpenAI · Anthropic  │       │  SQLite + WAL (metadata)              │
│ Gemini · Local ONNX │       │  Vector Index (HNSW via libremem)     │
└─────────────────────┘       └───────────────────────────────────────┘

Supported Agent Consumers

remem integrates with the leading AI coding assistants and agent frameworks. Each consumer connects through either the MCP stdio protocol or the REST API / SDK, giving your AI tools a shared, persistent memory across sessions.

Consumer	Integration	How It Connects
Claude Code	MCP (stdio)	Native MCP support — add remem as an MCP server in your project config
Codex	MCP (stdio)	Connects via MCP server configuration, enabling persistent context across coding sessions
Cursor	MCP (stdio)	Add remem to Cursor's MCP settings for cross-session memory in your IDE
GitHub Copilot	MCP (stdio)	MCP server integration provides durable project context alongside Copilot suggestions
Antigravity CLI	MCP (stdio)	Configure remem as an MCP tool server for Antigravity CLI agents
OpenCode	MCP (stdio)	MCP-compatible — works out of the box with remem's stdio transport
Aider	MCP (stdio)	Auto-configured via remem init aider for cross-session architecture reasoning
Windsurf	MCP (stdio)	Native MCP support for Windsurf workspaces
Cline	MCP (stdio)	Auto-injects memory limits and reasoning tools for Cline agents
Python agents	REST API / Python SDK	pip install rememhq — use Memory.store() and Memory.recall() in any async Python agent
TypeScript agents	REST API / TypeScript SDK	npm install @rememhq/sdk — typed client for Node.js and Deno agents
Any MCP client	MCP (stdio)	Any tool implementing the Model Context Protocol works with remem

Why remem?

• Remembers preferences: Coding style, tool choices, architecture decisions — stored once, recalled every time.
• Adapts to you: The more you interact, the better remem understands your project context and working patterns.
• Learns continuously: Session consolidation extracts durable knowledge from every interaction, building an ever-growing understanding of your codebase and workflows.
• Reasons about relevance: Unlike naive vector search, remem uses LLM reasoning to return what is actually useful, not just what is semantically nearest.

Traditional vector stores suffer from "confident recall of irrelevant context." remem bridges this gap with reasoning-powered retrieval that understands context, importance, and domain-specific relevance.

Feature	Naive Vector Store	remem
Store	embed + insert	embed + insert + LLM Importance Scoring
Recall	top-k by cosine similarity	top-50 cosine → LLM Re-ranking → top-8 with Reasoning Trace
Consolidation	—	LLM Fact Extraction from raw interaction logs
Contradictions	—	LLM Conflict Detection between old and new facts
Decay	Time-based (linear)	Importance-Weighted Decay; critical facts persist longer

Installation

1. Download Pre-built Binary

Download the latest executable for your platform (Linux, macOS, Windows) from GitHub Releases:

# Verify installation
remem --help

Or build directly via Cargo:

cargo install --path rememhq-cli

2. Install SDKs

# Python SDK
pip install rememhq

# TypeScript SDK
npm install @rememhq/sdk

Configuration & Environment Variables

remem seamlessly supports Google Gemini, Anthropic Claude, OpenAI, and Local ONNX models out of the box without code modifications. Set your preferred provider in your environment:

Environment Variable	Description	Example
REMEM_PROVIDER	AI Provider choice (gemini, claude, openai, local, mock)	export REMEM_PROVIDER=gemini
GOOGLE_API_KEY	Google Gemini API key	export GOOGLE_API_KEY="AIzaSy..."
ANTHROPIC_API_KEY	Anthropic Claude API key	export ANTHROPIC_API_KEY="sk-ant..."
OPENAI_API_KEY	OpenAI API key	export OPENAI_API_KEY="sk-..."
REMEM_DATA_DIR	Custom root data directory (defaults to ~/.remem)	export REMEM_DATA_DIR="/var/data/remem"

Quickstart

1. Auto-Configure AI Assistants (remem init)

Automatically inject remem memory into your AI coding assistant with a single command:

# Configure Cursor
remem init cursor --project my-project

# Configure Claude Code
remem init claude-code --project my-project

# Configure all supported agents in your workspace
remem init all --project my-project

2. Model Context Protocol (MCP) Manual Setup

Add remem to your tool's MCP configuration (.cursor/mcp.json, claude_code_config.json, etc.):

{
  "mcpServers": {
    "remem": {
      "command": "remem",
      "args": ["mcp", "--project", "my-project"]
    }
  }
}

3. Python SDK Usage

import asyncio
from rememhq import Memory

async def main():
    # Uses provider from environment (REMEM_PROVIDER=gemini, GOOGLE_API_KEY=...)
    m = Memory(project="my-agent")

    # Store durable preferences or facts
    await m.store("The production database uses PostgreSQL 15 on RDS with SSL", tags=["infra", "db"])

    # Recall with guided LLM reasoning & RRF hybrid search
    results = await m.recall("what database are we using?")
    for r in results:
        print(f"Content: {r.content}")
        print(f"Reasoning: {r.reasoning}")

asyncio.run(main())

4. TypeScript SDK Usage

import { Memory } from "@rememhq/sdk";

const m = new Memory({ project: "my-agent" });

// Store memory
await m.store("This repository uses trunk-based development", { tags: ["workflow"] });

// Recall with reasoning
const results = await m.recall("how do we manage branches?");
console.log(results);

Usage Commands

Local Development (Building from Source)

# Build the entire workspace
cargo build --workspace

# Run all tests
cargo test --workspace

# Check formatting
cargo fmt --all -- --check

# Format code
cargo fmt

# Lint (clippy) — must pass with no warnings
cargo clippy --workspace --all-targets -- -D warnings

Running the pre-built binaries (Downloaded Releases)

If you downloaded the pre-built binary releases from GitHub, you can use the remem executable directly. Here are some of the basic commands:

# Start the REST API server
remem serve --project my-project

# Start the MCP server (stdio transport)
remem mcp --project my-project

# Check configuration, storage paths, and provider readiness — the
# first thing to run after install or when something isn't working
remem doctor

# Also ping the configured LLM provider to verify the API key works
remem doctor --ping

# Store a memory
remem store "The main branch is called 'main'"

# Recall memories with guided retrieval
remem recall "What is the main branch called?"

# Search memories (no LLM re-ranking)
remem search "main branch"

# Forget (delete) a memory by ID
remem forget <memory-id>

# Show database statistics
remem inspect

# Apply importance-weighted decay to all active memories
remem decay

# Start an interactive REPL mode
remem repl

# Launch interactive Terminal UI (TUI) for browsing, searching, and monitoring memories
remem tui

# Launch TUI alongside an AI agent in a split-pane terminal (works with Windows Terminal, tmux, or iterm2)
remem tui --companion codex

# Start the Remem AI terminal agent (uses native tool calling to run shell commands)
# Ensure REMEM_PROVIDER is set to anthropic, openai, gemini, or local
remem agent

# List known local models and their install status
remem models list

# Pull the local embedding model (ONNX)
remem models pull nomic-embed

# Pull a local reasoning model (GGUF — serve with llama.cpp/Ollama)
remem models pull phi-3-mini

# One-command local inference server for a downloaded GGUF model
# (requires `llama-server` on PATH — https://github.com/ggml-org/llama.cpp)
remem models serve phi-3-mini

# Bulk import memories from a JSONL file
remem import data.jsonl

# Export all memories to a JSONL file
remem export backup.jsonl

# Initialize MCP configurations for all supported agents in your workspace
remem init all --project my-project

# Initialize MCP config for a specific agent (e.g. claude-code, windsurf, roocode)
remem init claude-code --project my-project

remem also has commands for project and session management, agent-loop execution, knowledge-graph workflows, and direct agent-harness interaction, plus a recall-latency benchmark — run remem --help or remem <command> --help for the full list and options.

Running Services from Source

If you are developing locally, you can run the components via cargo:

# Start the API server (REST interface)
cargo run -p rememhq-api -- --project default

# Start the MCP server (stdio interface for Claude Code, Cursor, etc.)
cargo run -p rememhq-mcp

# Run the CLI tool
cargo run -p rememhq-cli -- --help

# Run the interactive TUI
cargo run -p rememhq-cli -- tui

# Run the Remen AI terminal agent
cargo run -p rememhq-cli -- agent

SDKs

# Python SDK
cd sdk/python && pip install -e ".[dev]" && pytest tests/

# TypeScript SDK
cd sdk/typescript && npm install && npm run build

Contributing

We welcome contributions! Whether you're fixing a bug, improving the reasoning prompts, or adding a new provider, please check out our CONTRIBUTING.md.

1. Clone the repo: git clone https://github.com/remem-io/remem
2. Build: cargo build
3. Test: cargo test --workspace

License

remem is licensed under the Apache License 2.0. See LICENSE for details.