智能数据库引擎

Full suite (requires ANTHROPIC_API_KEY or OPENAI_API_KEY)

python3 benchmarks/run_all.py

Installation

Docker (fastest)

docker run -p 6677:6677 \
  -e MENTEDB_LLM_PROVIDER=openai \
  -e MENTEDB_LLM_API_KEY=sk-... \
  -v mentedb-data:/var/mentedb/data \
  ghcr.io/nambok/mentedb:latest

or: pipx install mentedb

```

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 ```

Docker

```bash

Or build from source

docker build -t mentedb . docker run -p 6677:6677 \ -e MENTEDB_JWT_SECRET=your-secret \ -v mentedb-data:/var/mentedb/data \ mentedb

Or with docker-compose:

Building

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

Quick start: an agent that remembers

Memory is one call. process_turn embeds the user message, recalls what is relevant from everything stored so far, saves the turn, and returns the memories to put in your next prompt. Full walkthrough for every stack (cloud vs self-hosted, Python / Node / Rust) is in Build an agent.

Self-hosted, Python:

```python from mentedb import MenteDB

db = MenteDB("./my-agent-memory")

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" LIMIT 20

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

-- Point-in-time recall (bitemporal AS OF): only memories whose validity
-- window contained the timestamp. A fact superseded after t is still
-- returned when you ask "as of" a moment it was true.
RECALL memories WHERE type = semantic AS OF 1700000000 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"

Integration Options

Configuration

All cognitive features are enabled by default. Toggle individually:

use mentedb::{MenteDb, CognitiveConfig};

let config = CognitiveConfig {
    write_inference: true,        // auto-edges, contradiction detection
    decay_on_recall: true,        // time-based salience decay
    pain_tracking: true,          // recurring failure warnings
    interference_detection: true, // confusable memory detection
    phantom_tracking: true,       // missing knowledge gap detection
    speculative_cache: true,      // predictive context pre-assembly
    archival_evaluation: true,    // memory lifecycle management
    ..Default::default()
};
let db = MenteDb::open_with_config("./memory", config)?;

LLM Extraction Configuration

Configure the extraction pipeline via environment variables:

Semantic search, auto-linking, and contradiction detection all depend on real embeddings. The Docker image ships with local Candle embeddings; a plain cargo install mentedb-server falls back to non-semantic hash embeddings and warns loudly at startup — build with --features local-embeddings for full quality.

Python SDK

pip install mentedb

On Debian and Ubuntu systems pip refuses system wide installs (PEP 668). Use a virtual environment or pipx:

```bash python3 -m venv .venv && .venv/bin/pip install mentedb

TypeScript SDK

npm install mentedb

2. REST API

```bash

4. SDKs

Python: pip install mentedb ```python from mentedb import MenteDB

db = MenteDB("./agent-memory") result = db.process_turn( user_message="I switched to Vim", assistant_response="Got it!", turn_id=0, )

Integrations

pip install mentedb-langchain  # LangChain memory provider
pip install mentedb-crewai     # CrewAI memory provider

10K Scale Test (engine latency vs embedding provider)

Run: python3 benchmarks/scale_10k.py candle (local Candle embeddings, no API key). The embedding round trip is timed separately from the engine, so the two are never conflated. A remote provider (OpenAI, Cohere) swaps the local embed for a network call of a few hundred ms, but the engine numbers below are unchanged.

Engine search stays near 1ms at 10,000 memories. An earlier version of this table reported roughly 431ms search: that figure was almost entirely the OpenAI round trip to embed the query, not engine work. Bulk inserts precompute embeddings in one batched provider call and pass them to store(embedding=...), so the per item network round trip is paid once per batch instead of once per memory. To reproduce with OpenAI embeddings, set OPENAI_API_KEY before running.

Candle (Local) vs OpenAI Embedding Quality

The engine search is the same for both providers, so the practical difference is embed latency (local model vs API round trip) and retrieval quality. Candle is zero-config and free but a smaller 384-dim model; OpenAI trades an API round trip for higher accuracy. Run python3 benchmarks/candle_vs_openai.py with OPENAI_API_KEY set for a head-to-head comparison.