memory-mcp

Memory MCP Server

Interact with and troubleshoot the Memory Model Context Protocol (MCP) server for the self-learning memory system.

When to Use

• Starting or configuring the memory-mcp server
• Using MCP tools for memory retrieval and pattern analysis
• Validating the MCP server implementation
• Debugging MCP server issues (connection, tool execution, performance)
• Testing MCP tools using the MCP inspector
• Understanding MCP configuration and environment variables

MCP Server Overview

The memory-mcp server exposes episodic memory functionality through the Model Context Protocol, allowing AI agents to:

• Query past experiences and learned patterns
• Analyze successful strategies from historical episodes
• Execute code in a secure sandbox environment
• Perform advanced statistical and predictive analysis
• Monitor server health and metrics

Location: ./target/release/memory-mcp-server Configuration: .mcp.json Transport: stdio (Standard Input/Output)

Available MCP Tools

1. query_memory

Query episodic memory for relevant past experiences and learned patterns.

Parameters:

• query (required): Search query describing the task or context
• domain (required): Task domain (e.g., 'web-api', 'data-processing')
• task_type (optional): Type of task - code_generation, debugging, refactoring, testing, analysis, documentation
• limit (default: 10): Maximum number of episodes to retrieve

Example:

{
  "query": "implement async storage with error handling",
  "domain": "rust-backend",
  "task_type": "code_generation",
  "limit": 5
}

Use when: You need relevant past experiences to inform current work.

2. analyze_patterns

Analyze patterns from past episodes to identify successful strategies.

Parameters:

• task_type (required): Type of task to analyze patterns for
• min_success_rate (default: 0.7): Minimum success rate (0.0-1.0)
• limit (default: 20): Maximum number of patterns to return

Example:

{
  "task_type": "debugging",
  "min_success_rate": 0.8,
  "limit": 10
}

Use when: You want to identify proven successful approaches for a task type.

3. advanced_pattern_analysis

Perform advanced statistical analysis, predictive modeling, and causal inference on time series data.

Parameters:

• analysis_type (required): statistical, predictive, or comprehensive
• time_series_data (required): Object mapping variable names to numeric arrays
• config (optional): Analysis configuration
  • significance_level (default: 0.05): Statistical significance level
  • forecast_horizon (default: 10): Steps to forecast ahead
  • anomaly_sensitivity (default: 0.5): Anomaly detection sensitivity
  • enable_causal_inference (default: true): Perform causal analysis
  • max_data_points (default: 10000): Maximum data points
  • parallel_processing (default: true): Enable parallel processing

Example:

{
  "analysis_type": "comprehensive",
  "time_series_data": {
    "latency_ms": [120, 115, 130, 125, 140],
    "success_rate": [0.95, 0.98, 0.96, 0.97, 0.99]
  },
  "config": {
    "forecast_horizon": 5,
    "anomaly_sensitivity": 0.6
  }
}

Use when: You need deep statistical insights and predictions from historical data.

4. execute_agent_code

Execute TypeScript/JavaScript code in a secure sandbox environment.

Parameters:

• code (required): TypeScript/JavaScript code to execute
• context (required): Execution context
  • task: Task description
  • input: Input data as JSON object

Example:

{
  "code": "function process(data) { return data.map(x => x * 2); } process(context.input.numbers);",
  "context": {
    "task": "Double all numbers in array",
    "input": { "numbers": [1, 2, 3, 4, 5] }
  }
}

Note: Only available if WASM sandbox is enabled.

Use when: You need to safely execute user-provided or generated code.

5. health_check

Check the health status of the MCP server and its components.

Parameters: None

Use when: Diagnosing server issues or verifying operational status.

6. get_metrics

Get comprehensive monitoring metrics and statistics.

Parameters:

• metric_type (default: "all"): all, performance, episodes, or system

Use when: Monitoring server performance or gathering operational insights.

Configuration

.mcp.json Structure

{
  "mcpServers": {
    "memory-mcp": {
      "type": "stdio",
      "command": "./target/release/memory-mcp-server",
      "args": [],
      "env": {
        "TURSO_DATABASE_URL": "file:/workspaces/feat-phase3/data/memory.db",
        "LOCAL_DATABASE_URL": "sqlite:/workspaces/feat-phase3/data/memory.db",
        "REDB_CACHE_PATH": "/workspaces/feat-phase3/data/cache.redb",
        "REDB_MAX_CACHE_SIZE": "1000",
        "MCP_CACHE_WARMING_ENABLED": "true",
        "MEMORY_MAX_EPISODES_CACHE": "1000",
        "MEMORY_CACHE_TTL_SECONDS": "1800",
        "RUST_LOG": "off"
      }
    }
  }
}

Environment Variables

• TURSO_DATABASE_URL: Primary database URL (file:// for local)
• LOCAL_DATABASE_URL: Local SQLite database URL
• REDB_CACHE_PATH: Path to redb cache file
• REDB_MAX_CACHE_SIZE: Maximum cache entries (default: 1000)
• MCP_CACHE_WARMING_ENABLED: Enable cache warming on startup
• MEMORY_MAX_EPISODES_CACHE: Maximum episodes in cache
• MEMORY_CACHE_TTL_SECONDS: Cache time-to-live in seconds
• RUST_LOG: Logging level (off, error, warn, info, debug, trace)

Starting the MCP Server

Build the Server

cargo build --release --bin memory-mcp-server

Run Directly

# With environment variables
export TURSO_DATABASE_URL="file:./data/memory.db"
export LOCAL_DATABASE_URL="sqlite:./data/memory.db"
export REDB_CACHE_PATH="./data/cache.redb"
export RUST_LOG=info

./target/release/memory-mcp-server

Run via MCP Inspector

The MCP Inspector is the recommended tool for testing and validation.

npx -y @modelcontextprotocol/inspector ./target/release/memory-mcp-server

This opens a web interface at http://localhost:5173 where you can:

• List available tools
• Test tool execution
• View request/response JSON
• Debug connection issues
• Validate tool schemas

See: https://modelcontextprotocol.io/docs/tools/inspector

Validation Workflow

Use the MCP Inspector to validate implementation against best practices:

Step 1: Build and Prepare

cargo build --release --bin memory-mcp-server

Step 2: Launch Inspector

npx -y @modelcontextprotocol/inspector ./target/release/memory-mcp-server

Step 3: Validate Tools

1. List Tools: Click "List Tools" - verify all expected tools appear
2. Check Schemas: Review each tool's input schema for correctness
3. Test Execution: Execute each tool with sample inputs
4. Verify Responses: Confirm responses match expected format

Step 4: Test Core Workflows

• Memory Retrieval: Test query_memory with various domains/task types
• Pattern Analysis: Test analyze_patterns with different success rates
• Advanced Analysis: Test advanced_pattern_analysis with time series data
• Health: Verify health_check returns valid status
• Metrics: Check get_metrics provides comprehensive data

Step 5: Performance Testing

• Test with large datasets
• Verify timeout handling
• Check memory usage
• Monitor response times

Troubleshooting

Common Issues

Server Won't Start

Symptoms: Process exits immediately or hangs

Checks:

1. Binary exists: ls -la ./target/release/memory-mcp-server
2. Binary is executable: chmod +x ./target/release/memory-mcp-server
3. Database files exist: ls -la ./data/
4. Environment variables set: env | grep -E '(TURSO|REDB|RUST_LOG)'

Solutions:

# Rebuild
cargo build --release --bin memory-mcp-server

# Create data directory
mkdir -p ./data

# Set environment variables
export TURSO_DATABASE_URL="file:./data/memory.db"
export LOCAL_DATABASE_URL="sqlite:./data/memory.db"
export REDB_CACHE_PATH="./data/cache.redb"

Tool Execution Fails

Symptoms: Tool returns errors or unexpected results

Checks:

1. Enable debug logging: RUST_LOG=debug
2. Validate input JSON against schema
3. Check database connectivity
4. Verify cache is accessible

Debug Commands:

# Run with debug logging
RUST_LOG=debug ./target/release/memory-mcp-server

# Check database
sqlite3 ./data/memory.db ".tables"

# Verify cache
ls -lh ./data/cache.redb

Performance Issues

Symptoms: Slow responses, timeouts

Checks:

1. Cache size configuration
2. Database size
3. Number of cached episodes
4. Concurrent requests

Solutions:

# Adjust cache settings
export REDB_MAX_CACHE_SIZE="2000"
export MEMORY_MAX_EPISODES_CACHE="2000"

# Reduce cache TTL
export MEMORY_CACHE_TTL_SECONDS="900"

# Disable cache warming if startup is slow
export MCP_CACHE_WARMING_ENABLED="false"

Connection Issues

Symptoms: Inspector can't connect, stdio communication fails

Checks:

1. Server process is running
2. No other process on same stdio
3. Binary path is correct
4. Shell environment is clean

Solutions:

# Kill existing processes
pkill memory-mcp-server

# Verify no zombie processes
ps aux | grep memory-mcp-server

# Restart inspector
npx -y @modelcontextprotocol/inspector ./target/release/memory-mcp-server

Best Practices

Tool Usage

✓ DO:

• Use query_memory before starting new tasks to learn from past experiences
• Set appropriate limit values to avoid over-retrieving
• Specify task_type to get more relevant results
• Use analyze_patterns to identify proven strategies
• Run health_check periodically in production
• Monitor metrics with get_metrics for performance insights

✗ DON'T:

• Query without a clear domain/task context
• Ignore min_success_rate when analyzing patterns

---

Content truncated.