remem

The reasoning memory layer for AI agents.

---

⚠️ In Development — remem is evolving rapidly. Not yet recommended for mission-critical production workloads.

remem provides agents with persistent, reasoned memory that spans across sessions. Unlike traditional vector stores that rely solely on semantic similarity, remem incorporates an LLM reasoning step at every stage of the memory lifecycle: from initial importance scoring and guided retrieval to session-wide consolidation and contradiction detection.

Architecture

┌─────────────────────────────────────────────────────┐
│                  Agent Consumers                    │
│  Claude Code · Cursor · Codex · Python/TS agents    │
└──────────┬──────────────────┬───────────────────────┘
           │ 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   │
└──────┬──────────────────────────┬───────────────────┘
       │                          │
┌──────▼──────┐          ┌────────▼────────────────────┐
│ OpenAI      │          │  Storage Layer              │
│ Anthropic   │          │  SQLite + WAL (metadata)    │
│ Gemini      │          │  Vector Index (HNSW)        │
└─────────────┘          └─────────────────────────────┘

Why remem?

Traditional vector stores often suffer from "confident recall of irrelevant context." They return what is semantically nearest, not what is actually useful. remem bridges this gap with reasoning.

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

🚀 Quickstart

Model Context Protocol (MCP) — Claude Code / Cursor / Codex

remem is designed to work seamlessly with MCP-compliant environments. Add the following to your configuration:

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

Python SDK

pip install rememhq

from rememhq import Memory

m = Memory(project="my-agent", reasoning_model="claude-sonnet-4-6")

# Store a durable preference
await m.store("The production database is PostgreSQL 15 on RDS", tags=["infra"])

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

TypeScript SDK

npm install @rememhq/sdk

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

const m = new Memory({ project: "my-agent", reasoningModel: "gpt-5.3" });
await m.store("This repository uses trunk-based development", { tags: ["workflow"] });

const results = await m.recall("how do we manage branches?");

⚙️ How it Works

1. Guided Retrieval: When you query remem, it first retrieves the top 50 candidates using cosine similarity on the vector index. These candidates are then passed to an LLM (e.g., Claude 4.6 Sonnet) which filters and re-ranks them, returning the top ~8 most relevant memories accompanied by a "reasoning trace" explaining why they were chosen.
2. Session Consolidation: At the end of a session, remem can ingest the entire interaction log. An LLM extracts durable, high-signal facts, scores their importance, and identifies relationships between them.
3. Knowledge Graph & Contradiction Detection: Facts are stored as structured nodes and edges (triples) in a knowledge graph. When new information is added that conflicts with existing knowledge, remem flags the contradiction, allowing the agent to clarify or archive the stale memory.
4. Local First: Using libremem, a custom C++ engine, remem supports local HNSW indexing and BERT-compatible tokenization for privacy-first, offline embedding generation.

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