Technical Briefing: shodh-memory

The Problem

AI agents typically forget everything between sessions, repeating mistakes and losing context. Most memory systems delegate storage intelligence to LLM API calls — making them slow, expensive, and dependent on external services. This repository presents an alternative: algorithmic memory management using local embeddings, mathematical decay, and learned associations with zero LLM calls in the storage loop.

What This Does

shodh-memory is a collection of 12 self-contained projects providing persistent, learning memory for AI agents. The core (src/) contains 101 files organizing memory storage, retrieval, and graph operations around MemorySystem and MemoryConfig types. Twelve benchmarks (benches/) measure adaptive memory, cognitive load, graph statistics, and Hebbian reinforcement. Five integration projects (shodh-whatsapp/, shodh-telegram/, shodh-todoist/, mcp-server/, shodh-whatsapp/) embed the memory core into messaging and productivity platforms. Two data-only directories (python/, benches/) supply test harnesses and pipeline scripts. Execution begins at src/main.rs:141 (main), which reaches 151 functions; an alternate entry async_main at line 178 reaches 144 functions. The binary is ~17MB, fully offline, with no API keys or external databases required.

How It Is Wired

Execution flows from src/main.rs through main → session handling → memory operations. The internal call graph contains 6000 resolved call edges between self-contained functions. Hub functions with the widest blast radius: is_empty (223 call sites), MemoryId (172), remember (167), insert (124), validate_user_id (117). src/memory/types.rs defines default experience types and is called from 59 other files; src/memory/hybrid_search.rs defines weighting defaults (BM25, vector, graph) and is called from 61 files; src/memory/retrieval.rs implements insert/remove_all and is called from 45 files. A traced path from main reaches the network via handle_session_start [network through client.post]. src/handlers/state.rs rotates audit logs; src/memory/storage.rs manages persistence. The module graph shows no circular dependencies across 196 analyzed files, but 19 oversized files (e.g., src/graph_memory.rs at 145 functions, src/ab_testing.rs at 94) create compilation and modification risk — a change in src/graph_memory.rs ripples through 20 callers.

How To Use It

Setup: cargo build --release produces the binary; docker run -d -p 3030:3030 -v shodh-data:/data varunshodh/shodh-memory starts the MCP server. Python: pip install shodh-memory. Rust: add shodh-memory = "0.1" to Cargo.toml.

Configuration: No environment variables required for local use. For remote MCP deployment, .env.example documents SHODH_API_KEY (generated automatically). The MCP server config lives at .mcp.json.

Running it: claude mcp add shodh-memory -- npx -y @shodh/memory-mcp auto-downloads the backend binary. Python API: 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).

Real-World Use

An AI agent integrated via the MCP server retains user preferences across sessions without API calls. After the agent recalls "user prefers dark mode," the Hebbian reinforcement pathway (bench_reinforce_helpful in benches/) strengthens that memory's salience score, making it surface faster on subsequent recalls. Irrelevant memories decay via a time-weighted function — the consolidator (bench_consolidator_creation, bench_consolidator_with_thresholds) prunes below a configurable threshold. In a Telegram bot (shodh-telegram/src/index.ts), each user message passes through setup_memory_system → remember → graph insertion, so context persists across bot restarts. A Todoist integration (shodh-todoist/src/index.ts) records tasks as Memory entries with metadata, enabling natural-language recall of past commitments.

Code Health & Issues

The static analysis (196 of 196 code files) identified 153 findings across 6 kinds:

  • [HIGH/cognitive_load] Deep nesting x37 in benches/adaptive_memory_benchmarks.rs, benches/cognitive_benchmarks.rs, benches/graph_benchmarks.rs — max indentation depth 9; flatten with guard clauses.
  • [HIGH/cognitive_load] Oversized files x19 — src/ab_testing.rs (1776 lines), src/graph_memory.rs, src/handlers/recall.rs — split into cohesive units.
  • [MEDIUM/cognitive_load] High branching density in shodh-whatsapp/src/config.ts — 23 branch points over 65 lines; decompose with strategy dispatch.
  • [MEDIUM/resilience] Empty catch block in shodh-todoist/src/sync.ts — silently discards errors; handle or log.
  • [HIGH/clarity] 503 repeated 6-line blocks across 101 files in benchmarks — extract shared helpers.
  • [MEDIUM/resource_safety] python/shodh_memory/client.py — open(...) not wrapped in with; handle may leak.

SDLC observations: 10 code-health findings (0 critical, 2 high, 6 medium, 2 low). Two high-severity items target the CI workflow: GitHub Actions pinned to version tags (e.g., dtolnay/rust-toolchain@stable) rather than commit SHAs, and exit codes discarded on steps at .github/workflows/ci.yml lines 178, 193, 195 — a crash produces a green job on stale data. Medium items include missing Dependabot/ Renovate configuration, untagged Docker base images (rust:1-slim-bookworm, debian:bookworm-slim), and persist-credentials: true on checkout keeping the GITHUB_TOKEN available to all later steps.

The Bottom Line

shodh-memory delivers offline, learning memory for AI agents without API dependencies — a meaningful trade-off for privacy-constrained or air-gapped deployments. The codebase shows genuine technical ambition (Hebbian reinforcement, graph-based retrieval, decay functions) but carries structural debt from its fragmented 12-project layout and nested control flow in benchmark files exceeding 1000 lines. Teams needing rapid integration will favor the MCP server or pip package; groups requiring customization should budget refactor time for the oversized source files and duplicated benchmark logic.