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

``bash
npx memory-mcp-server --help
`

Configuration

Add to your .mcp.json:

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

$3

| 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 |

$3

`bash
memory-mcp-server [options]

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

Tools

$3

| 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 |

$3

| 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 |

$3

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

$3

| 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

$3

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

$3

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

$3

- 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

$3

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

`bash


Install dependencies

pnpm install

Development with watch mode

pnpm dev

Run tests

pnpm test

Full validation (format + lint + test + build)

pnpm validate
``

License

MIT