MCP server for persistent AI memory - store and recall context across sessions
npm install @shodh/memory-mcp

v0.1.70 | Persistent cognitive memory for AI agents
Documentation |
GitHub |
Python SDK |
Rust Crate
---
- Cognitive Architecture: 3-tier memory (working, session, long-term) based on Cowan's model
- Hebbian Learning: "Neurons that fire together wire together" - associations strengthen with use
- Semantic Search: Find memories by meaning using MiniLM-L6 embeddings
- Knowledge Graph: Entity extraction and relationship tracking
- Memory Consolidation: Automatic decay, replay, and strengthening
- 1-Click Install: Auto-downloads native server binary for your platform
- Offline-First: All models auto-downloaded on first run (~38MB total), no internet required after
- Fast: Sub-millisecond graph lookup, 30-50ms semantic search
Add to your MCP client config:
Claude Desktop / Claude Code (claude_desktop_config.json):
``json`
{
"mcpServers": {
"shodh-memory": {
"command": "npx",
"args": ["-y", "@shodh/memory-mcp"],
"env": {
"SHODH_API_KEY": "your-api-key-here"
}
}
}
}
Config file locations:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json
- Windows: ~/.config/Claude/claude_desktop_config.json
- Linux:
Codex CLI (.codex/config.toml):`toml`
[mcp_servers.shodh-memory]
startup_timeout_sec = 60
command = "npx"
args = ["-y", "@shodh/memory-mcp"]
env = { SHODH_API_KEY = "your-api-key-here" }
> Note: First run downloads the server binary (~15MB) plus embedding model (~23MB). The startup_timeout_sec = 60 ensures enough time for initial setup.
For Cursor/other MCP clients: Similar configuration with the npx command.
| Variable | Description | Default |
|----------|-------------|---------|
| SHODH_API_KEY | Required. API key for authentication | - |SHODH_API_URL
| | Backend server URL | http://127.0.0.1:3030 |SHODH_USER_ID
| | User ID for memory isolation | claude-code |SHODH_NO_AUTO_SPAWN
| | Set to true to disable auto-starting the backend | false |SHODH_STREAM
| | Enable/disable streaming ingestion | true |SHODH_PROACTIVE
| | Enable/disable proactive memory surfacing | true |
| Tool | Description |
|------|-------------|
| remember | Store a memory with optional type and tags |recall
| | Semantic search to find relevant memories |proactive_context
| | Auto-surface relevant memories for current context |context_summary
| | Get categorized context for session bootstrap |list_memories
| | List all stored memories |forget
| | Delete a specific memory by ID |forget_by_tags
| | Delete memories matching any of the specified tags |forget_by_date
| | Delete memories within a date range |memory_stats
| | Get statistics about stored memories |recall_by_tags
| | Find memories by tag |recall_by_date
| | Find memories within a date range |verify_index
| | Check vector index health |repair_index
| | Repair orphaned memories |consolidation_report
| | View memory consolidation activity |streaming_status
| | Check WebSocket streaming connection status |
The server exposes a REST API at http://127.0.0.1:3030:
`javascript
// Store a memory
const res = await fetch("http://127.0.0.1:3030/api/remember", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "your-api-key"
},
body: JSON.stringify({
user_id: "my-app",
content: "User prefers dark mode",
memory_type: "Observation",
tags: ["preferences", "ui"]
})
});
// Semantic search
const results = await fetch("http://127.0.0.1:3030/api/recall", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "your-api-key"
},
body: JSON.stringify({
user_id: "my-app",
query: "user preferences",
limit: 5
})
});
`
| Endpoint | Method | Description |
|----------|--------|-------------|
| /health | GET | Health check |/api/remember
| | POST | Store a memory |/api/recall
| | POST | Semantic search |/api/recall/tags
| | POST | Search by tags |/api/recall/date
| | POST | Search by date range |/api/memories
| | POST | List all memories |/api/memory/{id}
| | GET/PUT/DELETE | CRUD operations |/api/context_summary
| | POST | Get context summary |/api/relevant
| | POST | Proactive context surfacing |/api/batch_remember
| | POST | Store multiple memories |/api/upsert
| | POST | Create or update by external_id |/api/graph/{user_id}/stats
| | GET | Knowledge graph statistics |/api/consolidation/report
| | POST | Memory consolidation report |/api/index/verify
| | POST | Verify index integrity |/metrics
| | GET | Prometheus metrics |
1. Install: npx -y @shodh/memory-mcp downloads the packageremember
2. Auto-spawn: On first run, downloads the native server binary (~15MB) and embedding model (~23MB)
3. Connect: MCP client connects to the server via stdio
4. Ready: Start using and recall tools
The backend server runs locally and stores all data on your machine. No cloud dependency.
``
"Remember that the user prefers Rust over Python for systems programming"
"Recall what I know about user's programming preferences"
"What context do you have about this project?"
"List my recent memories"
"Show me the consolidation report"
| Platform | Architecture | Status |
|----------|--------------|--------|
| Linux | x64 | Supported |
| macOS | x64 | Supported |
| macOS | ARM64 (M1/M2) | Supported |
| Windows | x64 | Supported |
- Python SDK: pip install shodh-memory - Native Python bindingscargo add shodh-memory` - Use as a library
- Rust Crate:
- Documentation
- GitHub Repository
- Issue Tracker
Apache-2.0