Memory MCP Integration

MCP (Model Context Protocol) server integration for the self-learning memory system. The server exposes episode lifecycle, memory retrieval, pattern analysis, embeddings, and monitoring tools over JSON-RPC on stdio.

Agent code execution is fail-closed. execute_agent_code is not a working execution backend. It is absent from tool discovery and direct calls are rejected. There is no WASM/Wasmtime/Javy sandbox in production. See ADR-073 and ADR-052.

Features

• MCP Server: JSON-RPC over stdio with tool discovery and a shared tool registry
• Episode Lifecycle Management: Programmatic episode creation, tracking, and completion
• Episode Relationships, Tags, and Handoffs: Knowledge-graph links, tag filtering, checkpoints
• Memory Integration: Query episodic and semantic memory; analyze learned patterns
• Pattern Analysis: Pattern extraction, search, recommendations, and playbooks
• Embeddings Support: Multiple providers (local, OpenAI, Mistral)
• Progressive Tool Disclosure: Tools prioritized based on usage patterns
• Monitoring: Health checks, metrics, rate limiting, and audit logging
• Fail-Closed Code Execution: execute_agent_code is unavailable in production

Code Execution Status

execute_agent_code is a fail-closed, unavailable tool in production:

• It is not advertised by tools/list (no working backend is registered).
• Direct tools/call for it is rejected by the dispatcher in src/bin/server_impl/handlers/call_tool.rs with a JSON-RPC error and the detail "execute_agent_code tool is not available due to WASM sandbox compilation issues".
• The batch dispatcher rejects it identically (src/bin/server_impl/handlers/batch_execute.rs).
• The handler in src/bin/server_impl/tools/memory_handlers.rs additionally audit-logs the attempt and returns "Code execution is no longer available. The WASM sandbox was removed in v0.1.29."
• The WASM/Wasmtime/Javy/rquickjs dependencies and the wasmtime-backend, javy-backend, and wasm-rquickjs feature names were removed in v0.1.29 (ADR-052). They do not exist in this crate today.

Use the supported episode and memory tools instead (see Available Tools), or run agent code in an external runner that you control outside this MCP server.

sandbox-dev (trusted local experimentation only)

A legacy Node.js CodeSandbox still lives in src/sandbox/, but it is compiled only when the non-default sandbox-dev feature is enabled:

cargo test -p do-memory-mcp --features sandbox-dev

sandbox-dev is not a production sandbox and MUST NOT be enabled for untrusted input. It exists solely for trusted local experimentation.

Limits that ARE enforced in this path:

• Execution timeout (max_execution_time_ms) via a Tokio timeout; the child process is killed on drop (kill_on_drop(true)).
• Maximum code length (100 KB) checked before execution.
• Static regex screening of the source for filesystem, network, subprocess, and obvious malicious patterns (see src/sandbox/mod.rs).
• Global shadowing/deletion in the JavaScript wrapper (process, require, module, __dirname, __filename) when those capabilities are disabled.

Limits that are NOT enforced (do not rely on them):

• OS-level isolation: src/sandbox/isolation.rs provides apply_isolation (privilege drop, ulimit, namespaces), but the execution path does not call it.
• Memory limits (max_memory_mb) and CPU limits (max_cpu_percent / max_cpu_seconds) are configuration-only; they are not applied to the child process.
• Output sanitization: stdout/stderr are returned as-is.
• The Node.js process itself is a full interpreter; regex screening is heuristic and can be bypassed by runtime obfuscation.
• There is no runtime capability enforcement for network/filesystem/subprocess; the settings only drive source-pattern checks.

Usage

The server is constructed with a memory system and a sandbox configuration, then served over stdio:

use do_memory_core::SelfLearningMemory;
use do_memory_mcp::{MemoryMCPServer, SandboxConfig};
use std::sync::Arc;
use tokio::sync::Mutex;

async fn build_server(memory: Arc<SelfLearningMemory>) -> anyhow::Result<Arc<Mutex<MemoryMCPServer>>> {
    let server = MemoryMCPServer::new(SandboxConfig::restrictive(), memory).await?;
    Ok(Arc::new(Mutex::new(server)))
}

SelfLearningMemory and its storage backends are initialized by src/bin/server_impl; see src/bin/memory-mcp-server.rs for the full startup path and stdio JSON-RPC loop.

Calling a supported tool

Use episode and memory tools rather than code execution:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "query_memory",
    "arguments": {
      "query": "implement REST API",
      "domain": "web-api",
      "task_type": "code_generation",
      "limit": 10
    }
  }
}

Calling execute_agent_code (fails closed)

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "execute_agent_code",
    "arguments": { "code": "console.log('hello')" }
  }
}

Observed response (production build):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": null,
  "error": {
    "code": -32000,
    "message": "Tool execution failed",
    "data": {
      "details": "execute_agent_code tool is not available due to WASM sandbox compilation issues"
    }
  }
}

Sandbox configuration

SandboxConfig is still accepted at construction (the server is built with SandboxConfig::restrictive() by default) but, without a registered execution backend, it no longer governs any production code path. Treat the timeout, memory, and CPU fields as advisory configuration only.

Available Tools

The MCP server exposes tools grouped into categories, defined in the shared registry (src/server/tools/registry/). Consult the registry and docs/API_REFERENCE.md for the authoritative, current surface.

Episode Lifecycle Management

• create_episode - Start tracking a new task with metadata
• add_episode_step - Log execution steps to track progress
• complete_episode - Finalize episode and trigger learning cycle
• get_episode - Retrieve complete episode details
• get_episode_timeline - Visualize chronological task progression
• update_episode - Update episode details
• delete_episode - Remove episodes permanently (with safeguards)
• checkpoint_episode - Create mid-task checkpoints
• get_handoff_pack / resume_from_handoff - Multi-agent handoff

📖 Complete Episode Lifecycle Documentation

Episode Relationships & Tags

• add_episode_relationship, get_episode_relationships, remove_episode_relationship
• find_related_episodes, check_relationship_exists
• add_episode_tags, get_episode_tags, set_episode_tags, remove_episode_tags
• search_episodes_by_tags
• get_dependency_graph, get_topological_order, validate_no_cycles

📖 Episode Tags Tools

Memory & Query Tools

• query_memory - Query episodic memory for relevant past experiences
• query_semantic_memory - Semantic search using embeddings
• bulk_episodes - Retrieve multiple episodes efficiently

Pattern Analysis

• analyze_patterns - Analyze patterns from past episodes
• advanced_pattern_analysis - Deep pattern analysis with statistical methods
• search_patterns - Search for specific patterns
• recommend_patterns - Get pattern recommendations for tasks
• recommend_playbook - Get actionable playbooks for tasks
• explain_pattern - Explain a specific pattern

Embeddings & Configuration

• configure_embeddings - Configure embedding providers (local, OpenAI, Mistral)
• test_embeddings - Test embedding generation
• generate_embedding - Generate an embedding for supplied text
• search_by_embedding - Search by embedding vector
• embedding_provider_status - Report active provider health

Monitoring & Health

• health_check - Server health and status
• get_metrics - Performance metrics and statistics
• quality_metrics - Episode quality assessment
• record_recommendation_session, record_recommendation_feedback, get_recommendation_stats

Code Execution (fail-closed)

• execute_agent_code - Unavailable / fail-closed. Not a working execution backend; calls are rejected. Use the tools above instead.

Batch Operations Contract Status

The MCP JSON-RPC endpoint supports batch/execute (multi-operation transport). Tool-level batch analytics names are intentionally deferred and not advertised:

• batch_query_episodes
• batch_pattern_analysis
• batch_compare_episodes

These names return Tool not found until dedicated handlers are implemented.

📖 Batch Tool Status (WG-053)

Security

Production security boundaries, authentication, isolation, and audit logging are described in SECURITY.md. In brief:

• Transport is JSON-RPC over stdio; there is no network listener by default.
• OAuth 2.1 bearer-token validation is opt-in via the oauth feature and MCP_OAUTH_* environment variables; when disabled the server logs that OAuth is disabled.
• Per-client token-bucket rate limiting protects against DoS.
• Structured audit logging records security-relevant events, including rejected execute_agent_code attempts.
• Agent code execution is fail-closed; the only in-tree executor is the non-default, trusted-local sandbox-dev path documented above.

Testing

# Run the crate tests
cargo test -p do-memory-mcp

# Include the trusted-development sandbox path (local experimentation only)
cargo test -p do-memory-mcp --features sandbox-dev

Contributing

1. Security first: keep execute_agent_code fail-closed unless an approved backend with enforced controls exists (ADR-073).
2. Test coverage: add tests for both success and failure cases.
3. Documentation: update this README and inline docs; do not reintroduce WASM/Javy production claims.
4. Performance: profile memory/query paths.

License

MIT License - See the repository LICENSE file for details.