varun29ankuS/shodh-memory

AI Agents & Assistants

Cognitive memory for AI agents with Hebbian learning, 3-tier architecture, and knowledge graphs. Single ~15MB binary, runs offline on edge devices.

Track releases GitHub Website

Rust Latest v0.2.0 · 1mo ago Security brief →

Features

Persistent, algorithmic memory that learns from usage (Hebbian learning)
Automatic decay of irrelevant data without external services
Runs fully offline with a single ~17 MB binary
Supports AI agents via MCP/HTTP and robotics via Zenoh/ROS2

Recent releases

View all 8 releases →

v0.2.0 Breaking risk 1mo

Breaking changes

Serialization changed from bincode to postcard; all write paths now use postcard, read paths dual-decode (postcard-first fallback). Offline migration required via `shodh-memory-server migrate --storage`.

Notable features

Entity salience reward loop propagates recall feedback to graph
NER filter expansion adds 6 new entity filtering rules
Curvature-weighted retrieval incorporates graph-informed entity filtering

Full changelog

v0.2.0

Breaking Changes

Serialization: bincode → postcard — All write paths now use postcard. Read paths dual-decode (postcard-first, legacy fallback). Offline migration: shodh-memory-server migrate --storage <path>.

New Features

Entity salience reward loop — recall feedback propagates to graph (#217)
NER filter expansion — 6 new entity filtering rules (#215)
Curvature-weighted retrieval — graph-informed entity filtering (#214)
Causal lineage inference — automatic on remember, 7 relation types
Fact-aware recall scoring — high-confidence facts boost source memories
Glacial fact decay — exponential half-life replaces linear decay

Fixes

MCP process orphan bug — stdin EOF detection, WebSocket cleanup (#218)
Docker image — pre-baked models, zero-download startup (#219)
Temporal retrieval — unified parsing, created_at proximity (#197)
MCP reliability — race condition, timeout, error handling (#196)
MCP env vars — SHODH_HOST/SHODH_PORT respected (#195)
Edge pruning log spam reduced to debug level
ORT init logging auditable (eprintln before tracing init)

Infrastructure

Postcard serialization with SHO envelope format tags
SHA-256 checksum verification for Docker-baked models
OOM fix: bincode decode limit 10MB

View release on GitHub

v0.1.91 Security relevant 2mo

Security fixes

Remediated semgrep-detected shell injection and command execution vulnerabilities (fix(security))

Notable features

Unified shodh CLI implementation

Full changelog

What's Changed

fix(security): remediate semgrep shell injection and command execution findings by @gourmetfire in https://github.com/varun29ankuS/shodh-memory/pull/111
feat: unified shodh CLI (closes #12) by @varun29ankuS in https://github.com/varun29ankuS/shodh-memory/pull/113

Full Changelog: https://github.com/varun29ankuS/shodh-memory/compare/v0.1.90...v0.1.91

View release on GitHub

v0.1.90 New feature 2mo

Security fixes

API key validation now uses constant‑time comparison
Request size limits and input sanitization added to all endpoints
WebSocket authentication scoped per connection

Notable features

Remember Idempotency: SHA-256 content deduplication returns existing memory ID instead of creating duplicates
RocksDB consolidation reduces file descriptors from 20 to 3 per user (storage, graph, shared) with lazy migration
Zero‑config local setup auto‑generates API key, downloads models (~38 MB), and starts serving without env vars or Docker

Full changelog

What's New

Remember Idempotency (SHA-256 Content Dedup)

Identical memories are never stored twice. Every remember() call now computes a content hash — if the same content already exists, it returns the existing memory ID instead of creating a duplicate. This makes the entire ingestion pipeline safe for retry, batch processing, and multi-agent scenarios.

Security Hardening

API key validation with constant-time comparison
Request size limits and input sanitization across all endpoints
WebSocket authentication scoped per connection
CORS and security headers on all responses

RocksDB Consolidation (20 → 3 DBs)

Column family migration reduced file descriptor usage by ~85%. Each user's data now lives in 3 RocksDB instances (storage, graph, shared) instead of 20 separate databases. Migration is lazy and transparent — old data directories are renamed on first access.

Zero-Config Local Setup

First run auto-generates an API key, downloads models (~38MB), and starts serving. No environment variables, no Docker, no configuration files needed.

Performance

remember() API response: <200ms (was 5-15s with sync processing)
Fire-and-forget post-processing for embeddings, NER, and graph updates
Shared RocksDB block cache capped at 256MB
Entity embedding cache capped at 10K entries
jemalloc enabled for RocksDB on Linux/macOS

Bug Fixes (40+)

Fix retrieval_mode not skipping graph traversal in semantic recall
Fix Windows MCP server spawn EINVAL and truncated UUIDs
Fix read_memory returning 'undefined' when LLM sends id instead of memory_id
Fix stuck 429 rate limit on resource-constrained systems
Fix mmap vector loading on Windows
Fix backup/restore covering todos, reminders, facts, and audit logs
Fix pre-migration directory cleanup across all modules

47 MCP Tools

Full GTD task management (todos, projects, subtasks, comments), reminders (time/duration/context triggers), backup/restore, and index health monitoring — all available to Claude, Cursor, and other MCP clients.

Updated TUI Dashboard

New recall view and projects/todos screenshots.

114 commits since v0.1.80. Full changelog: https://github.com/varun29ankuS/shodh-memory/compare/v0.1.80...v0.1.90

Install

# MCP (Claude Code / Cursor)
claude mcp add shodh-memory -- npx -y @shodh/memory-mcp

# Python
pip install shodh-memory==0.1.90

# Rust
cargo add [email protected]

# Docker
docker run -d -p 3030:3030 -v shodh-data:/data varunshodh/shodh-memory:0.1.90

View release on GitHub

v0.1.80 New feature 3mo

Notable features

OpenAI Agents SDK integration with eight FunctionTool instances (remember, recall, forget, context_summary, proactive_context, add_todo, list_todos, complete_todo)
Agent orchestration system for Claude Code with automatic memory encoding and session continuity
Skills framework enabling parallel sub‑agent workflows

Full changelog

What's New in 0.1.80

OpenAI Agents SDK Integration

ShodhTools: 8 FunctionTool instances (remember, recall, forget, context_summary, proactive_context, add_todo, list_todos, complete_todo) for explicit memory operations
ShodhSession: Session protocol implementation with cognitive memory — semantic retrieval instead of sequential replay, Hebbian strengthening on access, automatic decay
Install: pip install shodh-memory[openai-agents]

Agent Orchestration

Hook-based orchestration system for Claude Code — automatic memory encoding on tool use, proactive context surfacing, session continuity
Skills framework for decomposing complex tasks into parallel sub-agent workflows

Citation Support

CITATION.cff for GitHub's "Cite this repository" button
References: Wixted 2004, Cowan 2001, Hebb 1949, Anderson & Pirolli 1984, Bi & Poo 1998

Fixes

Windows stdin compatibility for memory hook (top-level await)
Full proactive context pipeline activation
Forget/delete lifecycle: BM25 cleanup, soft-forget index removal, GDPR-compliant erasure
Cleaned crate package excludes (179 → 133 files)

Binary Size

Server binary: 25 MB (stripped, LTO, single codegen unit)
ONNX Runtime: 14 MB (dynamic, downloaded on first run)
Total: ~39 MB
MiniLM model: ~23 MB (quantized, downloaded on first embedding)

Install

| Package | Registry | Command |
|---------|----------|---------|
| shodh-memory | crates.io | cargo install shodh-memory |
| @shodh/memory-mcp | npm | npx @shodh/memory-mcp |
| shodh-memory | PyPI | pip install shodh-memory |