⚠️ 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. Entity-Centric Memory extracts structured entities (people, pets, places, events) with typed attributes and links them to related memories via knowledge graph edges — so "bought a collar for my Golden Retriever" remembers the breed, not just the collar
3. Quality Filtering rejects low confidence extractions before they hit storage
4. Deduplication checks embedding similarity against existing memories
5. Contradiction Detection flags when new information conflicts with existing beliefs
6. 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
• Entity-Centric Memory Extracts typed entities (person, pet, place, event, item, organization) with structured attributes. Entity resolution merges attributes across mentions. Graph edges link memories to the entities they reference
• Adaptive Multi-Pass Retrieval Engine-level 3-pass search (instant recall → active search → deep dig) with progressively increasing depth, reciprocal rank fusion, and entity graph expansion
• Write Time Intelligence Quality filter, deduplication, and contradiction detection at ingest
• LLM Powered Cognitive Inference CognitiveLlmService judges whether new memories invalidate, update, or are compatible with existing ones (supports Anthropic, OpenAI, Ollama)
• Bi-Temporal Validity Memories and edges carry valid_from/valid_until timestamps. Temporal invalidation instead of deletion. Point-in-time queries via recall_similar_at(embedding, k, timestamp)
• 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

Entity-Centric Memory

Most memory systems store flat text strings. When a user says "I bought a collar for my Golden Retriever like Max", a flat system remembers the collar purchase but loses the breed. MenteDB extracts structured entities with typed attributes:

Entity: MAX (pet)
  breed: Golden Retriever
  ──linked to──> "User bought a collar for their dog Max"
  ──linked to──> "User takes Max to the park on weekends"

How it works:

1. Extraction — The LLM identifies entities (people, pets, places, events, items) and their attributes, even from incidental mentions
2. Resolution — Multiple mentions of the same entity are merged: "Max", "my dog", "the Golden Retriever" all resolve to one entity node
3. Graph linking — PartOf edges connect every memory that mentions an entity back to the entity node
4. Search expansion — When search hits an entity, the engine traverses its subgraph to surface all related memories

This means asking "What breed is my dog?" finds the entity MAX, follows its edges, and returns the breed attribute — even if no single memory explicitly says "my dog is a Golden Retriever".

Performance Targets (10M memories)

Integration Options

1. MCP Server (AI Clients)

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

npx mentedb-mcp@latest setup copilot

Or install from crates.io if you prefer Rust:

cargo install mentedb-mcp
mentedb-mcp setup copilot

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"]
        ENT["Entity Extraction<br/>typed attributes, resolution"]
        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"]
        ENTG["Entity Graph<br/>PartOf edges, resolution"]
    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 --> ENT --> 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)

LLM Accuracy Benchmarks (62 cases)

MenteDB's cognitive layer uses LLM judgment for memory invalidation, contradiction detection, and topic canonicalization. We maintain a curated test suite of 62 cases to validate accuracy across providers.

Three tier design: Works without any LLM (heuristics only), works well with a free local model via Ollama, and achieves perfect accuracy with a cloud API. We strongly recommend configuring your own LLM provider for the best experience.

# Run the accuracy benchmark yourself
LLM_PROVIDER=anthropic LLM_API_KEY=sk-ant-... \
  cargo test -p mentedb-extraction --test llm_accuracy -- --ignored --nocapture

LongMemEval Benchmark

LongMemEval is the standard benchmark for long-term conversational memory systems. It tests 500 questions across 7 categories using real multi-session conversation histories.

MenteDB v0.4.2 — 500 questions, judged by gpt-4o-2024-08-06 (official):

Setup: GPT-4o-mini extraction, text-embedding-3-small embeddings, Claude Sonnet reader. No benchmark files modified — all improvements are engine-side retrieval and synthesis.

# Run it yourself
cd benchmarks/longmemeval
bash run_full_benchmark.sh 0

# Evaluate
OPENAI_API_KEY=... python3 evaluate.py results/hypotheses_full.jsonl

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

# Criterion performance benchmarks
cargo bench

Building

cargo build              # Build all crates
cargo test               # Run 477+ 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.