# Memory MCP
[](https://www.npmjs.com/package/@whenmoon-afk/memory-mcp)
[](https://github.com/WhenMoon-afk/claude-memory-mcp)
[](https://opensource.org/licenses/MIT)
Local, persistent memory for Claude Desktop and MCP-compatible AI assistants.
> _Part of the [Substratia](https://substratia.io) 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.
## Why Use This?
**Without memory:** Every conversation starts fresh. Claude forgets your preferences, past decisions, and context.
**With memory:** Claude remembers what matters. Your AI becomes a persistent collaborator, not a stateless tool.
| Scenario | Without Memory | With Memory |
|----------|----------------|-------------|
| "What did I decide about the API design?" | "I don't have context about that" | "On Jan 15, you chose REST over GraphQL because..." |
| "Remember I prefer TypeScript" | ❌ Forgotten next session | ✅ Persists forever |
| "What were the key points from our meeting?" | "I wasn't in that conversation" | "You noted 3 action items: ..." |
## Quick Start
### Claude Desktop
Download `memory-mcp.mcpb` from [GitHub Releases](https://github.com/whenmoon-afk/claude-memory-mcp/releases) and double-click to install.
### Claude Code
```bash
claude plugin install github:whenmoon-afk/claude-memory-mcp
```
<details>
<summary><strong>Alternative: Manual JSON Config</strong></summary>
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`
```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"]`
</details>
After installation, **restart Claude Desktop** (quit and reopen).
## Usage Examples
### Storing a Memory
```
You: "Remember that I prefer dark mode in all my applications"
Claude: [calls memory_store]
✓ Stored: User prefers dark mode in all applications
- Entities: [user preferences, UI settings]
- Importance: medium
```
### Recalling Memories
```
You: "What are my UI preferences?"
Claude: [calls memory_recall with query "UI preferences"]
Found 3 relevant memories:
1. User prefers dark mode (stored 2 days ago)
2. User likes minimal interfaces (stored 1 week ago)
3. User wants large fonts for accessibility (stored 2 weeks ago)
```
### Forgetting (Soft Delete)
```
You: "Forget what I said about preferring tabs over spaces"
Claude: [calls memory_forget]
✓ Memory soft-deleted (audit trail preserved)
```
## 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** — Context-aware responses that fit your limits
- **Auto entity extraction** — Memories tagged with relevant entities
- **Soft deletes** — Audit trail preserved for compliance
- **Hybrid scoring** — Recency (30%) + Importance (40%) + Frequency (20%)
- **Multi-word search** — OR expansion finds partial matches (new in v3.0.1!)
## For Teams & Enterprise
Building with AI assistants at scale? Memory MCP can support:
- **Per-project memories** — Isolate context by codebase or workspace
- **Shared team knowledge** — Common patterns, decisions, preferences
- **Audit trails** — Track what was remembered and when
- **Local-first** — Data never leaves your infrastructure
Interested in enterprise features? [Open an issue](https://github.com/WhenMoon-afk/claude-memory-mcp/issues) or contact us at [substratia.io](https://substratia.io).
## 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?
1. Restart Claude Desktop completely (quit and reopen)
2. Verify config file syntax is valid JSON
3. Check that Node.js 18+ is installed: `node --version`
### "Connection closed" on Windows?
Windows requires either:
- The `cmd /c` wrapper 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.
## Contributing
We welcome contributions! Here's how:
1. Fork the repo
2. Create a feature branch (`git checkout -b feat/amazing-feature`)
3. Make your changes
4. Run tests (`npm test`)
5. Commit (`git commit -m 'feat: add amazing feature'`)
6. Push and open a PR
For major changes, please open an issue first to discuss.
## Dependencies
- `@modelcontextprotocol/sdk` - MCP protocol implementation
- `better-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
## Related Projects
Part of the **Substratia** memory infrastructure ecosystem:
- **[momentum](https://github.com/WhenMoon-afk/momentum)** - Instant context recovery (<5ms) for Claude Code
- **[AgentForge](https://substratia.io/builder)** - Visual drag-and-drop agent config builder
- **[Substratia](https://substratia.io)** - Memory infrastructure for AI
## Support
- [GitHub Issues](https://github.com/WhenMoon-afk/claude-memory-mcp/issues) - Bug reports & feature requests
## Privacy
**Local-only**: All memories are stored locally on your machine. No data is sent anywhere. Zero telemetry.
## Disclaimer
This project is provided as-is. It is actively maintained but may have breaking changes between minor versions.
## License
MIT
