hippocampus-sharp-memory 1.0.0

Brain-inspired memory for AI agents. Ebbinghaus forgetting + Kanerva SDM + spaced recall. Sub-microsecond semantic lookup. Only remembers what matters.

🧠 hippocampus-sharp-memory

Brain-inspired memory for AI agents. Adaptive retention + Kanerva SDM + locality-sensitive hashing. Sub-microsecond semantic lookup at 46M memories. Only remembers what matters.

pip install hippocampus-sharp-memory

Why This Exists

Every AI agent framework stores chat history in a list. That's a to-do app pretending to be a brain.

Real brains don't work that way. They:

• Prioritize — low-value information fades, critical knowledge stays sharp
• Strengthen memories accessed repeatedly (spaced repetition)
• Associate related memories into webs (Kanerva SDM)
• Amplify emotional/critical events with higher salience
• Consolidate frequently-accessed memories during "sleep" cycles

This library does all of that in Rust, exposed to Python via zero-copy PyO3 bindings.

Quick Start

from hippocampus_sharp_memory import create_memory

mem = create_memory()

# Store memories with salience scores
mem.remember("user prefers dark mode", salience=30.0)
mem.remember("billing complaint about invoice #4821", salience=60.0)
mem.remember("CRITICAL: production database at 95% capacity", salience=90.0, emotional_tag=3)

# Semantic recall — finds relevant memories, not keyword matches
results = mem.recall("database storage issue", top_k=3)
for r in results:
    print(f"  [{r.retention*100:.0f}%] {r.content}")

The Recall-Before-LLM Pattern

The killer use case. Save 90% on LLM costs:

def handle_alert(alert_text: str, mem, llm_client):
    # Step 1: Check if we've seen this before
    cached = mem.recall(alert_text, top_k=1)
    if cached and cached[0].retention > 0.5:
        return cached[0].content  # Free! No LLM call needed

    # Step 2: Only call LLM for genuinely new situations
    explanation = llm_client.explain(alert_text)

    # Step 3: Cache the expensive LLM response
    mem.remember(
        f"LLM explanation for '{alert_text}': {explanation}",
        salience=60.0,
        source="llm_cache",
    )
    return explanation

Recurring alerts (CPU spikes, billing complaints, routine errors) get answered from memory. Novel situations still go to the LLM. Adaptive retention naturally phases out stale explanations.

Architecture

┌──────────────────────────────────────────────────┐
│                  Python API                       │
│  create_memory() → HippocampusEngine              │
├──────────────────────────────────────────────────┤
│                 Rust Core (PyO3)                  │
│  ┌─────────┐  ┌─────────┐  ┌──────────────────┐ │
│  │ SimHash  │→│ LSH     │→│ Context Scorer    │ │
│  │ 1024-bit │  │ 16 tables│  │ sim+recency+sal  │ │
│  │ address  │  │ O(1)    │  │ +emotion weighting│ │
│  └─────────┘  └─────────┘  └──────────────────┘ │
│  ┌─────────────┐  ┌──────────────────────────┐   │
│  │ Adaptive  │  │ Kanerva SDM              │   │
│  │ Retention │  │ Consolidated Long-Term   │   │
│  └─────────────┘  └──────────────────────────┘   │
│  ┌──────────────────────────────────────────┐    │
│  │ Deduplication (LSH exact-match)          │    │
│  │ Identical content → salience boost       │    │
│  └──────────────────────────────────────────┘    │
├──────────────────────────────────────────────────┤
│          Optional Disk Persistence                │
│  mmap'd records + quota enforcement + compaction  │
└──────────────────────────────────────────────────┘

API Reference

Factory Functions

from hippocampus_sharp_memory import create_memory, create_persistent_memory

# In-memory (fast, ephemeral)
mem = create_memory(capacity=500_000)

# Disk-backed (survives restarts, 7.5 GB default quota)
mem = create_persistent_memory(quota_gb=7.5)

Core Operations

Method	Description
mem.remember(content, salience, source="", emotional_tag=0)	Store a memory. Duplicates auto-merge.
mem.recall(query, top_k=5)	Semantic recall. Returns List[RecallResult].
mem.tick()	Advance time. Triggers adaptive retention + consolidation.
mem.advance(n)	Advance n ticks at once.
mem.relate(id_a, id_b)	Create associative link between memories.
mem.recall_related(id, depth=1)	Follow relationship web.
mem.recall_between(start, end, top_k=10)	Temporal range query.
mem.stats()	Returns HippocampusStats snapshot.
mem.consolidate()	Force a sleep-replay consolidation cycle.

RecallResult Fields

Field	Type	Description
content	str	The memory text
source	str	Origin tag
salience	float	Current importance score
retention	float	0.0–1.0, how well-retained
age_ticks	int	Ticks since creation
recall_count	int	Times this memory was recalled
consolidated	bool	Promoted to long-term storage

Emotional Tags

Value	Meaning	Salience Multiplier
0	Neutral	1.0×
1	Positive	1.2×
2	Negative	1.5×
3	Critical	3.0×

Performance

Benchmarked on a single core (Intel i7-12700K):

Scale	remember()	recall()	Memory
1K memories	2 μs	8 μs	~1 MB
10K memories	2 μs	20 μs	~8 MB
100K memories	3 μs	50 μs	~80 MB
1M memories	3 μs	120 μs	~800 MB
46M memories	4 μs	2 μs (LSH)	~37 GB

The LSH index provides O(1) query time regardless of memory count at scale. At 46M memories, recall is actually faster than at 1M because the LSH buckets are more selective.

Advanced Usage

Spaced Repetition

mem = create_memory(recall_reinforcement=1.3)
mem.remember("important pattern", salience=20.0)

# Each recall boosts salience by 1.3×
r1 = mem.recall("important pattern", top_k=1)  # salience: 20.0
r2 = mem.recall("important pattern", top_k=1)  # salience: 26.0
r3 = mem.recall("important pattern", top_k=1)  # salience: 33.8
# Frequently recalled = permanently retained

Automatic Deduplication

mem.remember("server alert: CPU at 95%", salience=20.0)
mem.remember("server alert: CPU at 95%", salience=20.0)  # Same content
mem.remember("server alert: CPU at 95%", salience=20.0)  # Again!

assert mem.episode_count == 1  # Only 1 episode stored
# Salience was boosted, not duplicated

Relationship Graphs

mem.remember("billing complaint", salience=30.0)       # id=0
mem.remember("escalation to manager", salience=50.0)    # id=1
mem.remember("legal threat received", salience=80.0)    # id=2

mem.relate(0, 1)  # complaint → escalation
mem.relate(1, 2)  # escalation → legal

# Follow the chain
related = mem.recall_related(0, depth=2)
# Returns: [escalation, legal threat]

Part of the Ebbiforge Ecosystem

hippocampus-sharp-memory is the standalone memory engine extracted from Ebbiforge — a full AI agent framework with:

• 100M-agent swarm simulation (Rust tensor engine)
• Compliance & PII redaction (OWASP, rate limiting, audit trails)
• Self-evolution (Darwinian agent selection, metacognition)
• Latent world model (predictive planning, diffusion predictor)

If you need just memory → pip install hippocampus-sharp-memory If you need the full stack → pip install ebbiforge

License

MIT © Ebbiforge Team