MCP 服务器

Shodh-Memory

Provides persistent cognitive memory for AI agents and robots with no LLM in the loop, using algorithms for storage, recall, and forgetting; supports MCP, HTTP, and ROS2.

README

<h1 align="center">Shodh-Memory</h1>

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?

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

<details> <summary>Or with Docker (for production / shared servers)</summary>

# 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

</details>

<details> <summary>Direct server mode (systemd / MCP / REST)</summary>

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

</details>

<details> <summary>Cursor / Claude Desktop config</summary>

{
  "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" }. </details>

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	34-58ms
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.

51 MCP Tools

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

<details> <summary>Memory</summary>

remember · recall · recall_by_tags · proactive_context · context_summary · list_memories · read_memory · forget </details>

<details> <summary>Search & Insight</summary>

quick_recall · query · topic · what_i_know · recent_memories · pending_work · count · memory_health · session_summary </details>

<details> <summary>Sessions & Facts</summary>

session_digest · session_history · fact_narratives · purge_facts </details>

<details> <summary>Todos (GTD)</summary>

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 </details>

<details> <summary>Projects</summary>

add_project · list_projects · archive_project · delete_project </details>

<details> <summary>Reminders</summary>

set_reminder · list_reminders · dismiss_reminder </details>

<details> <summary>System</summary>

memory_stats · verify_index · repair_index · token_status · reset_token_session · consolidation_report · backup_create · backup_list · backup_verify · backup_restore · backup_purge </details>

REST API

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

Full API reference →

<details> <summary>Quick examples</summary>

# 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}'

</details>

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:

Operation	Key Expression	Description
Remember	`shodh/{user_id}/remember`	Store with GPS, local position, heading, sensor data, mission context
Recall	`shodh/{user_id}/recall`	Spatial search (haversine), mission replay, action-outcome filtering
Stream	`shodh/{user_id}/stream/sensor`	Auto-remember high-frequency sensor data via extraction pipeline
Mission	`shodh/{user_id}/mission/start`	Track mission boundaries, searchable across missions
Fleet	`shodh/fleet/**`	Automatic peer discovery via Zenoh liveliness tokens

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.

<details> <summary>Zenoh remember example (robot publishing a memory)</summary>

{
  "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"]
}

</details>

<details> <summary>Zenoh spatial recall example (robot querying nearby memories)</summary>

{
  "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"
}

</details>

<details> <summary>Environment variables</summary>

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"}
]'

</details>

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

<details> <summary>Environment variables</summary>

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_CORS_ORIGINS=https://app.example.com

</details>

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.

<details> <summary>Docker Compose with TLS</summary>

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:

</details>

<details> <summary>Reverse proxy (Nginx / Caddy)</summary>

The server binds to 127.0.0.1 by default. For network deployments, place behind a reverse proxy:

memory.example.com {
    reverse_proxy localhost:3030
}

</details>

Community

Project	Description	Author
SHODH on Cloudflare	Edge-native implementation on Cloudflare Workers	@doobidoo

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

<a href="https://registry.modelcontextprotocol.io/v0/servers?search=shodh">MCP Registry</a> · <a href="https://hub.docker.com/r/varunshodh/shodh-memory">Docker Hub</a> · <a href="https://pypi.org/project/shodh-memory/">PyPI</a> · <a href="https://www.npmjs.com/package/@shodh/memory-mcp">npm</a> · <a href="https://crates.io/crates/shodh-memory">crates.io</a> · <a href="https://www.shodh-memory.com">Docs</a>

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

Shodh-Memory

README

Why Not Just Use mem0 / Cognee / Zep?

No LLM in the Loop

Get Started

Unified CLI

Claude Code

Python

Rust

Docker

What It Does

Performance

51 MCP Tools

REST API

Robotics & ROS2

Platform Support

Production Deployment

Community

References

License

推荐服务器