MenteDB

⚠️ Beta — MenteDB is under active development. APIs may change between minor versions.

The Mind Database for AI Agents

MenteDB is a purpose built database engine for AI agent memory. Not a wrapper around existing databases, but a ground up Rust storage engine that understands how AI/LLMs consume data.

mente (Spanish): mind, intellect

Quick Start

Just remember a conversation:

# Via REST API
curl -X POST http://localhost:6677/v1/ingest \
  -H "Content-Type: application/json" \
  -d '{"conversation": "User: I prefer Python over JS\nAssistant: Noted!", "agent_id": "my-agent"}'

# Response: { "memories_stored": 2, "rejected_low_quality": 5, "contradictions": 0 }

Via MCP (Claude CLI, Copilot CLI, Cursor):

// claude_desktop_config.json
{
  "mcpServers": {
    "mentedb": {
      "command": "mentedb-mcp",
      "args": ["--data-dir", "~/.mentedb"]
    }
  }
}

Then the AI can call ingest_conversation directly. No manual memory structuring needed.

Embed in Rust:

use mentedb::MenteDb;

let db = MenteDb::open("./my-agent-memory")?;
db.store(&memory_node)?;
let context = db.assemble_context(agent_id, space_id, 4096)?;

Why MenteDB?

Every database ever built assumes the consumer can compensate for bad data organization. AI can't. A transformer gets ONE SHOT, a single context window, a single forward pass. MenteDB is a cognition preparation engine that delivers perfectly organized knowledge because the consumer has no ability to reorganize it.

The Memory Quality Problem

Most AI memory tools store everything and retrieve by similarity. The result: context windows full of noise. Studies show up to 97% of automatically stored memories are irrelevant.

MenteDB solves this with write time intelligence:

1. LLM Powered Extraction parses conversations and extracts only what matters: decisions, preferences, corrections, facts, entities
2. Quality Filtering rejects low confidence extractions before they hit storage
3. Deduplication checks embedding similarity against existing memories
4. Contradiction Detection flags when new information conflicts with existing beliefs
5. Belief Propagation cascades updates when facts change

The result: a clean, curated memory that actually helps the AI perform better.

What Makes MenteDB Different

Core Features

• Automatic Memory Extraction LLM powered pipeline extracts structured memories from raw conversations
• Write Time Intelligence Quality filter, deduplication, and contradiction detection at ingest
• Attention Optimized Context Assembly Respects the U curve (critical data at start/end of context)
• Belief Propagation When facts change, downstream beliefs are flagged for re evaluation
• Delta Aware Serving Only sends what changed since last turn (90% reduction in memory retrieval tokens over 20 turns)
• Cognitive Memory Tiers Working, Episodic, Semantic, Procedural, Archival
• Knowledge Graph CSR/CSC graph with BFS/DFS traversal and contradiction detection
• Memory Spaces Multi agent isolation with per space ACLs
• MQL Mente Query Language with full boolean logic (AND, OR, NOT) and ordering (ASC/DESC)
• Type Safe IDs MemoryId, AgentId, SpaceId newtypes prevent accidental mixing
• Binary Embeddings Base64 encoded storage, 65% smaller than JSON arrays
• Local Candle Embeddings Zero config semantic search using all-MiniLM-L6-v2 (384 dims), no API key required
• gRPC + REST + MCP Three integration paths for any use case

Performance Targets (10M memories)

Integration Options

1. MCP Server (AI Clients)

For Claude CLI, Copilot CLI, Cursor, Windsurf, and any MCP compatible client.

# Requires Rust: https://rustup.rs
cargo install mentedb-mcp

See mentedb-mcp for setup, configuration, and the full list of 32 tools.

Key tools: store_memory, search_memories, forget_all, ingest_conversation, assemble_context, relate_memories, write_inference, get_cognitive_state, and 23 more covering knowledge graph, consolidation, and cognitive systems.

2. REST API

# Start the server
cargo run -p mentedb-server -- --data-dir ./data --jwt-secret-file ./secret.key

# Store a memory
curl -X POST http://localhost:6677/v1/memories \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"agent_id": "...", "content": "User prefers dark mode", "memory_type": "semantic"}'

# Ingest a conversation (automatic extraction)
curl -X POST http://localhost:6677/v1/ingest \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"conversation": "...", "agent_id": "..."}'

# Recall memories
curl -X POST http://localhost:6677/v1/query \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"mql": "RECALL memories WHERE tag = \"preferences\" LIMIT 10"}'

3. gRPC

Bidirectional streaming for real time cognition updates. Proto file at crates/mentedb-server/proto/mentedb.proto.

4. SDKs

Python:

from mentedb import MenteDb

db = MenteDb("./agent-memory")
db.store(content="User prefers Python", memory_type="semantic", agent_id="my-agent")
db.ingest("User: I switched to Vim\nAssistant: Got it!")
results = db.recall("RECALL memories WHERE tag = 'preferences' LIMIT 5")

TypeScript:

import { MenteDb } from 'mentedb';

const db = new MenteDb('./agent-memory');
await db.store({ content: 'User prefers TypeScript', memoryType: 'semantic', agentId: 'my-agent' });
await db.ingest('User: I switched to Neovim\nAssistant: Noted!');
const results = await db.recall("RECALL memories WHERE tag = 'editor' LIMIT 5");

Architecture

graph TD
    subgraph API["API Layer"]
        MQL["MQL Parser"]
        QE["Query Planner"]
        GRPC["gRPC / REST / MCP"]
    end

    subgraph Extraction["Memory Extraction"]
        LLM["LLM Provider<br/>OpenAI / Anthropic / Ollama"]
        QF["Quality Filter"]
        DEDUP["Deduplication"]
        CONTRA_EX["Contradiction Check"]
    end

    subgraph Cognitive["Cognitive Engine"]
        CTX["Context Assembly<br/>U curve, delta aware"]
        STREAM["Stream Cognition<br/>live push corrections"]
        PAIN["Pain Signals<br/>mistake aversion"]
        PHANTOM["Phantom Memories<br/>knowledge gap tracking"]
    end

    subgraph Intelligence["Inference Layer"]
        BP["Belief Propagation"]
        WI["Write Time Inference"]
        INTERF["Interference Detection"]
    end

    subgraph Index["Index Layer"]
        HNSW["HNSW Vector Index"]
        ROAR["Roaring Bitmap Tags"]
        TEMP["Temporal Index"]
    end

    subgraph Graph["Knowledge Graph"]
        CSR["CSR/CSC Storage"]
        TRAV["BFS / DFS Traversal"]
    end

    subgraph Storage["Storage Engine"]
        BUF["Buffer Pool<br/>CLOCK eviction"]
        WAL["Write Ahead Log<br/>LZ4, crash safe"]
        PAGE["Page Manager<br/>16KB pages"]
    end

    LLM --> QF --> DEDUP --> CONTRA_EX --> WI

    MQL --> QE
    GRPC --> QE
    QE --> CTX
    QE --> Index
    QE --> Graph

    WI --> Graph
    WI --> Index
    BP --> Graph
    INTERF --> Index

    Index --> Storage
    Graph --> Storage

    BUF --> PAGE
    WAL --> PAGE

Crates

MenteDB is organized as a Cargo workspace with 13 crates:

Security

MenteDB includes production security features:

• JWT Authentication on all REST and gRPC endpoints
• Agent Isolation JWT claims enforce per agent data access
• Space ACLs fine grained permissions for multi agent setups
• Admin Keys separate admin authentication for token issuance
• Rate Limiting per agent write rate enforcement
• Embedding Validation dimension mismatch returns errors, not panics

# Production deployment
export MENTEDB_JWT_SECRET="your-secret-here"
export MENTEDB_ADMIN_KEY="your-admin-key"
export MENTEDB_LLM_PROVIDER="openai"
export MENTEDB_LLM_API_KEY="sk-..."

mentedb-server --require-auth --data-dir /var/mentedb/data

LLM Extraction Configuration

Configure the extraction pipeline via environment variables:

MQL Examples

-- Vector similarity search
RECALL memories NEAR [0.12, 0.45, 0.78, 0.33] LIMIT 10

-- Boolean filters with OR and NOT
RECALL memories WHERE type = episodic AND (tag = "backend" OR tag = "frontend") LIMIT 5
RECALL memories WHERE NOT tag = "archived" ORDER BY salience DESC

-- Content similarity
RECALL memories WHERE content ~> "database migration strategies" LIMIT 10

-- Graph traversal
TRAVERSE 550e8400-e29b-41d4-a716-446655440000 DEPTH 3 WHERE edge_type = caused

-- Consolidation
CONSOLIDATE WHERE type = episodic AND accessed < "2024-01-01"

Docker

docker build -t mentedb .
docker run -p 6677:8080 \
  -e MENTEDB_JWT_SECRET=your-secret \
  -e MENTEDB_LLM_PROVIDER=openai \
  -e MENTEDB_LLM_API_KEY=sk-... \
  -v mentedb-data:/data \
  mentedb

Or with docker-compose:

docker-compose up -d

Benchmarks

Quality Benchmarks (5/5 passing)

Mem0 vs MenteDB (head-to-head)

Mem0 returned both "Uses PostgreSQL" (stale) and "Prefers SQLite" (current). MenteDB returned only the current belief. Both used OpenAI text-embedding-3-small for a fair comparison. The correctness gap (PASS vs FAIL) is the more meaningful result.

10K Scale Test (OpenAI text-embedding-3-small)

Candle (Local) vs OpenAI Embedding Quality

Candle provides good quality for zero-config local use. OpenAI offers higher accuracy for production workloads. Run python3 benchmarks/candle_vs_openai.py with OPENAI_API_KEY set to get a head-to-head comparison.

Performance Benchmarks (Criterion)

Context assembly stays sub-millisecond even at 10,000 memories.

Running Benchmarks

# Engine tests (no LLM required)
python3 benchmarks/run_all.py --no-llm

# Full suite (requires ANTHROPIC_API_KEY or OPENAI_API_KEY)
python3 benchmarks/run_all.py

# Mem0 comparison (requires OPENAI_API_KEY)
python3 benchmarks/mem0_comparison.py

# Criterion performance benchmarks
cargo bench

Building

cargo build              # Build all crates
cargo test               # Run 427+ tests
cargo clippy             # Lint
cargo bench              # Benchmarks
cargo doc --open         # Documentation

Contributing

See CONTRIBUTING.md for guidelines.

Found a bug or have a feature request? Open an issue.

License

Apache 2.0, see LICENSE for details.