The Missing Brain for Stateless LLMs

Memory That LearnsFor Claude, GPT & Your Agents

LLMs are stateless. Every conversation starts from scratch. Shodh Memory gives them persistent memory that strengthens with use. Hebbian learning, spreading activation, 3-tier cognitive architecture.

One-liner setup for Claude Code & Desktop.37 MCP tools for memory, todos, reminders.Python SDK for custom agents.

Get Started Documentation

759

Tests Passing

MCP Tools

66k+

Lines of Code

100%

Offline

The Problem: LLMs Are Stateless

Every conversation with Claude or GPT starts from scratch. They forget what you told them yesterday. They can't learn from past mistakes. They rediscover the same patterns again and again.

Without Memory

✗Repeats same mistakes across sessions
✗Forgets user preferences and context
✗Can't learn from successful patterns
✗No accumulated project knowledge

With Shodh Memory

✓Remembers errors and avoids them
✓Builds persistent user model
✓Strengthens useful associations (Hebbian)
✓Accumulates domain expertise over time

One Line to Remember Everything

Add persistent memory to Claude Code, Claude Desktop, or Cursor with a single config line

MCP Configuration - Works Instantly

// Add to your MCP config file
{
  "mcpServers": {
    "shodh-memory": {
      "command": "npx",
      "args": ["-y", "@shodh/memory-mcp"],
      "env": {
        "SHODH_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

~/.claude/claude_code_config.json

Claude Desktop

claude_desktop_config.json

Cursor

~/.cursor/mcp.json

What you get: Claude remembers your decisions, learned patterns, errors to avoid, and project context across all sessions. Memories strengthen when retrieved together (Hebbian learning).

Claude Code

Add persistent memory to your CLI coding sessions

One line in claude_code_config.json

Claude Desktop

Remember conversations across chat sessions

One line in claude_desktop_config.json

Cursor IDE

Give your AI coding assistant project memory

Add to ~/.cursor/mcp.json

LangChain / AutoGPT

Persistent memory for autonomous agents

Python SDK or REST API

37 MCP Tools

More than just memory - a complete cognitive toolkit for AI agents

Memory

rememberrecallrecall_by_tagsrecall_by_dateforgetforget_by_tagsforget_by_datelist_memoriescontext_summaryproactive_context

Todos

add_todolist_todosupdate_todocomplete_tododelete_todoreorder_todolist_subtaskstodo_stats

Projects

add_projectlist_projectsarchive_projectdelete_project

Reminders

set_reminderlist_remindersdismiss_reminder

System

memory_statsverify_indexrepair_indexconsolidation_reportstreaming_statustoken_statusreset_token_session

Not Just Memory

Built-in task management, reminders, and a TUI dashboard for introspection

GTD Todos

Full GTD workflow with projects, contexts (@computer, @phone), priorities, due dates, and subtasks.

Smart Reminders

Time-based, duration-based, or context-triggered reminders that surface when relevant keywords appear.

Projects

Organize todos into projects with sub-project support. Archive when done. Codebase indexing for file context.

TUI Dashboard

Terminal UI for memory introspection. Watch memories form, see Hebbian strengthening, browse knowledge graph.

Proactive Context

The proactive_context tool automatically surfaces relevant memories based on the current conversation. Claude doesn't need to search - context appears when it's needed. This is how biological memory works: associations activate related memories without conscious effort.

Python SDK for Custom Agents

Build agents that learn from experience

pip install shodh-memory

from shodh_memory import Memory

# Initialize (auto-starts server if needed)
memory = Memory(api_key="your-api-key", storage_path="./my_agent_memory")

# Store memories with types for importance weighting
memory.remember("User prefers dark mode", memory_type="Decision")
memory.remember("JWT tokens expire after 24h", memory_type="Learning")
memory.remember("Don't use deprecated API v1", memory_type="Error")

# Semantic search - finds related memories
results = memory.recall("user preferences", limit=5)
for mem in results:
    print(f"{mem['content']} (importance: {mem.get('importance', 0):.2f})")

# Hybrid retrieval - semantic + graph associations
results = memory.recall("authentication", mode="hybrid", limit=10)

# Get context summary for LLM bootstrap
summary = memory.context_summary()
# Returns: decisions, learnings, errors, patterns - structured for prompts

# Memory statistics
stats = memory.get_stats()
print(f"Total memories: {stats['total_memories']}")

Memory Types: Decision (+0.30), Learning (+0.25), Error (+0.25), Discovery (+0.20), Task (+0.15), Context (+0.10)

Retrieval Modes: semantic (vector), associative (graph), hybrid (density-weighted combination)

Cognitive Architecture

Based on neuroscience research - Cowan's working memory model, Hebbian plasticity, spreading activation

Hebbian Learning

Memories strengthen when retrieved together - just like biological synapses

Co-activated memories form edges; 5+ co-activations become permanent

3-Tier Cognitive Architecture

Working → Session → Long-term memory based on Cowan's model

Sub-ms working memory, automatic promotion based on importance

Knowledge Graph

Entities, relationships, and spreading activation retrieval

763ns entity lookup, 32μs 3-hop traversal

100% Local & Private

Single ~18MB binary. No cloud. No data leaves your machine.

RocksDB storage, works completely offline

Sub-millisecond Graph Ops

Rust-native performance for real-time agent decisions

~55ms store (with embedding), ~45ms semantic search

Hybrid Retrieval

Semantic, associative, and hybrid search modes

Density-dependent weighting adapts to your usage patterns

How It Works

3-tier memory + knowledge graph + Hebbian learning

┌──────────────────────────────────────────────────────────────────┐
│                     SHODH MEMORY ARCHITECTURE                     │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │              WORKING MEMORY (LRU Cache)                    │  │
│  │  • 100 most recent/frequent memories                       │  │
│  │  • Retrieval: <1ms                                         │  │
│  │  • High importance items promoted here                     │  │
│  └────────────────────────────────────────────────────────────┘  │
│                          ↓ overflow ↑ access                     │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │              SESSION MEMORY (Bounded)                      │  │
│  │  • Current session context                                 │  │
│  │  • Retrieval: <10ms                                        │  │
│  │  • Promotion threshold: importance > 0.6                   │  │
│  └────────────────────────────────────────────────────────────┘  │
│                          ↓ consolidation ↑ recall                │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │              LONG-TERM MEMORY (RocksDB)                    │  │
│  │  • Persistent storage with LZ4 compression                 │  │
│  │  • Retrieval: <100ms                                       │  │
│  │  • Semantic consolidation after 7+ days                    │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │              KNOWLEDGE GRAPH (Hebbian)                     │  │
│  │                                                            │  │
│  │  Memory A ──co-retrieved──▶ Memory B                       │  │
│  │      │                          │                          │  │
│  │      └────strengthens───────────┘                          │  │
│  │                                                            │  │
│  │  • Edges form on co-retrieval (Hebbian learning)           │  │
│  │  • 5+ co-activations = Long-Term Potentiation (permanent)  │  │
│  │  • Unused edges decay over time                            │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │              VECTOR INDEX (Vamana HNSW)                    │  │
│  │  • MiniLM-L6-v2 embeddings (384-dim, 25MB model)           │  │
│  │  • TinyBERT NER for entity extraction (15MB model)         │  │
│  │  • Approximate nearest neighbor search                     │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Automatic Consolidation

Important memories promote up the hierarchy; old memories compress into semantic facts

Spreading Activation

Queries activate related memories through graph connections, not just vector similarity

Durable Storage

RocksDB with LZ4 compression. Survives restarts. Works offline.

Benchmark Results

Criterion benchmarks on Intel i7-1355U, release build

Operation	Latency	Notes
Entity Get (1000)	810ns	O(1) hash lookup
Entity Search	990ns	Sub-microsecond
Relationship Query	2.3μs	Graph traversal
3-hop Traversal	32.8μs	Deep graph walk
Hebbian Strengthen	6.2μs	Synapse update
Remember (full)	55-60ms	Embedding + NER + store
Recall (semantic)	34-58ms	Vector search + rank
Recall (tags)	~1ms	Index lookup

vs. Alternatives

Local-first alternative to cloud memory services

Feature	Shodh Memory	Mem0	LangChain Memory
Store memory	55-60ms	100-500ms	Varies
Semantic search	34-58ms	200-500ms	Varies
Graph operations	<1μs	N/A	N/A
Deployment	Local binary	Cloud API	Cloud DBs
Offline support	100%	No	Partial
Learning algorithm	Hebbian + LTP	None	None
MCP support	Native (37 tools)	No	No
Task management	Built-in	No	No
Reminders	Built-in	No	No
Proactive context	Yes	No	No
Binary size	~18MB	Cloud	Cloud

Why Local Matters

Your agent's memories contain sensitive context - user preferences, business logic, learned patterns. Shodh Memory keeps everything on your machine. No cloud API calls, no data transmission, no vendor lock-in. Works completely offline.

Give Your AI a Brain

One-liner for Claude. Python SDK for custom agents. REST API for everything else.

Get Started View on GitHub

PyPI npm crates.io