Memory MCP
Local, persistent memory for Claude Desktop and MCP-compatible AI assistants.
Part of the Substratia memory infrastructure ecosystem.
A lightweight MCP server that gives your AI durable, searchable memory — entirely on your machine. Built with TypeScript, SQLite + FTS5, and minimal dependencies.
Quick Start
Claude Desktop
Download memory-mcp.mcpb from GitHub Releases and double-click to install.
Claude Code
claude plugin install github:whenmoon-afk/claude-memory-mcp
Alternative: Manual JSON Config
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "github:whenmoon-afk/claude-memory-mcp"]
}
}
}
Windows may need "command": "cmd", "args": ["/c", "npx", "-y", "github:whenmoon-afk/claude-memory-mcp"]
After installation, restart Claude Desktop (quit and reopen).
Tools
| Tool | Description |
|---|---|
memory_store | Store a memory with auto-summarization and entity extraction |
memory_recall | Search memories with token-aware loading |
memory_forget | Soft-delete a memory (preserves audit trail) |
Features
- FTS5 full-text search (fast, no embeddings needed)
- Token budgeting for context-aware responses
- Automatic entity extraction and summarization
- Soft deletes with provenance tracking
- Hybrid relevance scoring (recency + importance + frequency)
Environment Variables
| Variable | Default | Description |
|---|---|---|
MEMORY_DB_PATH | Platform-specific | Database file location |
DEFAULT_TTL_DAYS | 90 | Default memory expiration |
Troubleshooting
Tools not appearing in Claude Desktop?
- Restart Claude Desktop completely (quit and reopen)
- Verify config file syntax is valid JSON
- Check that Node.js 18+ is installed:
node --version
"Connection closed" on Windows?
Windows requires either:
- The
cmd /cwrapper method (see Windows config above), OR - The full path to
npx.cmd(e.g.,C:\Program Files\nodejs\npx.cmd)
Getting stale cached versions?
The npx github: method bypasses npm cache. Alternatively:
- Clear npm cache:
npm cache clean --force - Use global install for version control
Slow startup with github: method?
First run requires downloading and installing dependencies (can take 30+ seconds). Subsequent runs are faster but still fetch from GitHub. For faster startup, use the global install method.
Dependencies
@modelcontextprotocol/sdk- MCP protocol implementationbetter-sqlite3- Fast native SQLite with FTS5
Links
- npm: https://www.npmjs.com/package/@whenmoon-afk/memory-mcp
- GitHub: https://github.com/WhenMoon-afk/claude-memory-mcp
- Issues: https://github.com/WhenMoon-afk/claude-memory-mcp/issues
Want Cloud Sync?
Substratia Pro (coming soon) adds:
- Cloud sync across all your devices
- Memory dashboard to view/edit what AI remembers
- Automatic backups and disaster recovery
- Team memory sharing
Join the waitlist to get early access.
Related Projects
Part of the Substratia memory infrastructure ecosystem:
- momentum - Instant context recovery (<5ms) for Claude Code
- AgentForge - Visual drag-and-drop agent config builder
- Substratia - Memory infrastructure for AI
Support
- GitHub Issues - Bug reports & feature requests
Privacy Policy
Local-only by default: All memories are stored locally on your machine in ~/.memory-mcp/memory.db. No data is sent anywhere unless you explicitly enable cloud sync.
Cloud sync (optional): If you connect to Substratia Cloud, memories are synced to our servers. See our full privacy policy at https://substratia.io/privacy
What we collect:
- Local mode: Nothing. Zero telemetry.
- Cloud mode: Memory content you choose to sync, usage metrics for service improvement.
Disclaimer
This project is provided as-is. It is actively maintained but may have breaking changes between minor versions.
License
MIT