MenteDB

https://mentedb.com/docs
Admin
MenteDB is a Rust-based database purpose-built for AI agent memory, featuring HNSW indexing,...
Tokens:6,031
Snippets:73
Trust Score:2.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### MenteDB Python Quick Start

Source: https://mentedb.com/docs

A quick start example demonstrating MenteDB initialization, LLM configuration, storing and searching memories, creating relationships, and retrieving/deleting memories in Python. Enabling an LLM provider is recommended for enhanced cognitive inference.

```python
import os
from mentedb import MenteDB

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

# Enable LLM-powered cognition (optional but recommended)
# Unlocks contradiction detection, temporal invalidation, entity resolution
db.configure_llm(
    provider="anthropic",             # or "openai", "ollama"
    api_key=os.getenv("MENTEDB_LLM_API_KEY"),  # not needed for ollama
)

# Store memories with types
db.store("User prefers Python for backend work", memory_type="semantic", tags=["preference", "language"])
db.store("Sprint planning meeting scheduled Friday", memory_type="episodic", tags=["meeting"])

# Search by text (uses hash embedding)
results = db.search_text("programming language preference", k=5)

# Create relationships
mem1 = db.store("User prefers PostgreSQL", memory_type="semantic")
mem2 = db.store("User switched to SQLite", memory_type="semantic")
db.relate(mem2, mem1, "supersedes", weight=1.0)

# Retrieve a specific memory
memory = db.get_memory(mem1)

# Delete a memory
db.forget(mem1)
```

--------------------------------

### Execute MQL Queries

Source: https://mentedb.com/docs

Examples of MQL syntax for filtering by tags, fuzzy text matching, and vector similarity search.

```mql
RECALL memories WHERE tag = preference LIMIT 5

RECALL memories WHERE content ~> "database" LIMIT 10

RECALL memories NEAR [0.1, 0.2, ...] LIMIT 10
```

--------------------------------

### Install MenteDB MCP Server

Source: https://mentedb.com/docs

Install the MenteDB MCP server using Cargo.

```bash
cargo install mentedb-mcp
```

--------------------------------

### Quick Setup for GitHub Copilot CLI

Source: https://mentedb.com/docs

Automatically configure MenteDB for GitHub Copilot CLI. This command sets up the MCP config, agent instructions, and alwaysAllow list.

```bash
mentedb-mcp setup copilot
```

--------------------------------

### Rust API Reference

Source: https://mentedb.com/docs

Rust code examples for interacting with MenteDB core storage engine.

```APIDOC
## Rust API

### Description
The Rust API provides direct access to the core storage engine.

### Example Usage
```rust
use mentedb::MenteDb;
use mentedb_cognitive::CognitiveLlmService;
use mentedb_extraction::{ExtractionLlmJudge, HttpExtractionProvider, ExtractionConfig};

let mut db = MenteDb::open("./data")?;

// Enable LLM-powered cognition (optional but recommended)
// Choose your provider: OpenAI, Anthropic, or local Ollama
let config = ExtractionConfig::anthropic(std::env::var("ANTHROPIC_API_KEY")?);
// let config = ExtractionConfig::openai(std::env::var("OPENAI_API_KEY")?);
// let config = ExtractionConfig::ollama(); // no API key needed

let provider = HttpExtractionProvider::new(config)?;
let judge = ExtractionLlmJudge::new(provider);
let llm = CognitiveLlmService::new(judge);

// Store a memory node
let id = db.store(memory_node)?;

// Search by similarity
let results = db.recall_similar(&embedding, k)?;

// Retrieve by ID
let node = db.get_memory(id)?;

// Delete a memory
db.forget(id)?;

// Create a relationship
db.relate(edge)?;
```
```

--------------------------------

### Quick Setup for Claude Desktop

Source: https://mentedb.com/docs

Automatically configure MenteDB for Claude Desktop. This command sets up the MCP config, agent instructions, and alwaysAllow list.

```bash
mentedb-mcp setup claude
```

--------------------------------

### Install MenteDB with Python

Source: https://mentedb.com/docs

Install the MenteDB Python package using pip.

```bash
pip install mentedb
```

--------------------------------

### Install MenteDB TypeScript/Node.js SDK

Source: https://mentedb.com/docs

Install the MenteDB SDK for TypeScript and Node.js using npm.

```bash
npm install @mentedb/sdk
```

--------------------------------

### Quick Setup for Cursor

Source: https://mentedb.com/docs

Automatically configure MenteDB for Cursor. This command sets up the MCP config, agent instructions, and alwaysAllow list.

```bash
mentedb-mcp setup cursor
```

--------------------------------

### Run MenteDB MCP Server with Ollama LLM

Source: https://mentedb.com/docs

Run the MenteDB MCP server using Ollama for free, local LLM inference. No API key is needed. Ensure Ollama is installed and the model is pulled.

```bash
# With Ollama (free, local)
mentedb-mcp --data-dir ~/.mentedb --llm-provider ollama
```

--------------------------------

### Initialize and Manage MenteDB in Rust

Source: https://mentedb.com/docs

Demonstrates opening a database, configuring LLM services, and performing basic CRUD and search operations using the Rust SDK.

```rust
use mentedb::MenteDb;
use mentedb_cognitive::CognitiveLlmService;
use mentedb_extraction::{ExtractionLlmJudge, HttpExtractionProvider, ExtractionConfig};

let mut db = MenteDb::open("./data")?;

// Enable LLM-powered cognition (optional but recommended)
// Choose your provider: OpenAI, Anthropic, or local Ollama
let config = ExtractionConfig::anthropic(std::env::var("ANTHROPIC_API_KEY")?);
// let config = ExtractionConfig::openai(std::env::var("OPENAI_API_KEY")?);
// let config = ExtractionConfig::ollama(); // no API key needed

let provider = HttpExtractionProvider::new(config)?;
let judge = ExtractionLlmJudge::new(provider);
let llm = CognitiveLlmService::new(judge);

// Store a memory node
let id = db.store(memory_node)?;

// Search by similarity
let results = db.recall_similar(&embedding, k)?;

// Retrieve by ID
let node = db.get_memory(id)?;

// Delete a memory
db.forget(id)?;

// Create a relationship
db.relate(edge)?;
```

--------------------------------

### Initialize and Manage MenteDB in Node.js

Source: https://mentedb.com/docs

Shows how to use the TypeScript SDK to configure LLM services and perform memory operations.

```typescript
import { MenteDB } from "@mentedb/sdk";

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

// Enable LLM-powered cognition (optional but recommended)
db.configureLlm({
  provider: "anthropic",  // or "openai", "ollama"
  apiKey: process.env.MENTEDB_LLM_API_KEY,
});

// Store a memory
const id = await db.store("User prefers TypeScript", {
  memoryType: "semantic",
  tags: ["preference", "language"],
});

// Search by text
const results = await db.searchText("language preference", { k: 5 });

// Create a relationship
await db.relate(newId, oldId, "supersedes");

// Retrieve a memory
const memory = await db.getMemory(id);

// Delete a memory
await db.forget(id);
```

--------------------------------

### Context Assembly

Source: https://mentedb.com/docs

The ContextAssembler builds optimized context windows for LLM consumption.

```APIDOC
## Context Assembly

### Description
The ContextAssembler builds optimized context windows for LLM consumption.

### U-Curve Ordering
Places high-salience memories at the start and end of the context window, where LLM attention is strongest. Lower priority items go in the middle.
```

--------------------------------

### Run MenteDB MCP Server with OpenAI LLM

Source: https://mentedb.com/docs

Run the MenteDB MCP server using OpenAI for LLM services. Ensure your API key is set.

```bash
# With OpenAI
mentedb-mcp --data-dir ~/.mentedb --llm-provider openai
```

--------------------------------

### Configure MenteDB MCP Server

Source: https://mentedb.com/docs

Define the MCP server configuration in ~/.copilot/mcp-config.json to enable memory tools without approval prompts.

```json
{
  "mcpServers": {
    "mentedb": {
      "command": "mentedb-mcp",
      "args": ["--data-dir", "~/.mentedb", "--llm-provider", "anthropic"],
      "env": {
        "MENTEDB_LLM_API_KEY": "sk-ant-..."
      },
      "alwaysAllow": [
        "process_turn", "store_memory",
        "search_memories", "forget_memory"
      ]
    }
  }
}
```

--------------------------------

### Update MenteDB MCP Server Agent Instructions

Source: https://mentedb.com/docs

Manually update agent instructions for the MenteDB MCP server after upgrading the `mentedb-mcp` binary. This command shows the exact instructions to be written and prompts for confirmation.

```bash
mentedb-mcp update copilot
```

--------------------------------

### Run MenteDB MCP Server with Anthropic LLM

Source: https://mentedb.com/docs

Run the MenteDB MCP server using Anthropic for LLM services. This is recommended for best accuracy. Ensure your API key is set.

```bash
# With Anthropic (recommended for best accuracy)
mentedb-mcp --data-dir ~/.mentedb --llm-provider anthropic
```

--------------------------------

### Node.js API Reference

Source: https://mentedb.com/docs

TypeScript SDK for a native Node.js interface to MenteDB.

```APIDOC
## Node.js API

### Description
The TypeScript SDK provides a native Node.js interface to MenteDB.

### Example Usage
```typescript
import { MenteDB } from "@mentedb/sdk";

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

// Enable LLM-powered cognition (optional but recommended)
db.configureLlm({
  provider: "anthropic",  // or "openai", "ollama"
  apiKey: process.env.MENTEDB_LLM_API_KEY,
});

// Store a memory
const id = await db.store("User prefers TypeScript", {
  memoryType: "semantic",
  tags: ["preference", "language"],
});

// Search by text
const results = await db.searchText("language preference", { k: 5 });

// Create a relationship
await db.relate(newId, oldId, "supersedes");

// Retrieve a memory
const memory = await db.getMemory(id);

// Delete a memory
await db.forget(id);
```
```

--------------------------------

### Define Agent Memory Instructions

Source: https://mentedb.com/docs

System instructions for LLMs to utilize MenteDB memory tools, including mandatory turn processing and memory management guidelines.

```markdown
# Memory

You have persistent memory via MenteDB. You have 4 tools — use them.

## ⚠️ process_turn — CALL EVERY TURN

Call `process_turn` BEFORE responding, on EVERY turn. Pass `user_message` and `assistant_response`.
- It stores the conversation, searches past context, runs inference, and detects contradictions.
- Without this call, nothing is remembered.
- Increment `turn_id` each turn (start at 0).

## USE the returned context

When `process_turn` returns:
- **context**: Truncated summaries with IDs from past conversations. Reference them in your response. Call `search_memories(id)` for full content.
- **pain_warnings**: If non-empty, WARN the user — a similar situation caused problems before.
- **contradictions**: If > 0, flag the inconsistency.

## store_memory — Save important facts

When you notice important information, call `store_memory`:
- **Preferences**: "User prefers Rust" → type: semantic, tags: [preference]
- **Decisions**: "Using PostgreSQL" → type: semantic, tags: [decision]
- **Corrections**: "Deadline is April, not March" → type: correction
- **Procedures**: "Deploy with: cargo build --release" → type: procedural
- **Mistakes**: "Never retag releases" → type: anti_pattern

Don't store chitchat. Store facts, preferences, decisions, corrections.

## search_memories — Look things up

Pass a text query to search by similarity, or a memory UUID to get full content.
Use proactively — if the user mentions a project, search for what you know about it.

## forget_memory — Delete memories

When the user says "forget" or "don't remember that", delete the memory by ID.
```

--------------------------------

### Run MenteDB MCP Server without LLM

Source: https://mentedb.com/docs

Run the MenteDB MCP server using only basic heuristics, without an LLM provider. This limits advanced memory quality features.

```bash
# Without LLM (heuristics only)
mentedb-mcp --data-dir ~/.mentedb
```

--------------------------------

### Python API Reference

Source: https://mentedb.com/docs

Python methods for interacting with MenteDB.

```APIDOC
## MenteDB(path: str)

### Description
Open or create a database at the given path.

### Returns
MenteDB instance

## configure_llm(provider: str, api_key: str | None = None, model: str | None = None)

### Description
Enable LLM-powered cognition. Provider can be 'anthropic', 'openai', or 'ollama'. API key is required for cloud providers (reads MENTEDB_LLM_API_KEY env var as fallback). Unlocks contradiction detection, entity resolution, temporal invalidation, and topic canonicalization.

### Returns
None

## store(content: str, memory_type: str, tags: list[str] = [], embedding: list[float] | None = None, agent_id: str | None = None)

### Description
Store a new memory.

### Returns
str (UUID) - The UUID of the created memory.

## search_text(query: str, k: int)

### Description
Search memories by text content using hash embedding.

### Returns
list[SearchResult] (id, score)

## search(embedding: list[float], k: int)

### Description
Search memories by raw vector embedding.

### Returns
list[SearchResult] (id, score)

## relate(source_id: str, target_id: str, edge_type: str, weight: float = 1.0)

### Description
Create a relationship between two memories.

### Returns
None

## forget(memory_id: str)

### Description
Delete a memory by its ID.

### Returns
None

## get_memory(memory_id: str)

### Description
Retrieve a specific memory by ID.

### Returns
dict (id, content, memory_type, tags, created_at)

## recall(mql_query: str)

### Description
Execute an MQL query against the database.

### Returns
RecallResult (text, total_tokens, memory_count)

## ingest(conversation: str, provider: str | None = None, agent_id: str | None = None)

### Description
Extract and store memories from a conversation transcript.

### Returns
None
```

--------------------------------

### MQL Query Language

Source: https://mentedb.com/docs

MQL (Mente Query Language) is a SQL-inspired query language for searching and retrieving memories.

```APIDOC
## MQL Query Language

### Description
MQL (Mente Query Language) is a SQL-inspired query language for searching and retrieving memories.

### Examples
```mql
RECALL memories WHERE tag = preference LIMIT 5

RECALL memories WHERE content ~> "database" LIMIT 10

RECALL memories NEAR [0.1, 0.2, ...] LIMIT 10
```

### Clauses
- `WHERE tag = value`: Filter memories by tag.
- `WHERE content ~> "text"`: Fuzzy text search within memory content.
- `NEAR [vector]`: Vector similarity search using an embedding.
- `LIMIT n`: Restrict the number of results returned.
```

--------------------------------

### Set MenteDB LLM API Key for OpenAI

Source: https://mentedb.com/docs

Set the MenteDB LLM API key for OpenAI. This enables intelligent features like contradiction detection and topic understanding.

```bash
export MENTEDB_LLM_API_KEY="sk-..."       # OpenAI
```

--------------------------------

### Add MenteDB Rust Crate

Source: https://mentedb.com/docs

Add the MenteDB Rust crate to your Cargo project.

```bash
cargo add mentedb
```

--------------------------------

### Set MenteDB LLM API Key for Anthropic

Source: https://mentedb.com/docs

Set the MenteDB LLM API key for Anthropic. This enables intelligent features like contradiction detection and topic understanding.

```bash
# Set your API key (pick one)
export MENTEDB_LLM_API_KEY="sk-ant-..."   # Anthropic
```

--------------------------------

### Claude Desktop MCP Server Configuration

Source: https://mentedb.com/docs

JSON configuration for MenteDB MCP server when used with Claude Desktop. Specifies the command, arguments, and environment variables, including the Anthropic API key.

```json
{
  "mcpServers": {
    "mentedb": {
      "command": "mentedb-mcp",
      "args": ["--data-dir", "~/.mentedb", "--llm-provider", "anthropic"],
      "env": {
        "MENTEDB_LLM_API_KEY": "sk-ant-..."
      }
    }
  }
}
```

--------------------------------

### Graph Relationships

Source: https://mentedb.com/docs

Memories form a directed graph through typed, weighted edges.

```APIDOC
## Graph Relationships

### Description
Memories form a directed graph through typed, weighted edges.

### Edge Types
| Edge Type     | Description                     | Belief Effect |
|---------------|---------------------------------|---------------|
| `supersedes`  | Newer memory replaces an older one | Target marked stale |
| `contradicts` | Memory conflicts with another   | Target marked stale |
| `supports`    | Memory reinforces another       | Increases salience |
| `related_to`  | General association             | None          |
| `caused_by`   | Causal relationship             | None          |
| `temporal_next`| Sequential ordering             | None          |

### Weight
Weight ranges from 0.0 to 1.0, representing the strength of the relationship.

### Belief Propagation
Supersedes and contradicts edges automatically mark their targets as stale, removing them from search results.

### Graph Traversal
Allows finding paths between memories, extracting subgraphs, and discovering related memories through edge traversal.
```
Tokens:
Raw