{ "markdown": "

\n \"Shodh-Memory\"\n

\n\n

Shodh-Memory

\n\n

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.

\n\n

\n \"build\"\n \"MCP\n \"Cursor\n \"crates.io\"\n \"npm\"\n \"PyPI\"\n \"Docker\"\n \"Zenoh/ROS2\"\n \"License\"\n \"Discord\"\n

\n\n---\n\n

\n \"Shodh-Memory\n

\n\nAI agents forget everything between sessions. Robots lose context between missions. They repeat mistakes, miss patterns, and treat every interaction like the first one.\n\nShodh-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.\n\n## Why Not Just Use mem0 / Cognee / Zep?\n\n| | **Shodh** | **mem0** | **Cognee** | **Zep** |\n|---|---|---|---|---|\n| LLM calls to store a memory | **0** | 2+ per add | 3+ per cognify | 2+ per episode |\n| External services needed | **None** | OpenAI + vector DB | OpenAI + Neo4j + vector DB | OpenAI + Neo4j |\n| Time to store a memory | **55ms** | ~20 seconds | seconds | seconds |\n| Learns from usage | **Yes** (Hebbian) | No | No | No |\n| Forgets irrelevant data | **Yes** (decay) | No | No | Temporal only |\n| Runs fully offline | **Yes** | No | No | No |\n| Robotics / ROS2 native | **Yes** (Zenoh) | No | No | No |\n| Binary size | **~17MB** | pip install + API keys | pip install + API keys + Neo4j | Cloud only |\n\nEvery other memory system delegates intelligence to LLM API calls — that's why they're slow, expensive, and can't work offline.\n\n## No LLM in the Loop\n\nStoring 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:\n\n- **Local embeddings** — MiniLM (22MB, INT8) via ONNX Runtime, on-device semantic search\n- **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\n- **Typed relation extraction without an LLM** — directed lexical cues + exemplar-matched semantic typing build a typed knowledge graph (`LocatedIn`, `WorksAt`, `Causes`…) from plain text\n- **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\n- **Mathematical memory dynamics** — Hebbian strengthening, exponential→power-law decay, spreading activation, long-term potentiation\n\nWhat 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.\n\n## Get Started\n\n### Unified CLI\n\n```bash\n# Download from GitHub Releases (or brew tap varun29ankuS/shodh-memory && brew install shodh-memory)\nshodh init # First-time setup — creates config, generates API key, downloads AI model\nshodh server # Start the memory server on :3030\nshodh setup-hooks # Print instructions to set up Claude Code hooks\nshodh tui # Launch the TUI dashboard\nshodh status # Check server health\nshodh doctor # Diagnose issues\n```\n\nOne binary, all functionality. No Docker, no API keys, no external dependencies.\n\n### Claude Code\n\n```bash\n# 1. Add the MCP server (auto-downloads the backend binary)\nclaude mcp add shodh-memory -- npx -y @shodh/memory-mcp\n\n# 2. Enable automatic memory capture (optional but recommended)\nnpx @shodh/memory-mcp setup-hooks\n```\n\nStep 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.\n\n
\nOr with Docker (for production / shared servers)\n\n```bash\n# 1. Start the server\ndocker run -d -p 3030:3030 -v shodh-data:/data varunshodh/shodh-memory\n\n# 2. Add to Claude Code\nclaude mcp add shodh-memory -- npx -y @shodh/memory-mcp\n```\n
\n\n
\nDirect server mode (systemd / MCP / REST)\n\nFor Linux users who want the Rust HTTP server supervised separately from MCP\nclients, see [Direct server mode with systemd](docs/direct-server-systemd.md).\n\n
\n\n
\nCursor / Claude Desktop config\n\n```json\n{\n \"mcpServers\": {\n \"shodh-memory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@shodh/memory-mcp\"]\n }\n }\n}\n```\n\nFor local use, no API key is needed — one is generated automatically. For remote servers, add `\"env\": { \"SHODH_API_KEY\": \"your-key\" }`.\n
\n\n### Python\n\n```bash\npip install shodh-memory\n```\n\n```python\nfrom shodh_memory import Memory\n\nmemory = Memory(storage_path=\"./my_data\")\nmemory.remember(\"User prefers dark mode\", memory_type=\"Decision\")\nresults = memory.recall(\"user preferences\", limit=5)\n```\n\n### Rust\n\n```toml\n[dependencies]\nshodh-memory = \"0.1\"\n```\n\n```rust\nuse shodh_memory::{MemorySystem, MemoryConfig};\n\nlet memory = MemorySystem::new(MemoryConfig::default())?;\nmemory.remember(\"user-1\", \"User prefers dark mode\", MemoryType::Decision, vec![])?;\nlet results = memory.recall(\"user-1\", \"user preferences\", 5)?;\n```\n\n### Docker\n\n```bash\ndocker run -d -p 3030:3030 -v shodh-data:/data varunshodh/shodh-memory\n```\n\n## What It Does\n\n```\nYou use a memory often → it becomes easier to find (Hebbian learning)\nYou stop using a memory → it fades over time (activation decay)\nYou recall one memory → related memories surface too (spreading activation)\nA connection is used → it becomes permanent (long-term potentiation)\n```\n\nUnder the hood, memories flow through three tiers:\n\n```\nWorking Memory ──overflow──▶ Session Memory ──importance──▶ Long-Term Memory\n (100 items) (100 MB) (RocksDB)\n```\n\nThis 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.\n\n## Performance\n\n| Operation | Latency |\n|-----------|---------|\n| Store memory (API response) | <200ms |\n| Store memory (core) | 55-60ms |\n| Semantic search | 34-58ms |\n| Tag search | ~1ms |\n| Entity lookup | 763ns |\n| Graph traversal (3-hop) | 30µs |\n\nSingle binary. No GPU required. Content-hash dedup ensures identical memories are never stored twice.\n\n## 51 MCP Tools\n\nFull list of tools available to Claude, Cursor, and other MCP clients:\n\n
\nMemory\n\n`remember` · `recall` · `recall_by_tags` · `proactive_context` · `context_summary` · `list_memories` · `read_memory` · `forget`\n
\n\n
\nSearch & Insight\n\n`quick_recall` · `query` · `topic` · `what_i_know` · `recent_memories` · `pending_work` · `count` · `memory_health` · `session_summary`\n
\n\n
\nSessions & Facts\n\n`session_digest` · `session_history` · `fact_narratives` · `purge_facts`\n
\n\n
\nTodos (GTD)\n\n`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`\n
\n\n
\nProjects\n\n`add_project` · `list_projects` · `archive_project` · `delete_project`\n
\n\n
\nReminders\n\n`set_reminder` · `list_reminders` · `dismiss_reminder`\n
\n\n
\nSystem\n\n`memory_stats` · `verify_index` · `repair_index` · `token_status` · `reset_token_session` · `consolidation_report` · `backup_create` · `backup_list` · `backup_verify` · `backup_restore` · `backup_purge`\n
\n\n## REST API\n\n160+ endpoints on `http://localhost:3030`. All `/api/*` endpoints require `X-API-Key` header.\n\n[Full API reference →](https://www.shodh-memory.com/docs/api)\n\n
\nQuick examples\n\n```bash\n# Store a memory\ncurl -X POST http://localhost:3030/api/remember \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your-key\" \\\n -d '{\"user_id\": \"user-1\", \"content\": \"User prefers dark mode\", \"memory_type\": \"Decision\"}'\n\n# Search memories\ncurl -X POST http://localhost:3030/api/recall \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your-key\" \\\n -d '{\"user_id\": \"user-1\", \"query\": \"user preferences\", \"limit\": 5}'\n```\n
\n\n## Robotics & ROS2\n\nShodh-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.\n\n```bash\n# Enable Zenoh transport (compile with --features zenoh)\nSHODH_ZENOH_ENABLED=true SHODH_ZENOH_LISTEN=tcp/0.0.0.0:7447 shodh server\n\n# ROS2 robots connect via zenoh-bridge-ros2dds or rmw_zenoh — zero code changes\nros2 run zenoh_bridge_ros2dds zenoh_bridge_ros2dds\n```\n\nSee [Robotics Quickstart](docs/robotics-quickstart.md) for full setup and examples.\n\n**What robots can do over Zenoh:**\n\n| Operation | Key Expression | Description |\n|-----------|---------------|-------------|\n| Remember | `shodh/{user_id}/remember` | Store with GPS, local position, heading, sensor data, mission context |\n| Recall | `shodh/{user_id}/recall` | Spatial search (haversine), mission replay, action-outcome filtering |\n| Stream | `shodh/{user_id}/stream/sensor` | Auto-remember high-frequency sensor data via extraction pipeline |\n| Mission | `shodh/{user_id}/mission/start` | Track mission boundaries, searchable across missions |\n| Fleet | `shodh/fleet/**` | Automatic peer discovery via Zenoh liveliness tokens |\n\nEach 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.\n\nEvery 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.\n\n
\nZenoh remember example (robot publishing a memory)\n\n```json\n{\n \"user_id\": \"spot-1\",\n \"content\": \"Detected crack in concrete at waypoint alpha\",\n \"robot_id\": \"spot_v2\",\n \"mission_id\": \"building_inspection_2026\",\n \"geo_location\": [37.7749, -122.4194, 10.0],\n \"local_position\": [12.5, 3.2, 0.0],\n \"heading\": 90.0,\n \"sensor_data\": {\"battery\": 72.5, \"temperature\": 28.3},\n \"action_type\": \"inspect\",\n \"reward\": 0.9,\n \"terrain_type\": \"indoor\",\n \"tags\": [\"crack\", \"concrete\", \"structural\"]\n}\n```\n
\n\n
\nZenoh spatial recall example (robot querying nearby memories)\n\n```json\n{\n \"user_id\": \"spot-1\",\n \"query\": \"structural damage near entrance\",\n \"mode\": \"spatial\",\n \"lat\": 37.7749,\n \"lon\": -122.4194,\n \"radius_meters\": 50.0,\n \"mission_id\": \"building_inspection_2026\"\n}\n```\n
\n\n
\nEnvironment variables\n\n```bash\nSHODH_ZENOH_ENABLED=true # Enable Zenoh transport\nSHODH_ZENOH_MODE=peer # peer | client | router\nSHODH_ZENOH_LISTEN=tcp/0.0.0.0:7447 # Listen endpoints\nSHODH_ZENOH_CONNECT=tcp/1.2.3.4:7447 # Connect endpoints\nSHODH_ZENOH_PREFIX=shodh # Key expression prefix\n\n# Auto-subscribe to ROS2 topics (via zenoh-bridge-ros2dds)\nSHODH_ZENOH_AUTO_TOPICS='[\n {\"key_expr\": \"rt/spot1/status\", \"user_id\": \"spot-1\", \"mode\": \"sensor\"},\n {\"key_expr\": \"rt/nav/events\", \"user_id\": \"spot-1\", \"mode\": \"event\"}\n]'\n```\n
\n\nWorks with ROS2 Kilted (rmw_zenoh), PX4 drones, Boston Dynamics Spot, humanoids — anything that speaks Zenoh or ROS2 DDS.\n\n## Platform Support\n\nLinux x86_64 · Linux ARM64 · macOS Apple Silicon · macOS Intel · Windows x86_64\n\n## Production Deployment\n\n
\nEnvironment variables\n\n```bash\nSHODH_ENV=production # Production mode\nSHODH_API_KEYS=key1,key2,key3 # Comma-separated API keys\nSHODH_HOST=127.0.0.1 # Bind address (default: localhost)\nSHODH_PORT=3030 # Port (default: 3030)\nSHODH_MEMORY_PATH=/var/lib/shodh # Data directory\n# SHODH_IPC_ENABLED=false # Local IPC is enabled by default; false disables it\n# SHODH_IPC_ENDPOINT=/private/path/shodh-memory.sock # Optional platform-specific override\n# SHODH_IPC_REQUIRED=true # Fail closed instead of falling back to HTTP\nSHODH_REQUEST_TIMEOUT=60 # Request timeout in seconds\nSHODH_MAX_CONCURRENT=200 # Max concurrent requests\nSHODH_ROCKSDB_BLOCK_CACHE_MB=256 # Shared RocksDB block cache (MiB)\nSHODH_CORS_ORIGINS=https://app.example.com\n```\n
\n\nThe server enables authenticated local IPC by default and keeps HTTP available.\nNative `shodh serve` prefers the platform-default IPC endpoint and falls back to\n`SHODH_API_URL` unless fail-closed mode is enabled; the TypeScript MCP client uses IPC only when\n`SHODH_IPC_ENDPOINT` is set. See the [local IPC architecture](docs/architecture/07-local-ipc-transport.md)\nfor platform defaults, security properties, and limitations.\n\n
\nDocker Compose with TLS\n\n```yaml\nservices:\n shodh-memory:\n image: varunshodh/shodh-memory:latest\n environment:\n - SHODH_ENV=production\n - SHODH_HOST=0.0.0.0\n - SHODH_API_KEYS=${SHODH_API_KEYS}\n volumes:\n - shodh-data:/data\n networks:\n - internal\n\n caddy:\n image: caddy:latest\n ports:\n - \"443:443\"\n volumes:\n - ./Caddyfile:/etc/caddy/Caddyfile\n networks:\n - internal\n\nvolumes:\n shodh-data:\n\nnetworks:\n internal:\n```\n
\n\n
\nReverse proxy (Nginx / Caddy)\n\nThe server binds to `127.0.0.1` by default. For network deployments, place behind a reverse proxy:\n\n```caddyfile\nmemory.example.com {\n reverse_proxy localhost:3030\n}\n```\n
\n\n## Community\n\n| Project | Description | Author |\n|---------|-------------|--------|\n| [SHODH on Cloudflare](https://github.com/doobidoo/shodh-cloudflare) | Edge-native implementation on Cloudflare Workers | [@doobidoo](https://github.com/doobidoo) |\n\n## References\n\n[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*.\n\n## License\n\nApache 2.0\n\n---\n\n

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

\n\nKeywords: 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\n", "bytes": 17476, "sha": "e348a495df85d852e28ea2b78765b735fd269cb7c5f7a77c537c1464a2718b3b", "repo_slug": "varun29ankus/shodh-memory", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_varun29ankus_shodh_memory_24c50734/readme" }