Skip to content
Back to search

shodh-memory

Local, LLM-free memory for AI agents. A single offline Rust binary — deterministic and auditable — that learns from use, forgets the irrelevant, and strengthens what matters. No cloud, no API keys.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/varun29ankuS/shodh-memory with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/varun29ankuS/shodh-memory'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/varun29ankus--shodh-memory/badge.svg)](/listings/varun29ankus--shodh-memory)

HTML

<a href="/listings/varun29ankus--shodh-memory"><img src="/api/listings/varun29ankus--shodh-memory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 449 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/varun29ankuS/shodh-memory/main/assets/logo.png" width="120" alt="Shodh-Memory">
  3. </p>
  4. <h1 align="center">Shodh-Memory</h1>
  5. <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>
  6. <p align="center">
  7. <a href="https://github.com/varun29ankuS/shodh-memory/actions"><img src="https://github.com/varun29ankuS/shodh-memory/workflows/CI/badge.svg" alt="build"></a>
  8. <a href="https://registry.modelcontextprotocol.io/v0/servers?search=shodh"><img src="https://img.shields.io/badge/MCP-Registry-green" alt="MCP Registry"></a>
  9. <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>
  10. <a href="https://crates.io/crates/shodh-memory"><img src="https://img.shields.io/crates/v/shodh-memory.svg" alt="crates.io"></a>
  11. <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>
  12. <a href="https://pypi.org/project/shodh-memory/"><img src="https://img.shields.io/pypi/v/shodh-memory.svg" alt="PyPI"></a>
  13. <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>
  14. <a href="#robotics--ros2"><img src="https://img.shields.io/badge/Zenoh%20%2F%20ROS2-ready-orange" alt="Zenoh/ROS2"></a>
  15. <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"></a>
  16. <a href="https://discord.gg/HrpzXqTtEp"><img src="https://img.shields.io/discord/1471830549818642432?logo=discord&label=Discord&color=5865F2" alt="Discord"></a>
  17. </p>
  18. ---
  19. <p align="center">
  20. <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">
  21. </p>
  22. AI agents forget everything between sessions. Robots lose context between missions. They repeat mistakes, miss patterns, and treat every interaction like the first one.
  23. 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.
  24. ## Why Not Just Use mem0 / Cognee / Zep?
  25. | | **Shodh** | **mem0** | **Cognee** | **Zep** |
  26. |---|---|---|---|---|
  27. | LLM calls to store a memory | **0** | 2+ per add | 3+ per cognify | 2+ per episode |
  28. | External services needed | **None** | OpenAI + vector DB | OpenAI + Neo4j + vector DB | OpenAI + Neo4j |
  29. | Time to store a memory | **55ms** | ~20 seconds | seconds | seconds |
  30. | Learns from usage | **Yes** (Hebbian) | No | No | No |
  31. | Forgets irrelevant data | **Yes** (decay) | No | No | Temporal only |
  32. | Runs fully offline | **Yes** | No | No | No |
  33. | Robotics / ROS2 native | **Yes** (Zenoh) | No | No | No |
  34. | Binary size | **~17MB** | pip install + API keys | pip install + API keys + Neo4j | Cloud only |
  35. Every other memory system delegates intelligence to LLM API calls — that's why they're slow, expensive, and can't work offline.
  36. ## No LLM in the Loop
  37. 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:
  38. - **Local embeddings** — MiniLM (22MB, INT8) via ONNX Runtime, on-device semantic search
  39. - **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
  40. - **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
  41. - **Typed relation extraction without an LLM** — directed lexical cues + exemplar-matched semantic typing build a typed knowledge graph (`LocatedIn`, `WorksAt`, `Causes`…) from plain text
  42. - **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
  43. - **Mathematical memory dynamics** — Hebbian strengthening, exponential→power-law decay, spreading activation, long-term potentiation
  44. 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.
  45. ## Get Started
  46. ### Unified CLI
  47. ```bash
  48. # Download from GitHub Releases (or brew tap varun29ankuS/shodh-memory && brew install shodh-memory)
  49. shodh init # First-time setup — creates config, generates API key, downloads AI model
  50. shodh server # Start the memory server on :3030
  51. shodh setup-hooks # Print instructions to set up Claude Code hooks
  52. shodh tui # Launch the TUI dashboard
  53. shodh status # Check server health
  54. shodh doctor # Diagnose issues
  55. ```
  56. One binary, all functionality. No Docker, no API keys, no external dependencies.
  57. ### Claude Code
  58. ```bash
  59. # 1. Add the MCP server (auto-downloads the backend binary)
  60. claude mcp add shodh-memory -- npx -y @shodh/memory-mcp
  61. # 2. Enable automatic memory capture (optional but recommended)
  62. npx @shodh/memory-mcp setup-hooks
  63. ```
  64. 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.
  65. <details>
  66. <summary>Or with Docker (for production / shared servers)</summary>
  67. ```bash
  68. # 1. Start the server
  69. docker run -d -p 3030:3030 -v shodh-data:/data varunshodh/shodh-memory
  70. # 2. Add to Claude Code
  71. claude mcp add shodh-memory -- npx -y @shodh/memory-mcp
  72. ```
  73. </details>
  74. <details>
  75. <summary>Direct server mode (systemd / MCP / REST)</summary>
  76. For Linux users who want the Rust HTTP server supervised separately from MCP
  77. clients, see [Direct server mode with systemd](docs/direct-server-systemd.md).
  78. </details>
  79. <details>
  80. <summary>Cursor / Claude Desktop config</summary>
  81. ```json
  82. {
  83. "mcpServers": {
  84. "shodh-memory": {
  85. "command": "npx",
  86. "args": ["-y", "@shodh/memory-mcp"]
  87. }
  88. }
  89. }
  90. ```
  91. For local use, no API key is needed — one is generated automatically. For remote servers, add `"env": { "SHODH_API_KEY": "your-key" }`.
  92. </details>
  93. ### Python
  94. ```bash
  95. pip install shodh-memory
  96. ```
  97. ```python
  98. from shodh_memory import Memory
  99. memory = Memory(storage_path="./my_data")
  100. memory.remember("User prefers dark mode", memory_type="Decision")
  101. results = memory.recall("user preferences", limit=5)
  102. ```
  103. ### Rust
  104. ```toml
  105. [dependencies]
  106. shodh-memory = "0.1"
  107. ```
  108. ```rust
  109. use shodh_memory::{MemorySystem, MemoryConfig};
  110. let memory = MemorySystem::new(MemoryConfig::default())?;
  111. memory.remember("user-1", "User prefers dark mode", MemoryType::Decision, vec![])?;
  112. let results = memory.recall("user-1", "user preferences", 5)?;
  113. ```
  114. ### Docker
  115. ```bash
  116. docker run -d -p 3030:3030 -v shodh-data:/data varunshodh/shodh-memory
  117. ```
  118. ## What It Does
  119. ```
  120. You use a memory often → it becomes easier to find (Hebbian learning)
  121. You stop using a memory → it fades over time (activation decay)
  122. You recall one memory → related memories surface too (spreading activation)
  123. A connection is used → it becomes permanent (long-term potentiation)
  124. ```
  125. Under the hood, memories flow through three tiers:
  126. ```
  127. Working Memory ──overflow──▶ Session Memory ──importance──▶ Long-Term Memory
  128. (100 items) (100 MB) (RocksDB)
  129. ```
  130. 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.
  131. ## Performance
  132. | Operation | Latency |
  133. |-----------|---------|
  134. | Store memory (API response) | <200ms |
  135. | Store memory (core) | 55-60ms |
  136. | Semantic search, reranking off (`SHODH_CE_RERANK=0`) | 34-58ms |
  137. | 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 |
  138. | Tag search | ~1ms |
  139. | Entity lookup | 763ns |
  140. | Graph traversal (3-hop) | 30µs |
  141. Single binary. No GPU required. Content-hash dedup ensures identical memories are never stored twice.
  142. 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.
  143. ## 51 MCP Tools
  144. Full list of tools available to Claude, Cursor, and other MCP clients:
  145. <details>
  146. <summary>Memory</summary>
  147. `remember` · `recall` · `recall_by_tags` · `proactive_context` · `context_summary` · `list_memories` · `read_memory` · `forget`
  148. </details>
  149. <details>
  150. <summary>Search & Insight</summary>
  151. `quick_recall` · `query` · `topic` · `what_i_know` · `recent_memories` · `pending_work` · `count` · `memory_health` · `session_summary`
  152. </details>
  153. <details>
  154. <summary>Sessions & Facts</summary>
  155. `session_digest` · `session_history` · `fact_narratives` · `purge_facts`
  156. </details>
  157. <details>
  158. <summary>Todos (GTD)</summary>
  159. `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`
  160. </details>
  161. <details>
  162. <summary>Projects</summary>
  163. `add_project` · `list_projects` · `archive_project` · `delete_project`
  164. </details>
  165. <details>
  166. <summary>Reminders</summary>
  167. `set_reminder` · `list_reminders` · `dismiss_reminder`
  168. </details>
  169. <details>
  170. <summary>System</summary>
  171. `memory_stats` · `verify_index` · `repair_index` · `token_status` · `reset_token_session` · `consolidation_report` · `backup_create` · `backup_list` · `backup_verify` · `backup_restore` · `backup_purge`
  172. </details>
  173. ## REST API
  174. 160+ endpoints on `http://localhost:3030`. All `/api/*` endpoints require `X-API-Key` header.
  175. [Full API reference →](https://www.shodh-memory.com/docs/api)
  176. <details>
  177. <summary>Quick examples</summary>
  178. ```bash
  179. # Store a memory
  180. curl -X POST http://localhost:3030/api/remember \
  181. -H "Content-Type: application/json" \
  182. -H "X-API-Key: your-key" \
  183. -d '{"user_id": "user-1", "content": "User prefers dark mode", "memory_type": "Decision"}'
  184. # Search memories
  185. curl -X POST http://localhost:3030/api/recall \
  186. -H "Content-Type: application/json" \
  187. -H "X-API-Key: your-key" \
  188. -d '{"user_id": "user-1", "query": "user preferences", "limit": 5}'
  189. ```
  190. </details>
  191. ## Robotics & ROS2
  192. 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.
  193. ```bash
  194. # Enable Zenoh transport (compile with --features zenoh)
  195. SHODH_ZENOH_ENABLED=true SHODH_ZENOH_LISTEN=tcp/0.0.0.0:7447 shodh server
  196. # ROS2 robots connect via zenoh-bridge-ros2dds or rmw_zenoh — zero code changes
  197. ros2 run zenoh_bridge_ros2dds zenoh_bridge_ros2dds
  198. ```
  199. See [Robotics Quickstart](docs/robotics-quickstart.md) for full setup and examples.
  200. **What robots can do over Zenoh:**
  201. | Operation | Key Expression | Description |
  202. |-----------|---------------|-------------|
  203. | Remember | `shodh/{user_id}/remember` | Store with GPS, local position, heading, sensor data, mission context |
  204. | Recall | `shodh/{user_id}/recall` | Spatial search (haversine), mission replay, action-outcome filtering |
  205. | Stream | `shodh/{user_id}/stream/sensor` | Auto-remember high-frequency sensor data via extraction pipeline |
  206. | Mission | `shodh/{user_id}/mission/start` | Track mission boundaries, searchable across missions |
  207. | Fleet | `shodh/fleet/**` | Automatic peer discovery via Zenoh liveliness tokens |
  208. 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.
  209. 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.
  210. <details>
  211. <summary>Zenoh remember example (robot publishing a memory)</summary>
  212. ```json
  213. {
  214. "user_id": "spot-1",
  215. "content": "Detected crack in concrete at waypoint alpha",
  216. "robot_id": "spot_v2",
  217. "mission_id": "building_inspection_2026",
  218. "geo_location": [37.7749, -122.4194, 10.0],
  219. "local_position": [12.5, 3.2, 0.0],
  220. "heading": 90.0,
  221. "sensor_data": {"battery": 72.5, "temperature": 28.3},
  222. "action_type": "inspect",
  223. "reward": 0.9,
  224. "terrain_type": "indoor",
  225. "tags": ["crack", "concrete", "structural"]
  226. }
  227. ```
  228. </details>
  229. <details>
  230. <summary>Zenoh spatial recall example (robot querying nearby memories)</summary>
  231. ```json
  232. {
  233. "user_id": "spot-1",
  234. "query": "structural damage near entrance",
  235. "mode": "spatial",
  236. "lat": 37.7749,
  237. "lon": -122.4194,
  238. "radius_meters": 50.0,
  239. "mission_id": "building_inspection_2026"
  240. }
  241. ```
  242. </details>
  243. <details>
  244. <summary>Environment variables</summary>
  245. ```bash
  246. SHODH_ZENOH_ENABLED=true # Enable Zenoh transport
  247. SHODH_ZENOH_MODE=peer # peer | client | router
  248. SHODH_ZENOH_LISTEN=tcp/0.0.0.0:7447 # Listen endpoints
  249. SHODH_ZENOH_CONNECT=tcp/1.2.3.4:7447 # Connect endpoints
  250. SHODH_ZENOH_PREFIX=shodh # Key expression prefix
  251. # Auto-subscribe to ROS2 topics (via zenoh-bridge-ros2dds)
  252. SHODH_ZENOH_AUTO_TOPICS='[
  253. {"key_expr": "rt/spot1/status", "user_id": "spot-1", "mode": "sensor"},
  254. {"key_expr": "rt/nav/events", "user_id": "spot-1", "mode": "event"}
  255. ]'
  256. ```
  257. </details>
  258. Works with ROS2 Kilted (rmw_zenoh), PX4 drones, Boston Dynamics Spot, humanoids — anything that speaks Zenoh or ROS2 DDS.
  259. ## Platform Support
  260. Linux x86_64 · Linux ARM64 · macOS Apple Silicon · macOS Intel · Windows x86_64
  261. ## Production Deployment
  262. <details>
  263. <summary>Environment variables</summary>
  264. ```bash
  265. SHODH_ENV=production # Production mode
  266. SHODH_API_KEYS=key1,key2,key3 # Comma-separated API keys
  267. SHODH_HOST=127.0.0.1 # Bind address (default: localhost)
  268. SHODH_PORT=3030 # Port (default: 3030)
  269. SHODH_MEMORY_PATH=/var/lib/shodh # Data directory
  270. # SHODH_IPC_ENABLED=false # Local IPC is enabled by default; false disables it
  271. # SHODH_IPC_ENDPOINT=/private/path/shodh-memory.sock # Optional platform-specific override
  272. # SHODH_IPC_REQUIRED=true # Fail closed instead of falling back to HTTP
  273. SHODH_REQUEST_TIMEOUT=60 # Request timeout in seconds
  274. SHODH_MAX_CONCURRENT=200 # Max concurrent requests
  275. SHODH_ROCKSDB_BLOCK_CACHE_MB=256 # Shared RocksDB block cache (MiB)
  276. SHODH_CE_RERANK=1 # Cross-encoder reranking (server default: on; 0 disables, e.g. for latency-bound robots)
  277. SHODH_CE_DEPTH=30 # Candidates the cross-encoder rescores (latency scales with this)
  278. # SHODH_CE_MODEL_PATH=/models/ce # Reranker assets; default: fetched on first start into the cache dir
  279. # SHODH_OFFLINE=true # Never download models; a missing reranker means unreranked recall
  280. SHODH_CORS_ORIGINS=https://app.example.com
  281. ```
  282. </details>
  283. The server enables authenticated local IPC by default and keeps HTTP available.
  284. Native `shodh serve` prefers the platform-default IPC endpoint and falls back to
  285. `SHODH_API_URL` unless fail-closed mode is enabled; the TypeScript MCP client uses IPC only when
  286. `SHODH_IPC_ENDPOINT` is set. See the [local IPC architecture](docs/architecture/07-local-ipc-transport.md)
  287. for platform defaults, security properties, and limitations.
  288. <details>
  289. <summary>Docker Compose with TLS</summary>
  290. ```yaml
  291. services:
  292. shodh-memory:
  293. image: varunshodh/shodh-memory:latest
  294. environment:
  295. - SHODH_ENV=production
  296. - SHODH_HOST=0.0.0.0
  297. - SHODH_API_KEYS=${SHODH_API_KEYS}
  298. volumes:
  299. - shodh-data:/data
  300. networks:
  301. - internal
  302. caddy:
  303. image: caddy:latest
  304. ports:
  305. - "443:443"
  306. volumes:
  307. - ./Caddyfile:/etc/caddy/Caddyfile
  308. networks:
  309. - internal
  310. volumes:
  311. shodh-data:
  312. networks:
  313. internal:
  314. ```
  315. </details>
  316. <details>
  317. <summary>Reverse proxy (Nginx / Caddy)</summary>
  318. The server binds to `127.0.0.1` by default. For network deployments, place behind a reverse proxy:
  319. ```caddyfile
  320. memory.example.com {
  321. reverse_proxy localhost:3030
  322. }
  323. ```
  324. </details>
  325. ## Community
  326. | Project | Description | Author |
  327. |---------|-------------|--------|
  328. | [SHODH on Cloudflare](https://github.com/doobidoo/shodh-cloudflare) | Edge-native implementation on Cloudflare Workers | [@doobidoo](https://github.com/doobidoo) |
  329. ## References
  330. [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*.
  331. ## License
  332. Apache 2.0
  333. ---
  334. <p align="center">
  335. <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>
  336. </p>
  337. <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>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.