Shodh-Memory MCP Server

v0.1.70 | Persistent cognitive memory for AI agents

Documentation |
GitHub |
Python SDK |
Rust Crate

---

Features

- 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

Installation

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
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

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.

Environment Variables

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

MCP Tools (15 total)

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

REST API (for Developers)

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
})
});
`

$3

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

Cognitive Features

$3

1. Install: npx -y @shodh/memory-mcp downloads the package
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 remember and recall tools

The backend server runs locally and stores all data on your machine. No cloud dependency.

Usage Examples

`
"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 Support

| Platform | Architecture | Status |
|----------|--------------|--------|
| Linux | x64 | Supported |
| macOS | x64 | Supported |
| macOS | ARM64 (M1/M2) | Supported |
| Windows | x64 | Supported |

Related Packages

- Python SDK: pip install shodh-memory - Native Python bindings
- Rust Crate: cargo add shodh-memory` - Use as a library

Links

- Documentation
- GitHub Repository
- Issue Tracker

License

Apache-2.0