# io.github.varun29ankuS/shodh-memory (npm · @shodh/memory-mcp)

Cognitive memory for AI agents — semantic search, Hebbian learning, knowledge graphs.

- Trust score: 60/100 (medium)
- Change this week: +7
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `@shodh/memory-mcp`: 60/100 (this document), [markdown](https://verifymcp.io/servers/varun29ankus-shodh-memory/shodh-memory-mcp.md), [page](https://verifymcp.io/servers/varun29ankus-shodh-memory/shodh-memory-mcp)

## Channel facts

- Registry: `npm`
- Package: `@shodh/memory-mcp`
- Version: `0.2.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 80/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
  - Runs a script at install time (postinstall) that we could not recognise. It may be perfectly ordinary, but we do not read the published tarball, so we cannot say what it does.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (Apache-2.0).
  - Actively maintained (last published 115 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 64/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (poor).
  - Tool/resource definitions use about 3770 tokens (~89/item across 42 items; 38 tools + 4 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 23/100
  - Stability observed for 7 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 20/100
  - Spec-recency check failed: implements MCP spec 2024-11-05; the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add varun29ankus-shodh-memory -- npx -y @shodh/memory-mcp
```

### Codex

```bash
codex mcp add varun29ankus-shodh-memory -- npx -y @shodh/memory-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "varun29ankus-shodh-memory": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@shodh/memory-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add varun29ankus-shodh-memory --command npx --arg -y --arg @shodh/memory-mcp
```

### Hermes

```yaml
mcp_servers:
  varun29ankus-shodh-memory:
    command: "npx"
    args: ["-y", "@shodh/memory-mcp"]
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 60, +40)

- [security regression] Provenance: unverified → fail
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Install scripts: unverified → partial
- [security] The scripts that run when this package is installed changed: postinstall
- [functional regression] MCP protocol: unverified → fail
- [functional improvement] Stability: unverified → 0.23
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Schema quality: unverified → 100
- [functional improvement] License: unverified → pass
- [functional improvement] Tool coverage: unverified → 100
- [functional] Licence: Apache-2.0

### 2026-08-02 (score 20, −30)

- [security regression] Provenance: fail → unverified
- [security regression] Install scripts: partial → unverified
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [security] The scripts that run when this package is installed changed: postinstall
- [functional regression] Capabilities: fail → unverified
- [functional regression] License: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Schema quality: 100 → unverified
- [functional regression] Maintenance: pass → unverified
- [functional] Licence: Apache-2.0

### 2026-08-01 (score 50, −10)

- [security regression] Known CVEs: partial → unverified
- [functional regression] Dependency health: partial → unverified

### 2026-07-31 (score 60, +35)

- [security regression] Malware scan: pass → unverified
- [functional regression] Dependency health: partial → unverified
- [functional regression] Security disclosure: fail → unverified
- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] Schema quality: unverified → 100
- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-29 (score 25, −28)

- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Schema quality: 100 → unverified
- [functional improvement] Dependency health: unverified → partial

### 2026-07-27 (score 53)

First indexed and scored.

## MCP tools (38)

### `remember` (~667 tokens)

Store a memory for future recall. Use this to remember important information, decisions, user preferences, project context, or anything you want to recall later.

Input parameters:

- `action_type` (string): Action type name (e.g., 'navigate', 'grasp', 'dock')
- `content` (string, required): The content to remember (observation, decision, learning, etc.)
- `created_at` (string): Optional ISO 8601 timestamp for the memory (e.g., '2025-12-15T06:30:00Z'). If not provided, uses current time.
- `credibility` (number): Credibility score: 0.0 to 1.0 (1.0 = verified facts, 0.3 = inferred)
- `emotion` (string): Dominant emotion label (e.g., 'joy', 'frustration', 'surprise')
- `emotional_arousal` (number): Arousal level: 0.0 (calm) to 1.0 (highly aroused). E.g., routine task: 0.2, critical issue: 0.9
- `emotional_valence` (number): Emotional valence: -1.0 (negative) to 1.0 (positive), 0.0 = neutral. E.g., bug found: -0.3, feature shipped: 0.7
- `episode_id` (string): Episode ID - groups memories into coherent episodes/conversations
- `geo_location` (array): GPS coordinates [latitude, longitude, altitude] in WGS84
- `heading` (number): Heading in degrees (0-360)
- `importance` (number): Optional importance override (0.0-1.0). Bypasses auto-calculation. Use for memories where importance is known: Decision=0.8, Learning=0.7, Error=0.7, Discovery=0.6, Observation=0.3
- `local_position` (array): Local position [x, y, z] in meters (robot-local frame)
- `mission_id` (string): Mission identifier for grouping experiences
- `outcome_type` (string): Outcome type: success, failure, partial, aborted, timeout
- `parent_id` (string): Parent memory ID for hierarchical organization. Creates memory trees (e.g., '71-research' -> 'algebraic' -> '21×27≡-1')
- `preceding_memory_id` (string): ID of the preceding memory (for temporal chains)
- `reward` (number): Reinforcement learning reward signal (-1.0 to 1.0)
- `robot_id` (string): Robot/drone identifier for multi-robot systems
- `sensor_data` (object): Raw sensor readings (e.g., {battery: 72.5, temperature: 23.1})
- `sequence_number` (number): Sequence number within episode (1, 2, 3...)
- `source_type` (string): Source type: where the information came from
- `tags` (array): Optional tags for categorization
- `terrain_type` (string): Terrain type: indoor, outdoor, urban, rural, water, aerial
- `type` (string): Type of memory

### `recall` (~501 tokens)

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

Input parameters:

- `action_type` (string): Filter by action type (e.g., 'navigate', 'grasp', 'dock')
- `failures_only` (boolean): If true, only return failure/error experiences
- `geo_lat` (number): Spatial filter: center latitude (-90 to 90). Requires geo_lon and geo_radius_meters.
- `geo_lon` (number): Spatial filter: center longitude (-180 to 180). Requires geo_lat and geo_radius_meters.
- `geo_radius_meters` (number): Spatial filter: search radius in meters. Requires geo_lat and geo_lon.
- `limit` (number): Maximum number of memory results (default: 5). Todos limited to 5.
- `mission_id` (string): Filter by mission identifier
- `mode` (string): Retrieval mode: 'semantic' for pure vector similarity, 'associative' for graph-based traversal (follows learned connections), 'temporal' for time-based retrieval, 'hybrid' for density-dependent combi…
- `outcome_type` (string): Filter by outcome type: success, failure, partial, aborted, timeout
- `query` (string, required): Natural language search query - searches both memories and todos
- `reward_max` (number): Filter by maximum reward value (-1.0 to 1.0)
- `reward_min` (number): Filter by minimum reward value (-1.0 to 1.0)
- `robot_id` (string): Filter by robot/drone identifier (for multi-robot systems)
- `session_id` (string): Session ID for session-scoped retrieval. When provided, retrieves memories from that session's time window. Forces temporal mode.
- `tags` (array): Filter by tags (any match)
- `terrain_type` (string): Filter by terrain type: indoor, outdoor, urban, rural, water, aerial

### `recall_by_tags` (~92 tokens)

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').

Input parameters:

- `limit` (number): Maximum number of results (default: 50)
- `tags` (array, required): Tags to search for (returns memories matching ANY of these tags)

### `context_summary` (~103 tokens)

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.

Input parameters:

- `include_context` (boolean): Include project context (default: true)
- `include_decisions` (boolean): Include recent decisions (default: true)
- `include_learnings` (boolean): Include recent learnings (default: true)
- `max_items` (number): Maximum items per category (default: 5)

### `list_memories` (~25 tokens)

List all stored memories

Input parameters:

- `limit` (number): Maximum number of results

### `forget` (~28 tokens)

Delete a specific memory by ID

Input parameters:

- `id` (string, required): The ID of the memory to delete

### `memory_stats` (~14 tokens)

Get statistics about stored memories

### `verify_index` (~34 tokens)

Verify vector index integrity - diagnose orphaned memories that are stored but not searchable. Returns health status and count of orphaned memories.

### `repair_index` (~34 tokens)

Repair vector index by re-indexing orphaned memories. Use this when verify_index shows unhealthy status. Returns count of repaired memories.

### `backup_create` (~37 tokens)

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` (~27 tokens)

List all available backups for this user. Returns backup history with IDs, timestamps, and sizes.

### `backup_verify` (~41 tokens)

Verify backup integrity using SHA-256 checksum. Use to check if a backup is corrupted before restoring.

Input parameters:

- `backup_id` (number, required): The backup ID to verify

### `backup_purge` (~45 tokens)

Purge old backups, keeping only the most recent N. Useful for managing disk space.

Input parameters:

- `keep_count` (number): Number of backups to keep (default: 7)

### `backup_restore` (~53 tokens)

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.

Input parameters:

- `backup_id` (number, required): The backup ID to restore (from backup_list)

### `consolidation_report` (~93 tokens)

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.

Input parameters:

- `since` (string): Start of report period (ISO 8601 format). Defaults to 24 hours ago.
- `until` (string): End of report period (ISO 8601 format). Defaults to now.

### `proactive_context` (~333 tokens)

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.

Input parameters:

- `auto_ingest` (boolean): Automatically store the context as a Conversation memory (default: true). Set to false to only surface memories without storing.
- `context` (string, required): The current conversation context or topic (e.g., recent messages, current task description)
- `entity_match_weight` (number): Weight for entity matching in relevance scoring (0.0-1.0, default: 0.4)
- `max_results` (number): Maximum number of memories to surface (default: 5)
- `memory_types` (array): Filter to specific memory types (e.g., ['Decision', 'Learning', 'Context']). Empty means all types.
- `recency_weight` (number): Weight for recency boost in relevance scoring (0.0-1.0, default: 0.2)
- `semantic_threshold` (number): Minimum semantic similarity (0.0-1.0) for memories to be surfaced (default: 0.65)
- `tool_actions` (array): Tool/actuator actions performed since last proactive_context call. Used for causal feedback attribution.

### `token_status` (~36 tokens)

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` (~35 tokens)

Reset the token counter for a new session. Call this when starting a new conversation or after context has been compressed/summarized.

### `set_reminder` (~245 tokens)

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.

Input parameters:

- `after_seconds` (number): Seconds from now for 'duration' trigger
- `content` (string, required): What to remember/remind about
- `keywords` (array): Keywords for 'context' trigger - reminder surfaces when any keyword appears
- `priority` (number): Priority 1-5 (5 = highest, default: 3)
- `tags` (array): Optional tags for categorization
- `threshold` (number): Semantic similarity threshold for 'context' trigger (0.0-1.0, default: 0.7). Lower values match more broadly, higher values require closer semantic match.
- `trigger_at` (string): ISO 8601 timestamp for 'time' trigger (e.g., '2025-12-23T18:00:00Z')
- `trigger_type` (string, required): When to trigger: 'time' (at specific ISO timestamp), 'duration' (after N seconds), 'context' (when keywords match)

### `list_reminders` (~36 tokens)

List all pending reminders. Use to check what reminders are scheduled.

Input parameters:

- `status` (string): Filter by status (default: pending)

### `dismiss_reminder` (~41 tokens)

Dismiss/acknowledge a triggered reminder. Call this after you've handled a reminder.

Input parameters:

- `reminder_id` (string, required): ID of the reminder to dismiss

### `add_todo` (~194 tokens)

Add a task to your todo list. Supports GTD workflow with projects, contexts (@computer, @phone), priorities, due dates, and subtasks (via parent_id).

Input parameters:

- `blocked_on` (string): Who/what you're waiting on (sets status to blocked)
- `content` (string, required): What needs to be done
- `contexts` (array): Contexts like @computer, @phone, @errands
- `due_date` (string): Due date - ISO format or 'today', 'tomorrow', 'monday', etc.
- `notes` (string): Additional notes
- `priority` (string): Priority level (default: medium)
- `project` (string): Project name (created if doesn't exist)
- `recurrence` (string): Recurrence pattern for repeating tasks
- `status` (string): Initial status (default: todo)
- `tags` (array): Optional tags for categorization

### `list_todos` (~152 tokens)

List or search todos. Supports semantic search via query parameter, or GTD-style filtering. Returns Linear-style formatted output grouped by status.

Input parameters:

- `context` (string): Filter by context (e.g., @computer)
- `due` (string): Filter by due date
- `limit` (number): Maximum results (default: 50)
- `offset` (number): Skip first N items for pagination (default: 0)
- `priority` (string): Filter by priority
- `project` (string): Filter by project name
- `query` (string): Semantic search query - when provided, uses vector similarity to find matching todos instead of listing all
- `status` (array): Filter by status(es)

### `update_todo` (~163 tokens)

Update a todo's properties. Use short ID prefix (e.g., SHO-1a2b) or full ID.

Input parameters:

- `blocked_on` (string): Who/what you're waiting on
- `content` (string): New content
- `contexts` (array): New contexts
- `due_date` (string): New due date
- `notes` (string): Additional notes
- `parent_id` (string): Parent todo ID or short prefix to make this a subtask. Pass empty string to remove parent.
- `priority` (string): New priority
- `project` (string): New project name
- `status` (string): New status
- `tags` (array): New tags
- `todo_id` (string, required): Todo ID or short prefix

### `complete_todo` (~38 tokens)

Mark a todo as complete. For recurring tasks, automatically creates the next occurrence.

Input parameters:

- `todo_id` (string, required): Todo ID or short prefix

### `delete_todo` (~27 tokens)

Delete a todo permanently.

Input parameters:

- `todo_id` (string, required): Todo ID or short prefix

### `reorder_todo` (~51 tokens)

Move a todo up or down within its status group. Use to prioritize tasks manually.

Input parameters:

- `direction` (string, required): Direction to move the todo
- `todo_id` (string, required): Todo ID or short prefix

### `add_project` (~92 tokens)

Create a new project to group todos. Use parent to create a sub-project under another project.

Input parameters:

- `description` (string): Project description
- `name` (string, required): Project name
- `parent` (string): Parent project name or ID to create a sub-project
- `prefix` (string): Custom prefix for todo IDs (e.g., 'BOLT', 'MEM'). Auto-derived from name if not provided.

### `list_projects` (~18 tokens)

List all projects with todo counts and status breakdown.

### `archive_project` (~36 tokens)

Archive a project. Archived projects are hidden by default but can be restored.

Input parameters:

- `project` (string, required): Project name or ID to archive

### `delete_project` (~61 tokens)

Permanently delete a project. Use delete_todos=true to also delete all todos in the project.

Input parameters:

- `delete_todos` (boolean): Also delete all todos in this project (default: false)
- `project` (string, required): Project name or ID to delete

### `todo_stats` (~23 tokens)

Get statistics about your todos - counts by status, overdue items, etc.

### `list_subtasks` (~43 tokens)

List subtasks of a parent todo. Use add_todo with parent_id to create subtasks.

Input parameters:

- `parent_id` (string, required): Parent todo ID or short prefix

### `add_todo_comment` (~95 tokens)

Add a comment to a todo. Use to track progress, notes, or resolution details.

Input parameters:

- `comment_type` (string): Type of comment: comment (default), progress (updates), resolution (fix details), activity (system)
- `content` (string, required): Comment content (supports markdown)
- `todo_id` (string, required): Todo ID or short prefix (e.g., 'BOLT-1', 'MEM-2')

### `list_todo_comments` (~48 tokens)

List all comments and activity history for a specific todo.

Input parameters:

- `todo_id` (string, required): Todo ID or short prefix (e.g., 'BOLT-1', 'MEM-2')

### `update_todo_comment` (~53 tokens)

Update an existing comment on a todo.

Input parameters:

- `comment_id` (string, required): Comment ID (UUID)
- `content` (string, required): New comment content
- `todo_id` (string, required): Todo ID or short prefix

### `delete_todo_comment` (~42 tokens)

Delete a comment from a todo.

Input parameters:

- `comment_id` (string, required): Comment ID (UUID)
- `todo_id` (string, required): Todo ID or short prefix

### `read_memory` (~62 tokens)

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.

Input parameters:

- `memory_id` (string, required): The memory ID (full UUID or short prefix like '5581cd02')

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/varun29ankus-shodh-memory/shodh-memory-mcp#diagnostics

## Score history

- 2026-08-03: 60
- 2026-08-02: 20
- 2026-08-01: 50
- 2026-07-31: 60
- 2026-07-29: 25
- 2026-07-28: 53
- 2026-07-27: 53

## Links

- npm package: https://www.npmjs.com/package/@shodh/memory-mcp
- Socket report: https://socket.dev/npm/package/@shodh/memory-mcp
- Repository: https://github.com/varun29ankuS/shodh-memory
- Changelog RSS feed: https://verifymcp.io/servers/varun29ankus-shodh-memory/shodh-memory-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/varun29ankus-shodh-memory/shodh-memory-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/varun29ankus-shodh-memory/shodh-memory-mcp