shodh-memory

Shodh-Memory

Persistent cognitive memory for AI agents and robots — with no LLM in the loop. Remembers what matters, forgets what doesn't, gets smarter with use.

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?

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

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

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

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:

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.

# Enable Zenoh transport (compile with --features zenoh)
SHODH_ZENOH_ENABLED=true SHODH_ZENOH_LISTEN=tcp/0.0.0.0:7447 shodh server

# ROS2 robots connect via zenoh-bridge-ros2dds or rmw_zenoh — zero code changes
ros2 run zenoh_bridge_ros2dds zenoh_bridge_ros2dds

See Robotics Quickstart for full setup and examples.

What robots can do over Zenoh:

Each robot uses its own user_id as the key segment (e.g., shodh/spot-1/remember). The robot_id is an optional payload field for fleet grouping.

Every Experience carries 26 robotics-specific fields: geo_location, local_position, heading, sensor_data, robot_id, mission_id, action_type, reward, terrain_type, nearby_agents, decision_context, action_params, outcome_type, confidence, failure/anomaly tracking, recovery actions, and prediction learning.

{
  "user_id": "spot-1",
  "content": "Detected crack in concrete at waypoint alpha",
  "robot_id": "spot_v2",
  "mission_id": "building_inspection_2026",
  "geo_location": [37.7749, -122.4194, 10.0],
  "local_position": [12.5, 3.2, 0.0],
  "heading": 90.0,
  "sensor_data": {"battery": 72.5, "temperature": 28.3},
  "action_type": "inspect",
  "reward": 0.9,
  "terrain_type": "indoor",
  "tags": ["crack", "concrete", "structural"]
}

{
  "user_id": "spot-1",
  "query": "structural damage near entrance",
  "mode": "spatial",
  "lat": 37.7749,
  "lon": -122.4194,
  "radius_meters": 50.0,
  "mission_id": "building_inspection_2026"
}

SHODH_ZENOH_ENABLED=true                # Enable Zenoh transport
SHODH_ZENOH_MODE=peer                   # peer | client | router
SHODH_ZENOH_LISTEN=tcp/0.0.0.0:7447    # Listen endpoints
SHODH_ZENOH_CONNECT=tcp/1.2.3.4:7447   # Connect endpoints
SHODH_ZENOH_PREFIX=shodh               # Key expression prefix

# Auto-subscribe to ROS2 topics (via zenoh-bridge-ros2dds)
SHODH_ZENOH_AUTO_TOPICS='[
  {"key_expr": "rt/spot1/status", "user_id": "spot-1", "mode": "sensor"},
  {"key_expr": "rt/nav/events", "user_id": "spot-1", "mode": "event"}
]'

Works with ROS2 Kilted (rmw_zenoh), PX4 drones, Boston Dynamics Spot, humanoids — anything that speaks Zenoh or ROS2 DDS.

Platform Support

Linux x86_64 · Linux ARM64 · macOS Apple Silicon · macOS Intel · Windows x86_64

Production Deployment

SHODH_ENV=production              # Production mode
SHODH_API_KEYS=key1,key2,key3     # Comma-separated API keys
SHODH_HOST=127.0.0.1              # Bind address (default: localhost)
SHODH_PORT=3030                   # Port (default: 3030)
SHODH_MEMORY_PATH=/var/lib/shodh  # Data directory
# SHODH_IPC_ENABLED=false         # Local IPC is enabled by default; false disables it
# SHODH_IPC_ENDPOINT=/private/path/shodh-memory.sock  # Optional platform-specific override
# SHODH_IPC_REQUIRED=true         # Fail closed instead of falling back to HTTP
SHODH_REQUEST_TIMEOUT=60          # Request timeout in seconds
SHODH_MAX_CONCURRENT=200          # Max concurrent requests
SHODH_ROCKSDB_BLOCK_CACHE_MB=256  # Shared RocksDB block cache (MiB)
SHODH_CE_RERANK=1                 # Cross-encoder reranking (server default: on; 0 disables, e.g. for latency-bound robots)
SHODH_CE_DEPTH=30                 # Candidates the cross-encoder rescores (latency scales with this)
# SHODH_CE_MODEL_PATH=/models/ce  # Reranker assets; default: fetched on first start into the cache dir
# SHODH_OFFLINE=true              # Never download models; a missing reranker means unreranked recall
SHODH_CORS_ORIGINS=https://app.example.com

The server enables authenticated local IPC by default and keeps HTTP available. Native shodh serve prefers the platform-default IPC endpoint and falls back to SHODH_API_URL unless fail-closed mode is enabled; the TypeScript MCP client uses IPC only when SHODH_IPC_ENDPOINT is set. See the local IPC architecture for platform defaults, security properties, and limitations.

services:
  shodh-memory:
    image: varunshodh/shodh-memory:latest
    environment:
      - SHODH_ENV=production
      - SHODH_HOST=0.0.0.0
      - SHODH_API_KEYS=${SHODH_API_KEYS}
    volumes:
      - shodh-data:/data
    networks:
      - internal

  caddy:
    image: caddy:latest
    ports:
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
    networks:
      - internal

volumes:
  shodh-data:

networks:
  internal:

memory.example.com {
    reverse_proxy localhost:3030
}

Community

References

[1] Cowan, N. (2010). The Magical Mystery Four. Current Directions in Psychological Science. [2] Magee & Grienberger (2020). Synaptic Plasticity Forms and Functions. Annual Review of Neuroscience. [3] Subramanya et al. (2019). DiskANN. NeurIPS 2019.

License

Apache 2.0

MCP Registry · Docker Hub · PyPI · npm · crates.io · Docs

_{Keywords: LLM-free memory · no LLM in the loop · local-first AI memory · offline agent memory · persistent memory for AI agents · long-term memory for LLM agents · MCP memory server · Claude Code memory · knowledge graph memory · hybrid vector + graph search · causal lineage · Hebbian learning · memory decay · edge AI memory · robotics memory · ROS2 / Zenoh robot memory · air-gapped RAG alternative}