# varun29ankuS/shodh-memory [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/varun29ankuS/shodh-memory  
**GitHub Stars:** 281  
**npm Downloads (last month):** 304  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/varun29ankus-shodh-memory

## Description
Cognitive memory for AI agents with Hebbian learning, 3-tier architecture, and knowledge graphs. Single 15MB binary, runs offline on edge devices.

## Tools
Capabilities this server exposes over MCP:

- **remember** — Store a memory for future recall. Use this to remember important information, decisions, user preferences, project context, or anything you want to recall later.
- **recall** — Search memories AND todos using semantic similarity. Returns both relevant memories and matching todos. Use this to find past experiences, decisions, context, or pending work. Modes: 'semantic' (vector similarity), 'associative' (graph traversal), 'temporal' (time-based retrieval), 'hybrid' (combined), 'spatial' (geo-location based), 'mission' (mission context), 'action_outcome' (reward-based learning).
- **recall_by_tags** — Find memories by tags. Returns memories matching ANY of the provided tags. Useful for finding memories by category (e.g., 'tool:Edit', 'file:src/main.rs', 'source:hook', 'error', 'session-summary').
- **context_summary** — Get a condensed summary of recent learnings, decisions, and context. Use this at the start of a session to quickly understand what you've learned before.
- **list_memories** — List all stored memories
- **forget** — Delete a specific memory by ID
- **memory_stats** — Get statistics about stored memories
- **verify_index** — Verify vector index integrity - diagnose orphaned memories that are stored but not searchable. Returns health status and count of orphaned memories.
- **repair_index** — Repair vector index by re-indexing orphaned memories. Use this when verify_index shows unhealthy status. Returns count of repaired memories.
- **backup_create** — Create a backup of all memories. Returns backup metadata including ID, size, and checksum. Backups are stored locally and can be restored later.
- **backup_list** — List all available backups for this user. Returns backup history with IDs, timestamps, and sizes.
- **backup_verify** — Verify backup integrity using SHA-256 checksum. Use to check if a backup is corrupted before restoring.
- **backup_purge** — Purge old backups, keeping only the most recent N. Useful for managing disk space.
- **backup_restore** — Restore a previously created backup by ID. This replaces all current data for the user with the backup contents. Server restart is recommended after restore.
- **consolidation_report** — Get a report of what the memory system has been learning. Shows memory strengthening/decay events, edge formation, fact extraction, and maintenance cycles. Use this to understand how your memories are evolving.
- **proactive_context** — REQUIRED: Call this tool with EVERY user message to surface relevant memories and build conversation history. Pass the user's message as context. This enables: (1) retrieving memories relevant to what the user is asking, (2) building persistent memory of the conversation for future sessions. The system analyzes entities, semantic similarity, and recency to find contextually appropriate memories. Auto-ingest stores the context automatically. USAGE: Always call this FIRST when you receive a user message, passing their message as the context parameter.
- **token_status** — Get current token usage status for this session. Returns tokens used, budget remaining, and percentage consumed. Use this to check context window health.
- **reset_token_session** — Reset the token counter for a new session. Call this when starting a new conversation or after context has been compressed/summarized.
- **set_reminder** — Set a reminder for the future. Triggers on time (at specific time or after duration) or context match (when keywords appear in conversation). Reminders will surface automatically when conditions are met.
- **list_reminders** — List all pending reminders. Use to check what reminders are scheduled.
- **dismiss_reminder** — Dismiss/acknowledge a triggered reminder. Call this after you've handled a reminder.
- **add_todo** — Add a task to your todo list. Supports GTD workflow with projects, contexts (@computer, @phone), priorities, due dates, and subtasks (via parent_id).
- **list_todos** — List or search todos. Supports semantic search via query parameter, or GTD-style filtering. Returns Linear-style formatted output grouped by status.
- **update_todo** — Update a todo's properties. Use short ID prefix (e.g., SHO-1a2b) or full ID.
- **complete_todo** — Mark a todo as complete. For recurring tasks, automatically creates the next occurrence.
- **delete_todo** — Delete a todo permanently.
- **reorder_todo** — Move a todo up or down within its status group. Use to prioritize tasks manually.
- **add_project** — Create a new project to group todos. Use parent to create a sub-project under another project.
- **list_projects** — List all projects with todo counts and status breakdown.
- **archive_project** — Archive a project. Archived projects are hidden by default but can be restored.
- **delete_project** — Permanently delete a project. Use delete_todos=true to also delete all todos in the project.
- **todo_stats** — Get statistics about your todos - counts by status, overdue items, etc.
- **list_subtasks** — List subtasks of a parent todo. Use add_todo with parent_id to create subtasks.
- **add_todo_comment** — Add a comment to a todo. Use to track progress, notes, or resolution details.
- **list_todo_comments** — List all comments and activity history for a specific todo.
- **update_todo_comment** — Update an existing comment on a todo.
- **delete_todo_comment** — Delete a comment from a todo.
- **read_memory** — Read the FULL content of a specific memory by ID. Use this when you need to see the complete text of a memory that was truncated in search results.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "shodh-memory": {
    "command": "npx",
    "args": ["-y","@shodh/memory-mcp"]
  }
}
```

## Documentation

## What varun29ankuS/shodh-memory MCP server does

varun29ankuS/shodh-memory MCP server adds persistent memory and task management to MCP clients. Agents can save decisions, preferences, project details, and other context with `remember`, then retrieve it through semantic, associative, temporal, hybrid, spatial, mission, or action-outcome recall modes. Tag searches, recent-context summaries, memory statistics, and memory listing support inspection and targeted retrieval.

The server also exposes reminders and a GTD-oriented todo system. Agents can create projects and tasks, assign priorities, contexts, due dates, and subtasks, then search, reorder, complete, update, archive, or delete them. Recurring todos create their next occurrence when completed.

## How it works

Storage and retrieval run locally rather than sending content to an LLM or a hosted database. The system uses on-device MiniLM embeddings through ONNX Runtime for semantic search. It can extract entities with a local GLiNER model, fall back to rules, and build typed graph relationships from text. Graph traversal supports related-memory retrieval and causal tracing.

Memory is organized into working, session, and long-term tiers. Frequently used memories receive stronger activation, while unused information decays. Recalling one item can activate related items, and repeated connection use can preserve those relationships. Content-hash deduplication prevents identical memories from being stored twice.

The `proactive_context` tool is intended to run first for every user message. It accepts the message as context, retrieves relevant prior information, and automatically ingests the context for future sessions. Token tools report session usage and can reset the counter after a new or compressed conversation.

## Setup and configuration

For an MCP client, install the published npm wrapper with:

```bash
npx -y @shodh/memory-mcp
```

A Claude Desktop or Cursor configuration can run that command with `-y` and `@shodh/memory-mcp` as its arguments. Local operation needs no API key; the local setup generates one automatically. Remote deployments can pass a `SHODH_API_KEY` value to authenticate access.

The project also documents a unified `shodh` CLI, Python installation, Rust usage, and Docker deployment. The standalone server can listen on port 3030 in the documented Docker example, with a mounted volume used for data persistence. The MCP wrapper is the relevant installation path when an MCP client launches the server locally.

## Tools and capabilities

The available capabilities include:

- Store, recall, tag-search, summarize, list, inspect, and delete memories.
- Check vector-index health and re-index orphaned memories.
- Create, list, verify, purge, and restore local backups.
- Review consolidation reports covering strengthening, decay, graph edges, extraction, and maintenance.
- Track token usage and reset a token session.
- Set, list, and dismiss time- or context-triggered reminders.
- Manage todos and projects, including priorities, due dates, subtasks, ordering, completion, and archiving.

## Limitations and notes

varun29ankuS/shodh-memory MCP server is designed for local, offline use, but the first run may download the configured local AI model. Its memory intelligence is algorithmic and does not use an LLM in the storage or recall path. Remote deployments require the API-key configuration described in the README, while local clients do not.

Restoring a backup replaces the current user's data, and the documentation recommends restarting the server afterward. The `verify_index` and `repair_index` tools are available for diagnosing and repairing memories that exist in storage but are missing from the searchable vector index. The project describes edge-device and robotics support, including Zenoh and ROS2 readiness, but those deployment paths are separate from the basic MCP client setup.

_Full upstream README: https://allmcps.com/mcp/varun29ankus-shodh-memory/readme_