shodh-memory

---

AI agents forget everything between sessions. Robots lose context between missions. They repeat mistakes, miss patterns, and treat every interaction like the first one.

Shodh-Memory fixes this. It's persistent memory that actually learns — memories you use often become easier to find, old irrelevant context fades automatically, and recalling one thing brings back related things. Works for chat agents (MCP/HTTP), robots (Zenoh/ROS2), and edge devices. No API keys. No cloud. No external databases. No LLM in the loop. One binary.

Why Not Just Use mem0 / Cognee / Zep?

	Shodh	mem0	Cognee	Zep
LLM calls to store a memory	0	2+ per add	3+ per cognify	2+ per episode
External services needed	None	OpenAI + vector DB	OpenAI + Neo4j + vector DB	OpenAI + Neo4j
Time to store a memory	55ms	~20 seconds	seconds	seconds
Learns from usage	Yes (Hebbian)	No	No	No
Forgets irrelevant data	Yes (decay)	No	No	Temporal only
Runs fully offline	Yes	No	No	No
Robotics / ROS2 native	Yes (Zenoh)	No	No	No
Binary size	~17MB	pip install + API keys	pip install + API keys + Neo4j	Cloud only

Every other memory system delegates intelligence to LLM API calls — that's why they're slow, expensive, and can't work offline.

No LLM in the Loop

Storing a memory makes zero LLM calls. Recalling makes zero LLM calls. Entity extraction, relation typing, knowledge-graph construction, causal tracing, ranking, decay, consolidation — all of it runs locally as algorithms, not API round-trips:

• Local embeddings — MiniLM (22MB, INT8) via ONNX Runtime, on-device semantic search
• Local reranking — a cross-encoder (ms-marco-MiniLM-L6, 23 MB int8, ONNX) reads the query and each of the top 30 candidates together, where the embedder sees them apart. On by default in the server: +16.5pp precision@1 and +8.7pp recall@10 on LoCoMo (1,531 held-out questions). It is a 22M-parameter ranking model, not an LLM, and it runs on CPU
• Local NER — GLiNER bi-edge-v2 span typer (ONNX, schema-driven: 141 fine / 18 coarse entity types), auto-downloaded on first run from the pinned release, with a rule-based fallback
• Typed relation extraction without an LLM — directed lexical cues + exemplar-matched semantic typing build a typed knowledge graph (LocatedIn, WorksAt, Causes…) from plain text
• Causal lineage — "what was the root cause of X?" is answered by walking typed causal edges backward through the graph, not by asking a model
• Mathematical memory dynamics — Hebbian strengthening, exponential→power-law decay, spreading activation, long-term potentiation

What that buys you: fully offline operation, millisecond latency instead of multi-second API calls, zero inference cost at any scale, deterministic, testable behavior, and data that never leaves the machine. Your agent's LLM does the reasoning — its memory doesn't need one.

Get Started

Unified CLI

# Download from GitHub Releases (or brew tap varun29ankuS/shodh-memory && brew install shodh-memory)
shodh init          # First-time setup — creates config, generates API key, downloads AI model
shodh server        # Start the memory server on :3030
shodh setup-hooks   # Print instructions to set up Claude Code hooks
shodh tui           # Launch the TUI dashboard
shodh status        # Check server health
shodh doctor        # Diagnose issues

One binary, all functionality. No Docker, no API keys, no external dependencies.

Claude Code

# 1. Add the MCP server (auto-downloads the backend binary)
claude mcp add shodh-memory -- npx -y @shodh/memory-mcp

# 2. Enable automatic memory capture (optional but recommended)
npx @shodh/memory-mcp setup-hooks

Step 1 gives Claude persistent memory tools. Step 2 installs Claude Code hooks that automatically capture context from every session — memories surface without you having to ask.

# 1. Start the server
docker run -d -p 3030:3030 -v shodh-data:/data varunshodh/shodh-memory

# 2. Add to Claude Code
claude mcp add shodh-memory -- npx -y @shodh/memory-mcp

For Linux users who want the Rust HTTP server supervised separately from MCP clients, see Direct server mode with systemd.

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

For local use, no API key is needed — one is generated automatically. For remote servers, add "env": { "SHODH_API_KEY": "your-key" }.

Python

pip install shodh-memory

from shodh_memory import Memory

memory = Memory(storage_path="./my_data")
memory.remember("User prefers dark mode", memory_type="Decision")
results = memory.recall("user preferences", limit=5)

Rust

[dependencies]
shodh-memory = "0.1"

use shodh_memory::{MemorySystem, MemoryConfig};

let memory = MemorySystem::new(MemoryConfig::default())?;
memory.remember("user-1", "User prefers dark mode", MemoryType::Decision, vec![])?;
let results = memory.recall("user-1", "user preferences", 5)?;

Docker

docker run -d -p 3030:3030 -v shodh-data:/data varunshodh/shodh-memory

What It Does

You use a memory often  →  it becomes easier to find (Hebbian learning)
You stop using a memory →  it fades over time (activation decay)
You recall one memory   →  related memories surface too (spreading activation)
A connection is used    →  it becomes permanent (long-term potentiation)

Under the hood, memories flow through three tiers:

Working Memory ──overflow──▶ Session Memory ──importance──▶ Long-Term Memory
   (100 items)                  (100 MB)                      (RocksDB)

This is based on Cowan's working memory model and Wixted's memory decay research. The neuroscience isn't a gimmick — it's why the system gets better with use instead of just accumulating data.

Performance

Operation	Latency
Store memory (API response)	<200ms
Store memory (core)	55-60ms
Semantic search, reranking off (SHODH_CE_RERANK=0)	34-58ms
Cross-encoder rerank of the top 30 (server default)	+156ms p50, +216ms p95 end to end (76→232 p50, 79→295 p95; int8, release build, CI runner, 100-query LoCoMo gate). The cross-encoder itself is ~190ms mean per query, 83% of query time
Tag search	~1ms
Entity lookup	763ns
Graph traversal (3-hop)	30µs

Single binary. No GPU required. Content-hash dedup ensures identical memories are never stored twice.

The reranker numbers are an order of magnitude, not a promise: on identical code, runner speed moved the gate's p50 by up to 2.3× between runs (140 to 544ms). The gate now runs with per-stage timing on (SHODH_STAGE_TIMING=1, STAGE_TIMING rows in its recall-eval.log), which is how the cost above is attributed to the cross-encoder rather than to the runner.

51 MCP Tools

Full list of tools available to Claude, Cursor, and other MCP clients:

remember · recall · recall_by_tags · proactive_context · context_summary · list_memories · read_memory · forget

quick_recall · query · topic · what_i_know · recent_memories · pending_work · count · memory_health · session_summary

session_digest · session_history · fact_narratives · purge_facts

add_todo · list_todos · update_todo · complete_todo · delete_todo · reorder_todo · list_subtasks · add_todo_comment · list_todo_comments · update_todo_comment · delete_todo_comment · todo_stats

add_project · list_projects · archive_project · delete_project

set_reminder · list_reminders · dismiss_reminder

memory_stats · verify_index · repair_index · token_status · reset_token_session · consolidation_report · backup_create · backup_list · backup_verify · backup_restore · backup_purge

REST API

160+ endpoints on http://localhost:3030. All /api/* endpoints require X-API-Key header.

Full API reference →

# Store a memory
curl -X POST http://localhost:3030/api/remember \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"user_id": "user-1", "content": "User prefers dark mode", "memory_type": "Decision"}'

# Search memories
curl -X POST http://localhost:3030/api/recall \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"user_id": "user-1", "query": "user preferences", "limit": 5}'

Robotics & ROS2

Shodh-Memory isn't just for chat agents. It's persistent memory for robots — Spot, drones, humanoids, any system running ROS2 or Zenoh. No cloud, survives power cycles, learns from rewards, speaks Zenoh natively.