Metadata-Version: 2.4
Name: hippocampus-sharp-memory
Version: 1.0.0
Summary: Brain-inspired memory for AI agents. Ebbinghaus forgetting + Kanerva SDM + spaced recall. Sub-microsecond semantic lookup. Only remembers what matters.
Project-URL: Homepage, https://github.com/juyterman1000/hippocampus-sharp-memory
Project-URL: Documentation, https://github.com/juyterman1000/hippocampus-sharp-memory#readme
Project-URL: Repository, https://github.com/juyterman1000/hippocampus-sharp-memory
Project-URL: Bug Tracker, https://github.com/juyterman1000/hippocampus-sharp-memory/issues
Project-URL: Full Framework, https://github.com/juyterman1000/ebbiforge
Author-email: Ebbiforge Team <fastrunner10090@gmail.com>
License: MIT
Keywords: agents,ai,associative-memory,chatbot,ebbinghaus,forgetting,hippocampus,kanerva,llm,memory,rag,recall,sdm,semantic-search
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: ebbiforge>=4.0.0
Description-Content-Type: text/markdown

# 🧠 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.

```bash
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

```python
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:**

```python
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

```python
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

```python
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

```python
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

```python
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](https://github.com/juyterman1000/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
