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

Variable	Description	Default
SHODH_API_KEY	Required. API key for authentication	-
SHODH_IPC_ENABLED	Server listener toggle. The auto-spawned backend honors this value.	true
SHODH_IPC_ENDPOINT	Local endpoint for MCP requests: a Unix socket path (macOS/Linux) or \\.\pipe\name (Windows). When set, ordinary MCP requests use local IPC instead of HTTP. A Windows pipe value on macOS/Linux is rejected.	-
SHODH_IPC_REQUIRED	Fail closed when IPC cannot bind or authenticate. The TypeScript client also requires SHODH_IPC_ENDPOINT when enabled.	false
SHODH_API_URL	Backend server URL	http://127.0.0.1:3030
SHODH_USER_ID	Logical memory namespace; not an authorization tenant	claude-code
SHODH_NO_AUTO_SPAWN	Set to true to disable auto-starting the backend	false
SHODH_STREAM	Enable/disable streaming ingestion	true
SHODH_STREAM_WEBSOCKET	In IPC mode only, explicitly opt into WebSocket streaming through SHODH_API_URL	false
SHODH_PROACTIVE	Enable/disable proactive memory surfacing	true

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

Tool	Description
remember	Store a memory with optional type, tags, and metadata
recall	Semantic search to find relevant memories. Pass full_content: true for complete bodies inline
proactive_context	Auto-surface relevant memories for current context. Pass full_content: true for complete bodies inline
context_summary	Get categorized context for session bootstrap
list_memories	List all stored memories
read_memory	Read full content of a specific memory by ID
forget	Delete a specific memory by ID

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("<id>") 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

Tool	Description
add_todo	Create a task with priority, due date, project, contexts
list_todos	List/search todos with semantic or GTD-style filtering
update_todo	Update task properties (status, priority, notes)
complete_todo	Mark a task as done (auto-creates next for recurring)
delete_todo	Permanently delete a task
reorder_todo	Move a task up or down within its status group
list_subtasks	List subtasks of a parent todo
add_todo_comment	Add a comment to a task (progress, resolution)
list_todo_comments	List all comments on a task
update_todo_comment	Edit an existing comment
delete_todo_comment	Delete a comment
todo_stats	Get todo statistics by status, overdue items

Projects — Organize todos into groups

Tool	Description
add_project	Create a project with optional parent (sub-projects)
list_projects	List all projects with todo counts
archive_project	Archive a project (hidden but restorable)
delete_project	Permanently delete a project

Reminders — Time, duration, and context-triggered reminders

Tool	Description
set_reminder	Set a reminder (time, duration, or keyword trigger)
list_reminders	List pending/triggered/dismissed reminders
dismiss_reminder	Acknowledge a triggered reminder

System — Health, backups, and diagnostics

Tool	Description
memory_stats	Get statistics about stored memories
verify_index	Check vector index integrity
repair_index	Re-index orphaned memories
token_status	Get current session token usage
reset_token_session	Reset token counter for new session
consolidation_report	View memory consolidation activity
backup_create	Create a backup of all memories
backup_list	List available backups
backup_verify	Verify backup integrity (SHA-256)
backup_restore	Restore from a backup
backup_purge	Purge old backups, keep most recent N

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

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

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

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