Neuroscience-inspired cognitive memory system for AI agents with offline single-binary deployment, three-layer memory architecture, Hebbian learning, and native MCP integration.
Overview#
Shodh-Memory is a neuroscience-inspired cognitive memory system for AI agents, implemented in Rust as a single binary (~17-30MB) with full offline capability. Features native MCP protocol integration with Claude/Cursor and provides Python/Rust/REST API interfaces.
Core Features#
Three-Layer Memory Architecture#
Based on Cowan's working memory model:
- Sensory Buffer: ~7 items, <1s decay
- Working Memory: ~4 chunks, minute-level decay
- Long-Term Memory: Unlimited capacity, Power-law decay
Cognitive Learning Mechanisms#
- Hebbian Learning: Co-retrieved memories form stronger connections
- Activation Decay:
A(t) = A₀ · e^(-λt) - Long-Term Potentiation (LTP): 10+ accesses reduce decay rate by 10x
- Memory Replay: Important memories replayed during maintenance cycles (simulating hippocampal replay)
Hybrid Retrieval System#
- Vector Index: HNSW semantic similarity
- Knowledge Graph: Entity relations + spreading activation
- Temporal Index: Time decay + sequential retrieval
- Hybrid Ranking: Combined vector + graph + temporal scoring
Performance Metrics#
| Operation | Latency |
|---|---|
| Store memory | 55-60ms |
| Semantic search | 34-58ms |
| Tag search | ~1ms |
| Entity lookup | 763ns |
| Graph traversal (3-hop) | 30µs |
Installation#
Docker#
docker run -d -p 3030:3030 -v shodh-data:/data varunshodh/shodh-memory
MCP Integration (Claude Code / Cursor)#
claude mcp add shodh-memory -- npx -y @shodh/memory-mcp
Python SDK#
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)
REST API (Port 3030)#
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/remember | Store memory |
| POST | /api/recall | Semantic search |
| POST | /api/proactive_context | Context-aware retrieval |
| POST | /api/reinforce | Hebbian feedback |
| POST | /api/todos/add | Create todo |
| GET | /api/projects | List projects |
Use Cases#
- AI agent cross-session memory persistence (Claude/GPT/Cursor)
- Edge device offline memory (Raspberry Pi, Jetson, industrial PCs)
- Robot/drone environmental memory
- Local-first AI applications (no cloud dependency, no external API keys)
Theoretical Foundation#
- Cowan, N. (2010) — Working Memory Capacity
- Wixted & Ebbesen (1991) — Power-law decay
- Bi & Poo (1998) — Long-Term Potentiation
- Anderson & Pirolli (1984) — Hebbian Strengthening
- Rasch & Born (2013) — Memory Replay