Related Pages

Related topics: MCP Tools and the process_turn Pipeline, Configuration, Deployment, and Operations

Overview and Architecture

mentedb-mcp is a Model Context Protocol (MCP) server that exposes the MenteDb memory and knowledge-graph engine to LLM agents. It functions as the protocol adapter between MCP-aware clients (such as Claude Code) and the underlying MenteDb storage and retrieval primitives, presenting memory operations as a discoverable, callable tool surface.

Purpose and Scope

The project exists to give LLM agents persistent, searchable, graph-augmented memory without requiring them to call the engine directly. The MCP server wraps MenteDb and re-exports a small set of high-level operations — most importantly process_turn, store_memory, and recall helpers — that agents invoke over the MCP transport. Local mode is shipped by default since v0.5.6, and a cloud backend mode is available as an alternative transport (Source: src/main.rs:1-40).

The crate is intentionally thin: prior to v0.5.2 it contained roughly 820 lines of manual orchestration, but the release notes for v0.5.2 state that "use engine process_turn, remove 820 lines of manual orchestration," shifting responsibility for turn-level logic into the MenteDb engine itself (v0.5.2 release notes). The MCP layer therefore focuses on protocol transport, configuration, and tool registration rather than memory semantics.

Architectural Layers

The codebase is organized into four cooperating modules that form a clean separation between transport, configuration, and engine access:

main.rs reads configuration and decides whether to boot the local in-process engine or hand off to the cloud client. In local mode, it constructs an Arc<MenteDb> (note the v0.4.24 change: "remove Mutex — use Arc<MenteDb> with interior mutability") and hands it to the server module. The shared Arc allows the MCP transport and background enrichment tasks to share the same engine instance safely (Source: src/main.rs:20-60).

config.rs centralizes all environment-driven behavior: local-vs-cloud selection, paths to engine data, enrichment toggles, and the resilience prompt that instructs agents to retry process_turn after failures (added in v0.5.0). Centralizing this in one module prevents drift between the binary entry point and the server handlers (Source: src/config.rs:1-80).

server.rs implements the MCP ServerHandler trait using rmcp ~1.3 and the rmcp-macros 1.3.0 procedural macros for tool registration. The v0.5.0 / v0.4.26 release notes flag that pinning these crates is required for the --features local build to compile. Each tool is a thin wrapper that translates MCP arguments into engine method calls and serializes results back as MCP content (Source: src/server.rs:1-120).

The cloud pair, cloud_client.rs and cloud_server.rs, lets the binary run against a remote MenteDb deployment. The MCP server module is reused; only the engine binding differs — a remote handle replacing the local Arc<MenteDb> (Source: src/cloud_client.rs:1-60).

Tool Surface and Data Flow

The most prominent tool is process_turn, which the engine now drives end-to-end. It accepts a conversational turn and returns retrieved memories, extracted facts, contradictions, and updated graph state. The v0.5.2 release moved sleeptime enrichment into the engine; v0.5.3 then "wired sleeptime enrichment into MCP process_turn," so the MCP tool simply forwards the call and returns the engine's result (Source: src/server.rs:60-140).

Retrieval inside process_turn uses HNSW indexing rather than a linear scan, following the v0.4.24 migration: "migrate MCP from O(n) recall_all_memories to HNSW retrieval." This keeps latency bounded as the memory store grows.

The general request flow:

1. An MCP client (e.g., Claude Code) opens a transport and lists tools (Source: src/main.rs:30-70).
2. The client invokes a tool; server.rs deserializes arguments and calls into the bound MenteDb engine handle (Source: src/server.rs:80-160).
3. The engine executes the operation — for process_turn, this includes extraction, retrieval, contradiction detection via graph().find_all_contradictions (v0.5.2), and optionally community/user-model enrichment phases (v0.5.4) (Source: src/server.rs:100-180).
4. Results are serialized back to MCP content and returned to the client.

Dependencies and Engine Integration

Cargo.toml pins the rmcp ecosystem to ~1.3 and rmcp-macros to 1.3.0, and bumps the MenteDb engine crate to 0.10.0 (v0.5.6). Earlier versions targeted 0.9, which introduced WAL-level locking for multi-process safety (v0.5.5 notes: "Bump mentedb crates to 0.9 (WAL-level locking, multi-process safety)"). The skip_extraction parameter added in v0.5.5 reflects a 0.9 API change in run_enrichment, and store_memory gained a scope parameter in v0.5.6 — both are MCP-visible surface area that must match the engine's API (Source: Cargo.toml:1-60).

The v0.5.7 release added lifecycle hook integration for Claude Code across both the local daemon and cloud backends, allowing the MCP server to participate in session start/stop events in addition to tool calls (v0.5.7 release notes). This widens the architectural role of the server from a pure request handler to a session-aware participant, but does not change the core tool surface.

Related Pages

Related topics: Overview and Architecture, Claude Code Hooks and Local Daemon

MCP Tools and the process_turn Pipeline

Overview

The MCP server in mentedb-mcp exposes a focused set of tools that wrap a long-lived MenteDb engine and present them through the Model Context Protocol. The tool surface lives entirely under src/tools/ and is split by responsibility: a module entry point, a transport-level handler, a dedicated process_turn pipeline split across three files, and a memory module covering explicit storage and recall operations.

src/tools/mod.rs declares the submodules and re-exports the public tool surface to the rest of the binary. src/tools/handler.rs wires the tools into the MCP ServerHandler, including the JSON Schema descriptions that clients see. Because MenteDb is shared across requests, the handler holds an Arc<MenteDb> (introduced in v0.4.24 after removing the previous Mutex) so concurrent tool calls share state without serializing the engine. Source: src/tools/handler.rs

The process_turn Pipeline

process_turn is the centerpiece tool. It accepts a conversation turn from the host agent and runs the full extraction, retrieval, contradiction, and enrichment pipeline before returning synthesized context. In v0.5.2, the implementation was collapsed from ~820 lines of manual orchestration down to a thin wrapper around the engine's own process_turn API. Source: src/tools/process_turn.rs

The pipeline is decomposed across three files:

• process_turn.rs — entry point and request/response shaping for the MCP tool.
• process_turn_analysis.rs — analysis-side steps: turn classification, entity extraction, memory candidate construction, and contradiction detection via graph().find_all_contradictions() (replacing the old get_edges API in v0.5.2).
• process_turn_helpers.rs — shared helpers for formatting, scope merging, and result assembly.

Enrichment is layered on top: v0.5.3 wired sleeptime enrichment into the MCP process_turn, and v0.5.4 added Phase 3 (communities) and Phase 4 (user model). v0.5.5 updated the run_enrichment call to pass skip_extraction for the 0.9 engine API. Source: src/tools/process_turn_helpers.rs, src/tools/process_turn_analysis.rs

A high-level flow:

flowchart LR
  A[MCP process_turn request] --> B[Engine process_turn]
  B --> C[Extraction + Entities]
  C --> D[HNSW Retrieval]
  D --> E[find_all_contradictions]
  E --> F[Sleeptime Enrichment]
  F --> G[Phase 3 Communities]
  G --> H[Phase 4 User Model]
  H --> I[Synthesized Context Response]

Because process_turn is the most failure-prone call (it touches extraction, embedding, and graph code), the tool description instructs agents to always retry after a failure (added in v0.5.0). Source: src/tools/handler.rs

Memory Tools

src/tools/memory.rs covers the explicit, agent-driven memory operations: store_memory and recall/search helpers. v0.4.25 added agent instructions to call store_memory on explicit "remember this" requests, and v0.5.6 added a scope parameter to store_memory so callers can target user-, project-, or session-scoped memories. Source: src/tools/memory.rs

Retrieval migrated from an O(n) recall_all_memories walk to HNSW-based vector retrieval in v0.4.24, which is why the module no longer needs a process-wide Mutex and now shares Arc<MenteDb> freely. Source: src/tools/memory.rs

State, Concurrency, and Resilience

All tools read from the same Arc<MenteDb> held by the handler. Writes go through the engine's WAL-level locking introduced in mentedb 0.9 (v0.5.5), which gave the server multi-process safety. The current engine dependency is 0.10.0 (v0.5.6). Source: src/tools/handler.rs, src/tools/mod.rs

The rmcp crate is pinned to ~1.3 with rmcp-macros 1.3.0 (v0.5.0) so the --features local build stays reproducible. v0.5.7 adds lifecycle hook integration for Claude Code on top of the existing local-daemon and cloud backends, but the tool surface remains defined in src/tools/handler.rs.

Related Pages

Related topics: MCP Tools and the process_turn Pipeline, Configuration, Deployment, and Operations

Claude Code Hooks and Local Daemon

Overview and Purpose

The Claude Code Hooks and Local Daemon subsystem, introduced in v0.5.7 (#83), provides lifecycle hook integration between the MenteDb MCP server and the Claude Code editor. It lets the memory engine react to editor-side events — session start, message turns, tool calls, session stop — and run enrichment or persistence work against either a local in-process daemon or a remote cloud backend.

This subsystem builds on earlier releases: v0.5.2 removed 820 lines of manual orchestration in favor of engine.process_turn, and v0.5.3 wired sleeptime enrichment into that same process_turn flow. The hook layer sits above these engine entry points and gives Claude Code a stable, transport-agnostic surface for triggering them.

Source: src/hook/mod.rs:1-40

Module Layout and Backend Abstraction

The hook subsystem is organized as a thin facade plus a backend trait, mirroring the engine's separation between API surface and storage:

• src/hook/mod.rs re-exports the public hook API, defines the event payload type (HookEvent), and contains the dispatch entry point used by the MCP request loop.
• src/hook/backend.rs defines a HookBackend trait with two implementations — a LocalDaemon backend that delegates to the in-process daemon, and a Cloud backend that forwards events to a remote MenteDb service over HTTP.

This trait-based split is consistent with the project's earlier move away from Mutex<MenteDb> toward Arc<MenteDb> interior mutability (v0.4.24, #62), and it lets the rest of the crate depend on the abstraction rather than a concrete transport.

Source: src/hook/backend.rs:1-60

The Local Daemon

src/daemon.rs hosts the long-lived in-process daemon. It owns the MenteDb engine handle and exposes lifecycle endpoints (start, status, shutdown). When the LocalDaemon backend receives a hook event, it enqueues the corresponding engine step onto the daemon's task queue so that expensive operations — HNSW retrieval, community detection (Phase 3, v0.5.4), user-model enrichment (Phase 4, v0.5.4), contradiction finding — do not block the MCP request loop.

The daemon also enforces the resilience contract documented in v0.5.0: failed process_turn calls should be retried. The local backend wraps daemon calls with this retry policy so that transient storage or lock failures (mitigated upstream by WAL-level locking added in mentedb 0.9, v0.5.5) do not surface to the agent as dropped memories. CLAUDE.md records this contract for agent authors and instructs the model to always retry process_turn after a failure.

Source: src/daemon.rs:1-80, CLAUDE.md:1-40

MCP Tool Surface

src/tools/hook_support.rs exposes MCP tools that agents can call explicitly when they want to interact with the hook system outside the event flow — for example to trigger a manual flush, query hook status, or store a memory with a given scope parameter (the scope argument on store_memory was added in v0.5.6 alongside shipping local mode by default). These tools delegate to the same HookBackend trait used by the event handlers, so behavior is identical regardless of whether work originates from a Claude Code lifecycle event or an explicit agent call.

This unification is what allowed the v0.5.0 "always retry process_turn" instruction to apply uniformly to both the implicit hook path and the explicit tool path, and it is what let v0.4.25's "call store_memory on explicit remember requests" instruction reach the same persistence layer.

Source: src/tools/hook_support.rs:1-50

Event Flow

This flow is bounded: the request loop only awaits the enqueue, while enrichment and storage happen asynchronously on the daemon. Cloud-mode users get the same event semantics, with the cloud backend replacing the local daemon for steps 4–5.

Source: src/hook/mod.rs:40-100, src/hook/backend.rs:60-120, src/daemon.rs:80-160

Related Pages

Related topics: Overview and Architecture, Claude Code Hooks and Local Daemon

Configuration, Deployment, and Operations

mentedb-mcp is a Rust MCP (Model Context Protocol) server that exposes a long-term, HNSW-indexed memory store to LLM agents. Once installed, its day-to-day operation revolves around three concerns: how the binary is built and configured at runtime, how it is registered with MCP clients (Claude Desktop, Cursor, Claude Code), and how it is packaged and distributed to end users via npm.

1. Runtime Configuration and CLI Entry Point

The binary entry point is src/main.rs, which parses command-line flags and selects between two operating modes — a local in-process mode and a remote cloud mode. Starting with v0.5.6 the local mode ships by default, so most deployments run without any extra arguments; the cloud backend is opt-in via CLI flags (--features cloud at build time, plus runtime flags such as --remote/--api-key). Source: src/main.rs:1-60.

Configuration is delegated to src/config.rs, which defines the Config struct loaded from environment variables and CLI arguments. Typical keys include the data directory for the embedded MenteDb engine, the API endpoint for remote backends, and tuning knobs for the HNSW index size and recall depth. Because the engine uses Arc<MenteDb> with interior mutability, no explicit Mutex is required at the server boundary, so multiple concurrent MCP tool calls can share one connection. Source: src/config.rs:10-80.

As of v0.5.5, the underlying mentedb crates were bumped to 0.9, which introduced WAL-level locking and multi-process safety. That release also fixed run_enrichment by adding skip_extraction to align with the 0.9 API. Since v0.5.6, the engine has been moved to 0.10.0. Source: Cargo.toml:20-45.

2. Build Feature Flags

Feature selection happens entirely in Cargo.toml. The two primary features are:

In v0.5.0 the dependency on rmcp ~1.3 and rmcp-macros 1.3.0 was pinned to repair a --features local build, and the project began instructing LLM agents to always retry process_turn after failures — a resilience contract for operators rather than a code change. Source: Cargo.toml:50-75.

3. MCP Client Registration

The repo ships ready-made registration snippets under examples/. Both follow the same shape: declare an MCP server named mentedb, point at either the local target/release/mentedb-mcp binary or the npm-wrapped launcher, and pass any required flags in args.

For Claude Desktop, the snippet in examples/claude_desktop_config.json registers the server under mcpServers. For Cursor, examples/cursor_mcp.json uses the same layout with the Cursor-expected schema. Source: examples/claude_desktop_config.json:1-20, examples/cursor_mcp.json:1-20.

In v0.5.7 a lifecycle-hook integration was added so that Claude Code can start a local daemon on demand and connect to either a local daemon or the cloud backend without restarting the agent. Source: README.md:1-40.

4. npm Distribution and Lifecycle Hooks

The npm package at npm/mentedb-mcp/ is the distribution path of choice for non-Rust users. package.json declares a single bin entry, and a postinstall (or lifecycle) script that downloads the matching prebuilt binary for the host platform. The launcher itself lives at npm/mentedb-mcp/bin/mentedb-mcp and is a small Node shim that resolves the platform-specific binary inside the package. Source: npm/mentedb-mcp/package.json:1-40.

Because the npm wrapper is the surface that Claude Code hooks into, it is also where local-daemon lifecycle management was wired in v0.5.7. Operators do not need to manage a long-running process manually: the npm shim spawns the daemon on first MCP request, hands over the socket, and shuts it down on session end. Source: npm/mentedb-mcp/bin/mentedb-mcp:1-60.

5. Operations: Storage and Resilience

Two operational behaviors matter in production:

• Storage location. The local mode persists HNSW vectors, contradictions, community clusters, and the user-model cache inside the configured data directory. v0.5.4 added Phase 3 (communities) and Phase 4 (user model) of enrichment, both of which write to this directory, so operators should size it accordingly. Source: src/config.rs:40-70.
• Failure handling. Since v0.5.0 the system prompt instructs agents to retry process_turn after any failure, treating transient errors as recoverable. v0.5.2 removed ~820 lines of manual orchestration in favor of the engine's own process_turn, reducing the operational surface area. Source: src/main.rs:60-120.

6. Upgrade Path

Releases follow a straightforward cadence visible in the changelog: each engine bump (0.7.1 → 0.9 → 0.10.0) coincides with a dep refresh, and v0.5.6 introduced Dependabot to keep those bumps automatic. Operators upgrading should: (1) rebuild with cargo build --release, (2) update the mentedb npm dependency if using the npm distribution, and (3) verify the MCP client config still points at the new binary path. Source: Cargo.toml:1-50.

Doramagic Pitfall Log

Found 17 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/nambok/mentedb-mcp

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/nambok/mentedb-mcp

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/nambok/mentedb-mcp

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/nambok/mentedb-mcp

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/nambok/mentedb-mcp

6. Runtime risk: Runtime risk requires verification

• Severity: low
• Finding: Developers should check this performance risk before relying on the project: v0.4.25
• User impact: Upgrade or migration may change expected behavior: v0.4.25
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.4.25. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.4.25

7. Runtime risk: Runtime risk requires verification

• Severity: low
• Finding: Developers should check this performance risk before relying on the project: v0.5.6
• User impact: Upgrade or migration may change expected behavior: v0.5.6
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.5.6. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.5.6

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/nambok/mentedb-mcp

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/nambok/mentedb-mcp

10. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: Developers should check this maintenance risk before relying on the project: v0.4.24
• User impact: Upgrade or migration may change expected behavior: v0.4.24
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.4.24. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.4.24

11. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: Developers should check this maintenance risk before relying on the project: v0.4.26
• User impact: Upgrade or migration may change expected behavior: v0.4.26
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.4.26. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.4.26

12. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: Developers should check this maintenance risk before relying on the project: v0.5.0
• User impact: Upgrade or migration may change expected behavior: v0.5.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.5.0. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.5.0

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using mentedb-mcp with real data or production workflows.

• v0.5.7 - github / github_release
• v0.5.6 - github / github_release
• v0.5.5 - github / github_release
• v0.5.4 - github / github_release
• v0.5.3 - github / github_release
• v0.5.2 - github / github_release
• v0.5.1 - github / github_release
• v0.5.0 - github / github_release
• v0.4.26 - github / github_release
• v0.4.25 - github / github_release
• v0.4.24 - github / github_release
• Configuration risk requires verification - GitHub / issue