shodh-memory

Shodh-Memory is an MCP server that provides persistent, offline-capable memory tooling for your AI agents. It exposes a suite of memory and productivity tools (such as remember, recall, proactive_context, list_memories, and memory_stats) that the MCP clients can invoke through standard MCP interfaces. The server runs as a single binary-backed service that stores memories locally, supports decay and Hebbian learning, and surfaces related memories when you recall a item. You can also manage todos, projects, reminders, and system operations via the included 47 MCP tools, all accessible to Claude, Cursor, and other MCP clients. The REST API is available on port 3030 once the server is up, with endpoints prefixed by /api and protected by an API key if you choose to enable one.

Typical usage involves starting the MCP server via npx (or via Docker for production) and then connecting an MCP client to the localhost endpoint. For example, you can add the memory MCP to Claude Code so Claude can read and write memories across sessions. The server also ships a TUI dashboard and a set of commands to inspect and control memory state, offering quick access to memory stores, semantic searches, and graph-based memory relationships. You can run the server locally with no external keys, or deploy to a remote server with your own API keys if you need shared access across multiple clients.

The MCP tools include a memory set: remember, recall, proactive_context, context_summary, list_memories, read_memory, forget, and reinforce; GTD-style tasks via todos; project management; reminders; and a broad set of system utilities like memory_stats, verify_index, repair_index, token_status, and backups. With REST endpoints at http://localhost:3030/api, you can script interactions or integrate memory operations into external tooling.

Prerequisites:

• Node.js and npm (or npx available) for running the MCP client commands
• Optional Docker if you prefer container deployment
• Optional Docker volume setup for persistent data (e.g., shodh-data)

Install & run (Node-based, MCP client):

1. Ensure Node.js and npm are installed

   • macOS/Linux: curl -fsSL https://deb.nodesource.com/setup_18.x | bash - sudo apt-get install -y nodejs
   • verify: node -v and npm -v

2. Start the MCP server using npx (no local install required):

   • npx -y @shodh/memory-mcp This downloads and runs the MCP server binary for Shodh-Memory and starts listening for MCP clients.

3. Connect your MCP client (example command shown in the README):

   • Claude Code: claude mcp add shodh-memory -- npx -y @shodh/memory-mcp

Optional Docker deployment (production / shared servers):

1. Run the container with a persistent data volume: docker run -d -p 3030:3030 -v shodh-data:/data varunshodh/shodh-memory

2. Connect Claude or other MCP clients as above, pointing to the same MCP server URL.

Notes:

• For local development, no API key is required. For remote deployments, you may set SHODH_API_KEY through environment variables or your orchestration platform.
• If you plan to run more than one MCP client against the server, consider using Docker or a hosted deployment and set appropriate API keys and host bindings.

Environment variables and configuration:

• SHODH_API_KEY: Optional API key for remote deployments. Not required for local usage.
• SHODH_HOST / SHODH_PORT: Bind address and port for the REST API (default: localhost:3030).
• SHODH_MEMORY_PATH: Storage path for memory data (used in production setups).

Common issues:

• If the MCP server fails to start, ensure Node.js is accessible (npx has network access to fetch the package).
• When using Docker, ensure the host port (3030) is not in use by another service.
• For remote access, verify that API keys are supplied to clients and that CORS or network policies allow connections to port 3030.