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-<current-user-SID>); 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)

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 active memories
2. Session Memory: Current session context
3. Long-Term Memory: Persistent storage with vector indexing

How It Works

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 this MCP server via stdio; backend requests use local IPC when SHODH_IPC_ENDPOINT is set, otherwise HTTP
4. Ready: Start using remember and recall tools
5. Session end: when the host closes stdin (e.g. a Claude Desktop thread switch), the shim finishes any in-flight tool call and writes its response to the still-open stdout before exiting, so a mid-flight request is never silently dropped. Draining is bounded by a grace window; if it elapses the caller receives an explicit error instead of waiting out the host timeout.

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

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