Shodh-Memory

Persistent memory for AI agents. Single package. Local-first. Runs offline.

Give your AI agents memory that persists across sessions, learns from experience, and runs entirely on your hardware.

Installation

pip install shodh-memory

That's it. No additional setup required. Models and runtime are bundled.

Quick Start

from shodh_memory import Memory

# Create memory (data stored locally)
memory = Memory(storage_path="./my_agent_data")

# Store memories
memory.remember("User prefers dark mode", memory_type="Decision")
memory.remember("JWT tokens expire after 24h", memory_type="Learning")
memory.remember("Deployment failed due to missing env var", memory_type="Error")

# Search semantically
results = memory.recall("user preferences", limit=5)
for r in results:
    print(f"{r['content']} (importance: {r['importance']:.2f})")

# Get context summary for LLM bootstrap
summary = memory.context_summary()
print(summary["decisions"])  # Recent decisions
print(summary["learnings"])  # Recent learnings

Features

• Zero setup — Everything bundled. No API keys, no cloud, no Docker
• Semantic search — MiniLM embeddings for meaning-based retrieval
• Hebbian learning — Connections strengthen when memories are used together
• Activation decay — Unused memories fade naturally
• Idempotent — Content-hash dedup prevents duplicate memories
• Entity extraction — TinyBERT NER extracts people, orgs, locations
• 100% offline — Works on air-gapped systems

Memory Types

Different types get different importance weights:

API Reference

Core Memory

# Store a memory
memory.remember(
    content="...",           # Required: the memory content
    memory_type="Learning",  # Optional: Decision, Learning, Error, etc.
    tags=["tag1", "tag2"],   # Optional: for filtering
    metadata={"key": "val"}  # Optional: custom metadata dict
)

# Semantic search
results = memory.recall(
    query="...",             # Required: search query
    limit=10,                # Optional: max results (default: 10)
    mode="hybrid"            # Optional: semantic, associative, hybrid
)

# Search by tags (no embedding needed, fast)
results = memory.recall_by_tags(tags=["preferences", "ui"], limit=20)

# Search by date range
results = memory.recall_by_date(
    start="2025-12-01T00:00:00Z",
    end="2025-12-20T23:59:59Z",
    limit=20
)

# List all memories
memories = memory.list_memories(limit=100, memory_type="Decision")

# Get single memory by ID
mem = memory.get_memory("uuid-here")

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

Proactive Context (for Agent Loops)

# Surface relevant memories for current context
# Use in every agent loop to maintain context awareness
result = memory.proactive_context(
    context="User asking about authentication",  # Current conversation/task
    semantic_threshold=0.65,                      # Min similarity (0.0-1.0)
    max_results=5,                                # Max memories to return
    auto_ingest=True,                             # Store context as Conversation memory
    recency_weight=0.2                            # Boost recent memories
)

# Returns surfaced memories with relevance scores
for mem in result["memories"]:
    print(f"{mem['content'][:50]} (score: {mem['relevance_score']:.2f})")

Forget Operations

# Delete by ID
memory.forget("memory-uuid")

# Delete old memories
memory.forget_by_age(days=30)

# Delete low-importance memories
memory.forget_by_importance(threshold=0.3)

# Delete by pattern (regex)
memory.forget_by_pattern(r"test.*")

# Delete by tags
memory.forget_by_tags(["temporary", "draft"])

# Delete by date range (ISO 8601 format)
memory.forget_by_date(start="2025-11-01T00:00:00Z", end="2025-11-30T23:59:59Z")

# GDPR: Delete everything
memory.forget_all()

Context & Introspection

# Context summary for LLM bootstrap
summary = memory.context_summary(max_items=5)
# Returns: {"decisions": [...], "learnings": [...], "context": [...], "patterns": [...]}

# 3-tier memory visualization
state = memory.brain_state(longterm_limit=100)
# Returns: {"working_memory": [...], "session_memory": [...], "longterm_memory": [...], "stats": {...}}

# Memory learning activity report
report = memory.consolidation_report(since="2025-12-19T00:00:00Z")
# Returns: strengthening events, decay events, edge formations, pruned associations

# Raw consolidation events
events = memory.consolidation_events(since="2025-12-19T00:00:00Z")

# Knowledge graph statistics
graph = memory.graph_stats()
print(f"Nodes: {graph['node_count']}, Edges: {graph['edge_count']}")

# Flush to disk
memory.flush()

Index Health & Maintenance

# Verify vector index integrity
report = memory.verify_index()
print(f"Healthy: {report['is_healthy']}, Orphaned: {report['orphaned_count']}")

# Repair orphaned memories (re-index missing entries)
result = memory.repair_index()
print(f"Repaired: {result['repaired']}, Failed: {result['failed']}")

# Get detailed index health metrics
health = memory.index_health()
print(f"Vectors: {health['total_vectors']}, Needs rebuild: {health['needs_rebuild']}")

LLM Framework Integration

LangChain

from shodh_memory.integrations.langchain import ShodhMemory

# Use as LangChain memory
memory = ShodhMemory(storage_path="./langchain_data")

LlamaIndex

from shodh_memory.integrations.llamaindex import ShodhLlamaMemory

# Use as LlamaIndex memory
memory = ShodhLlamaMemory(storage_path="./llamaindex_data")

Performance

Measured on Intel i7-1355U (10 cores, 1.7GHz):

Architecture

Experiences flow through three tiers based on Cowan's working memory model:

Working Memory ──overflow──> Session Memory ──importance──> Long-Term Memory
   (100 items)                  (500 MB)                      (RocksDB)

Cognitive processing:

• Spreading activation retrieval
• Activation decay (exponential)
• Hebbian strengthening (co-retrieval strengthens connections)
• Long-term potentiation (frequently-used connections become permanent)
• Memory replay during maintenance
• Interference detection

Platform Support

Links

• GitHub
• Documentation
• npm (MCP Server)
• crates.io (Rust)

License

Apache 2.0