mentedb-mcp 0.4.5

# MenteDB MCP Server

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

The MCP (Model Context Protocol) server for MenteDB, the mind database for AI agents.

[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

## What is this?

This MCP server lets any AI agent (Claude, GPT, Copilot, or any MCP compatible client) use MenteDB as persistent memory. By default, the server exposes **4 essential tools** for clean agent integration. Use `--full-tools` to expose all 32 tools for power users.

## Quick Start

Install and configure in one command:

```bash
npx mentedb-mcp@latest setup copilot
```

That's it. Your agent now has persistent memory. Replace `copilot` with `cursor` or `claude` for other editors.

### Cloud sync (optional)

To sync memories across devices, log in:

```bash
npx mentedb-mcp@latest login
```

Without login, everything works locally in `~/.mentedb/`.

### Alternative: install from crates.io

```bash
cargo install mentedb-mcp
mentedb-mcp setup copilot
```

### Updating

After upgrading, instructions auto-update on server startup. To manually review and confirm changes:

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

The `update` command shows you the exact instructions that will be written and asks for confirmation. If you've customized the MenteDB block, it warns you and creates a `.bak` backup. Your own instructions outside the MenteDB block are always preserved.

## Cloud Sync

MenteDB can sync your local memories to MenteDB Cloud. To authenticate:

```bash
mentedb-mcp login
```

This opens your browser to authorize the CLI. Once authenticated, credentials are saved to `~/.mentedb/cloud.json` and the MCP server will sync with MenteDB Cloud on subsequent runs.

### Manual Configuration

If you prefer manual setup, see the client-specific configs below.

### Claude Desktop

Add to `~/.config/claude/claude_desktop_config.json` (macOS/Linux) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

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

### Cursor

Add to your Cursor MCP configuration:

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

### GitHub Copilot (VS Code)

Add to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "mentedb": {
      "type": "stdio",
      "command": "mentedb-mcp",
      "args": ["--data-dir", "~/.mentedb"]
    }
  }
}
```

### GitHub Copilot CLI

Add to `~/.copilot/mcp-config.json`:

```json
{
  "mcpServers": {
    "mentedb": {
      "command": "mentedb-mcp",
      "args": ["--data-dir", "~/.mentedb"],
      "alwaysAllow": [
        "process_turn", "store_memory", "search_memories", "forget_memory"
      ]
    }
  }
}
```

The `alwaysAllow` list lets memory tools run without approval prompts. By default, only 4 essential tools are exposed. Add `--full-tools` to args to expose all 32 tools.

## Embeddings

The server uses local Candle embeddings by default with the `all-MiniLM-L6-v2` model (384 dimensions). No API key needed for semantic search. The model auto-downloads from Hugging Face on first use (~80MB) and is cached locally. If the download fails (offline), it falls back to hash embeddings.

## LLM Extraction (Optional)

Embeddings power search. For LLM based memory extraction via `ingest_conversation`, you can optionally configure an API key:

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

Supported providers: `openai`, `anthropic`, `ollama`, `mock` (default). Without an API key, `ingest_conversation` uses the mock provider which does basic keyword extraction.

## Default Tools (4 tools)

By default, the server exposes only 4 essential tools for optimal agent compliance:

| Tool | Description |
|------|-------------|
| `process_turn` | **⚠️ Call every turn.** Stores conversation, retrieves context, runs inference, detects contradictions. |
| `store_memory` | Store an important fact with type and tags. |
| `search_memories` | Semantic search by query, or get full content by memory UUID. |
| `forget_memory` | Delete a memory by ID. |

## All Tools (`--full-tools`, 32 tools)

With `--full-tools`, all tools below are also exposed:

### Core Memory (8 tools)

| Tool | Description |
|------|-------------|
| `store_memory` | Store a new memory with content, type, tags, and metadata. Returns the UUID. |
| `get_memory` | Retrieve a memory by UUID with all fields including salience and confidence. |
| `recall_memory` | Recall a specific memory by UUID. Returns content, type, metadata, timestamps. |
| `search_memories` | Semantic similarity search with optional type filtering and result limit. |
| `relate_memories` | Create a typed edge between two memories (caused, contradicts, supports, etc). |
| `forget_memory` | Delete a memory from the database with optional reason. |
| `forget_all` | Delete ALL memories permanently. Requires `confirm='CONFIRM'` safety check. |
| `ingest_conversation` | Extract structured memories from raw conversation text via LLM provider. |

Memory types: `episodic`, `semantic`, `procedural`, `anti_pattern`, `reasoning`, `correction`.

Edge types: `caused`, `before`, `related`, `contradicts`, `supports`, `supersedes`, `derived`, `part_of`.

### Context Assembly (1 tool)

| Tool | Description |
|------|-------------|
| `assemble_context` | Build an optimized context window from memories for a query with a real token budget. Supports `structured`, `compact`, and `delta` output formats. Returns zone allocations and token usage metadata. |

### Knowledge Graph (5 tools)

| Tool | Description |
|------|-------------|
| `get_related` | Traverse relationships from a memory with optional edge type filter and depth. |
| `find_path` | Find the shortest path between two memories in the knowledge graph. |
| `get_subgraph` | Extract all nodes and edges within N hops of a center memory. |
| `find_contradictions` | Find all memories that contradict a given memory via graph edges. |
| `propagate_belief` | Propagate a confidence change through the graph, returning all affected memories. |

### Memory Consolidation (6 tools)

| Tool | Description |
|------|-------------|
| `consolidate_memories` | Cluster similar memories and merge them into consolidated semantic memories. |
| `apply_decay` | Apply time based salience decay to all memories. Configurable half life. |
| `compress_memory` | Extract key sentences from a memory, removing filler. Returns compression ratio. |
| `evaluate_archival` | Categorize all memories into keep, archive, delete, or consolidate decisions. |
| `extract_facts` | Extract structured subject/predicate/object triples from a memory. |
| `gdpr_forget` | GDPR compliant deletion of all memories for a subject with full audit log. |

### Cognitive Systems (12 tools)

| Tool | Description |
|------|-------------|
| `process_turn` | **One call per turn.** Searches context, extracts memories, stores with embeddings, runs inference, tracks trajectory. Returns relevant context, stored IDs, pain warnings, and topic predictions. |
| `record_pain` | Record a negative experience (pain signal) so MenteDB warns on similar contexts. |
| `detect_phantoms` | Scan content for knowledge gaps, entities referenced but not in memory. |
| `resolve_phantom` | Mark a knowledge gap (phantom memory) as resolved. |
| `record_trajectory` | Record a conversation turn for trajectory tracking and topic prediction. |
| `predict_topics` | Predict likely next topics based on the current conversation trajectory. |
| `detect_interference` | Find pairs of memories similar enough to confuse an LLM, with disambiguation hints. |
| `check_stream` | Check LLM output text against known facts for contradictions and reinforcements. |
| `write_inference` | Run write time inference: contradiction detection, edge suggestion, confidence adjustment. |
| `register_entity` | Register an entity for phantom memory detection. |
| `get_cognitive_state` | Full cognitive state snapshot: pain signals, phantoms, trajectory predictions. |
| `get_stats` | Database statistics: version, memory count estimate, operational status. |

## Configuration

### CLI Arguments

```
mentedb-mcp [OPTIONS]

Options:
  --data-dir <PATH>           Data directory path [default: ~/.mentedb]
  --embedding-dim <DIM>       Embedding vector dimension [default: 384]
  --llm-provider <PROVIDER>   LLM provider for extraction: openai, anthropic, ollama, mock [default: mock]
  --llm-api-key <KEY>         API key for the LLM provider (overrides env var)
  --llm-model <MODEL>         Model name override for the LLM provider
  --full-tools                Expose all 32 tools (default: 4 essential tools)
  -h, --help                  Print help
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `MENTEDB_LLM_API_KEY` | Default API key for LLM extraction (also read by `--llm-api-key`) |
| `MENTEDB_LLM_PROVIDER` | LLM provider: `openai`, `anthropic`, `ollama`, `mock` (also read by `--llm-provider`) |
| `MENTEDB_LLM_MODEL` | Model name override for the LLM provider (also read by `--llm-model`) |
| `OPENAI_API_KEY` | Fallback API key when using the OpenAI provider |
| `ANTHROPIC_API_KEY` | Fallback API key when using the Anthropic provider |
| `RUST_LOG` | Logging filter, e.g. `RUST_LOG=mentedb_mcp=debug` |

The server writes logs to both stderr (for MCP clients) and a rolling file at `<data-dir>/mentedb-mcp.log`.

## Resources

MCP resources provide read only access to server state.

| URI | Type | Description |
|-----|------|-------------|
| `mentedb://stats` | Static | Database statistics: version, memory count, operational status |
| `mentedb://memories` | Static | JSON listing of all available tools with names and descriptions |
| `mentedb://memories/{id}` | Template | Full memory content by UUID via direct database lookup |
| `mentedb://cognitive/state` | Template | Cognitive state snapshot: pain signals, phantoms, trajectory |

## Architecture

The server runs on stdio transport using the rmcp framework. It is backed by the MenteDB engine, which is composed of 13 Rust crates covering storage, indexing, graph, context assembly, consolidation, cognitive systems, embedding, and extraction. Cognitive subsystems (pain registry, phantom tracker, trajectory tracker) are initialized at startup and maintained in memory for the lifetime of the server process.

## Issues

Found a bug or have a feature request? [Open an issue](https://github.com/nambok/mentedb-mcp/issues).

## License

Apache-2.0