memory-mcp-server

MCP server for agent memory with fitness-based learning, self-correction, and evolutionary memory management. Extends duckpond-mcp-server with specialized memory tools.

Features

• Darwinian Memory System: Memories have fitness scores that evolve based on usage
• Fitness Tracking: Memories are reinforced when useful, deprecated when outdated
• Self-Correction: Log corrections and create antipatterns to prevent repeat mistakes
• Memory Relations: Link related memories together with typed relationships
• Auto-Archival: Low-fitness memories are automatically archived
• Promotion Candidates: High-fitness memories are flagged for hardwiring into code/config
• DuckDB UI: Optional web UI for exploring your database

Installation

npx memory-mcp-server --help

Configuration

Add to your .mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-server", "--ui"],
      "env": {
        "DUCKPOND_DEFAULT_USER": "claude",
        "DUCKPOND_DATA_DIR": "${HOME}/.duckpond/data"
      }
    }
  }
}

Environment Variables

| Variable | Description | Default | | ----------------------- | ---------------------------------- | ------------------ | | DUCKPOND_DEFAULT_USER | Default user ID for all operations | (required) | | DUCKPOND_DATA_DIR | Directory for persistent storage | ~/.duckpond/data | | DUCKPOND_UI_ENABLED | Enable DuckDB UI via env var | false | | DUCKPOND_MEMORY_LIMIT | DuckDB memory limit | 4GB | | DUCKPOND_THREADS | DuckDB thread count | 4 |

CLI Options

memory-mcp-server [options]

Options:
  -t, --transport <type>     Transport mode: stdio or http (default: "stdio")
  -p, --port <port>          HTTP port (default: "3000")
  --ui                       Enable DuckDB UI
  --ui-port <port>           UI management port (default: "4000")
  --ui-internal-port <port>  DuckDB UI port (default: "4213")

Tools

Memory Tools

| Tool | Description | | --------------------- | ----------------------------------------------- | | remember | Store a new memory with fitness tracking | | recall | Search memories by keyword (auto-tracks access) | | reinforce | Boost memory fitness (+0.1) when it was useful | | deprecate | Reduce memory fitness (×0.5) when outdated | | relate | Create relationships between memories | | list_memories | List all active memories | | get_promotions | Get memories ready to hardwire into code | | decay_fitness | Apply time-based decay to stale memories | | archive_low_fitness | Archive memories below threshold |

Correction Tools

| Tool | Description | | ---------------------- | --------------------------------------------- | | log_correction | Log a correction with lesson learned | | create_antipattern | Create an antipattern memory from correction | | check_antipatterns | Check for relevant antipatterns before a task | | get_corrections | Get recent corrections | | get_correction_stats | Get self-improvement metrics |

Health Tools

| Tool | Description | | -------------- | -------------------------------- | | health_check | Get memory system health status | | get_at_risk | Get memories at risk of archival |

Inherited from duckpond-mcp-server

| Tool | Description | | -------------- | ------------------------------ | | query | Execute SQL and return results | | execute | Run DDL/DML statements | | listUsers | List cached users | | getUserStats | Get database statistics | | isAttached | Check connection status | | detachUser | Free database resources |

Memory Schema

Memory Types

• fact - Verified information
• preference - User/system preferences
• episodic - Decisions and events
• context - Situational context
• antipattern - Things NOT to do

Memory Categories

user, project, decision, system, theory, test, coding, architecture, workflow, config

Fitness System

• Initial: 1.0 (max)
• Reinforce: +0.1 (capped at 1.0)
• Deprecate: ×0.5
• Decay: ×0.95 weekly for stale memories
• At Risk: < 0.4
• Archive: < 0.2

Promotion Criteria

Memories become promotion candidates when:

• Fitness score ≥ 0.9
• Access count ≥ 10 OR reinforcement count ≥ 5

Suggested targets:

• preference → CLAUDE.md
• episodic/decision → Skill or Config
• fact/system → Documentation

Development

# Install dependencies
pnpm install

# Development with watch mode
pnpm dev

# Run tests
pnpm test

# Full validation (format + lint + test + build)
pnpm validate

License

MIT