Shodh Memory

Shodh-Memory MCP Server

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
• Idempotent: Content-hash dedup — identical memories are never stored twice
• 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: <200ms API response, sub-millisecond graph lookup, 30-50ms semantic search
• GTD Task Management: Full todo system with projects, subtasks, comments, and reminders

Installation

Add to your MCP client config:

Claude Desktop / Claude Code (claude_desktop_config.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):

[mcp_servers.shodh-memory]

startup_timeout_sec = 60 command = "npx" args = ["-y", "@shodh/memory-mcp"] env = { SHODH_API_KEY = "your-api-key-here" }

By default the MCP server talks to the backend over HTTP, which works on every platform. To route ordinary requests over authenticated local IPC instead, add SHODH_IPC_ENDPOINT with a platform-appropriate value. On Windows, use the per-user named pipe printed by the server (normally \\.\pipe\shodh-memory- ); on macOS/Linux, use its absolute Unix socket path (under the platform data directory at shodh/shodh-memory.sock by default). A \\.\pipe\... value on macOS/Linux is rejected rather than silently forwarded to the spawned backend. The auto-spawn path passes an explicitly configured endpoint to the backend so both processes use the same value.

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

Local IPC

When SHODH_IPC_ENDPOINT is set, tool calls, proactive surfacing, health checks, resources, and prompts use local IPC. Each call opens one local connection and exchanges one versioned, newline-delimited JSON request and response. Frames are limited to eight MiB. An empty-auth health challenge first proves the endpoint knows the configured key. Ordinary requests then use HMAC proofs bound to that server instance and request body; the reusable API key is never sent over IPC or written to MCP stdout.

Streaming ingestion remains a WebSocket feature. It is disabled by default in IPC mode because the local protocol is finite request/response. To enable it explicitly, set SHODH_STREAM_WEBSOCKET=true and configure SHODH_API_URL for the server's HTTP WebSocket endpoint. Ordinary operations continue to use IPC.

If SHODH_IPC_ENDPOINT is absent, the MCP server preserves its existing HTTP and WebSocket behavior. When the variable is present, it is an explicit transport selection: an unavailable IPC endpoint is reported rather than silently retried over HTTP.

SHODH_USER_ID remains a logical namespace, as it is over REST. A configured API key has authority across namespaces. Use separate server/key instances when mutually untrusted tenants require an authorization boundary.

MCP Tools (51 total)

Memory — Store, search, and manage memories

Memory previews and truncation. recall, recall_by_tags, and proactive_context return previews of each memory body (default cap: 500 characters). When a body is longer than the cap, the output is truncated with an explicit, honest marker that reports the real lengths and the follow-up call, e.g. …[truncated 500/2340 chars — read_memory(" ") for full]. A preview is never silently cut off — the absence of a marker means you are seeing the complete body. To get complete bodies inline (no markers), pass full_content: true on any of those three tools; this increases token usage, so prefer it for small result sets. read_memory always returns the full, untruncated content.

Todos (GTD) — Task management with projects and subtasks

Projects — Organize todos into groups

Reminders — Time, duration, and context-triggered reminders

System — Health, backups, and diagnostics

REST API (for Developers)

The server exposes a REST API at http://127.0.0.1:3030:

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

Key Endpoints

Cognitive Features

Hebbian Learning

Memories that are frequently accessed together form stronger associations. The system automatically:

• Forms edges between co-retrieved memories
• Strengthens connections with repeated co-activation
• Enables Long-Term Potentiation (LTP) for permanent associations

Memory Consolidation

Background processes maintain memory health:

• Decay: Unused memories gradually lose activation
• Replay: High-value memories are periodically replayed
• Pruning: Weak associations are removed
• Promotion: Important memories move to long-term storage

3-Tier Architecture

Based on Cowan's working memory model:

1. Working Memory: Recent, highly