Content
<p align="center">
<img src="https://raw.githubusercontent.com/varun29ankuS/shodh-memory/main/assets/logo.png" width="120" alt="Shodh-Memory">
</p>
<h1 align="center">Shodh-Memory</h1>
<p align="center"><b>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.</b></p>
<p align="center">
<a href="https://github.com/varun29ankuS/shodh-memory/actions"><img src="https://github.com/varun29ankuS/shodh-memory/workflows/CI/badge.svg" alt="build"></a>
<a href="https://registry.modelcontextprotocol.io/v0/servers?search=shodh"><img src="https://img.shields.io/badge/MCP-Registry-green" alt="MCP Registry"></a>
<a href="https://cursor.directory/plugins/shodh-memory-1"><img src="https://img.shields.io/badge/Cursor-Directory-black?logo=cursor" alt="Cursor Directory"></a>
<a href="https://crates.io/crates/shodh-memory"><img src="https://img.shields.io/crates/v/shodh-memory.svg" alt="crates.io"></a>
<a href="https://www.npmjs.com/package/@shodh/memory-mcp"><img src="https://img.shields.io/npm/v/@shodh/memory-mcp.svg?logo=npm" alt="npm"></a>
<a href="https://pypi.org/project/shodh-memory/"><img src="https://img.shields.io/pypi/v/shodh-memory.svg" alt="PyPI"></a>
<a href="https://hub.docker.com/r/varunshodh/shodh-memory"><img src="https://img.shields.io/docker/pulls/varunshodh/shodh-memory.svg?logo=docker" alt="Docker"></a>
<a href="#robotics--ros2"><img src="https://img.shields.io/badge/Zenoh%20%2F%20ROS2-ready-orange" alt="Zenoh/ROS2"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"></a>
<a href="https://discord.gg/HrpzXqTtEp"><img src="https://img.shields.io/discord/1471830549818642432?logo=discord&label=Discord&color=5865F2" alt="Discord"></a>
</p>
---
<p align="center">
<img src="https://raw.githubusercontent.com/varun29ankuS/shodh-memory/main/assets/Shodh_preview.gif" width="800" alt="Shodh-Memory Demo — Claude Code with persistent memory and TUI dashboard">
</p>
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
```bash
# 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
```bash
# 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](https://docs.anthropic.com/en/docs/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>
```bash
# 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](docs/direct-server-systemd.md).
</details>
<details>
<summary>Cursor / Claude Desktop config</summary>
```json
{
"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
```bash
pip install shodh-memory
```
```python
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
```toml
[dependencies]
shodh-memory = "0.1"
```
```rust
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
```bash
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](https://doi.org/10.1177/0963721409359277) and [Wixted's memory decay research](https://doi.org/10.1111/j.1467-9280.2004.00687.x). 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 →](https://www.shodh-memory.com/docs/api)
<details>
<summary>Quick examples</summary>
```bash
# 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.
```bash
# 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](docs/robotics-quickstart.md) 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>
```json
{
"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>
```json
{
"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>
```bash
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>
```bash
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](docs/architecture/07-local-ipc-transport.md)
for platform defaults, security properties, and limitations.
<details>
<summary>Docker Compose with TLS</summary>
```yaml
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:
```caddyfile
memory.example.com {
reverse_proxy localhost:3030
}
```
</details>
## Community
| Project | Description | Author |
|---------|-------------|--------|
| [SHODH on Cloudflare](https://github.com/doobidoo/shodh-cloudflare) | Edge-native implementation on Cloudflare Workers | [@doobidoo](https://github.com/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
---
<p align="center">
<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>
</p>
<sub><i>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</i></sub>
