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

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 (47 total)

| Tool | Description | |------|-------------| | remember | Store a memory with optional type, tags, and metadata | | 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 | | read_memory | Read full content of a specific memory by ID | | forget | Delete a specific memory by ID | | reinforce | Reinforce a memory (boost importance) |

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

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

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

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