aeonica-memory 0.1.0
Governed AI memory for LLM agents and RAG systems - audit trails, Merkle proofs, GDPR-compliant deletion, temporal decay
Requires Python: >=3.8
Keywords: memory, faiss, vector-search, semantic-search, llm, rag, explainability, ai, langchain, retrieval, embeddings, audit-log, gdpr, compliance, merkle-proof, governance

# Aeonica Memory

[![PyPI version](https://badge.fury.io/py/aeonica-memory.svg)](https://badge.fury.io/py/aeonica-memory)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-81%20passing-brightgreen.svg)]()

**Governed AI memory for LLM agents and RAG systems.**

The only memory SDK with built-in audit trails, cryptographic proofs, GDPR-compliant deletion, and temporal decay.

```bash
pip install aeonica-memory
```

---

## What Makes It Different

Most vector stores just store and retrieve. Aeonica Memory gives you:

| Feature | What It Does | Why It Matters |
|---------|--------------|----------------|
| **Audit Trail** | Hash-chained log of every operation | Tamper-evident compliance |
| **State Proofs** | Merkle trees over memory state | Prove "what AI knew when" |
| **Deletion Certificates** | Cryptographic proof of deletion | GDPR Article 17 compliance |
| **Temporal Decay** | Memories fade over time | Human-like memory behavior |
| **RAG Tracing** | Full retrieval debugging | "Why did it retrieve X?" |
| **Explainability** | Natural language reasoning | Know *why*, not just *what* |

---

## What It Does

Aeonica Memory is a semantic memory SDK that wraps FAISS with:

1. **Governance** - Audit logs, Merkle proofs, deletion certificates
2. **Explainability** - Know *why* a memory was retrieved, not just *that* it was
3. **Temporal behavior** - Decay, importance, auto-expiration
4. **Developer-friendly API** - 3 lines to get started

```python
from aeonica_memory import MemoryClient

client = MemoryClient()
client.add("py_1", "Python uses indentation for code blocks")
results = client.query("How does Python structure code?", explain=True)

for r in results:
    print(f"{r.content}")
    print(f"  Confidence: {r.confidence_depth}")
    print(f"  Why: {r.explanation}")
```

---

## Why Aeonica Memory?

| Problem | Aeonica Solution |
|---------|------------------|
| FAISS returns scores, not explanations | Natural language reasoning for every result |
| No visibility into retrieval confidence | Cluster-based confidence depth |
| Pattern discovery is manual | Automatic schema detection |
| Vector DBs charge per query | $0 local inference, runs anywhere |
| Pinecone/Weaviate vendor lock-in | Open source, your data stays local |

---

## Quick Start

### Installation

```bash
pip install aeonica-memory
```

### Basic Usage

```python
from aeonica_memory import MemoryClient

# Initialize client
client = MemoryClient(backend="faiss", explainability=True)

# Add memories
client.add("auth_1", "OAuth 2.0 uses token-based authentication")
client.add("auth_2", "JWT tokens provide stateless authentication")
client.add("auth_3", "API keys are simple but less secure than OAuth")

# Query with explainability
results = client.query("How do I authenticate API requests?", top_k=3)

for r in results:
    print(f"[{r.score:.2f}] {r.content}")
    print(f"         {r.explanation}")
```

**Output:**
```
[0.89] OAuth 2.0 uses token-based authentication
       Very strong semantic match to your query - part of a pattern with 3 similar cases

[0.84] JWT tokens provide stateless authentication
       Strong semantic similarity to your query - backed by 3 similar cases in memory

[0.71] API keys are simple but less secure than OAuth
       Moderate semantic relevance to your query
```

### Batch Operations

```python
# Efficient batch add
memories = [
    ("mem_1", "Python uses indentation", {"topic": "syntax"}),
    ("mem_2", "JavaScript uses braces", {"topic": "syntax"}),
    ("mem_3", "SQL queries databases", {"topic": "data"}),
]
client.add_batch(memories)
```

### Web Playground

```bash
pip install 'aeonica-memory[playground]'
aeonica-memory playground
# Opens at http://localhost:8000
```

---

## Features

### Explainability

Every retrieval result includes:

| Field | Description | Example |
|-------|-------------|---------|
| `confidence_depth` | How many similar memories back this result | "High confidence (based on 23 similar cases)" |
| `schema_label` | Detected pattern this memory belongs to | "Pattern: API authentication flows" |
| `explanation` | Natural language reasoning | "Strong semantic match - part of a pattern with 5 similar cases" |

### Schema Detection

Aeonica automatically discovers patterns in your memories:

```python
stats = client.get_stats()
print(f"Detected {stats['total_schemas']} patterns")
print(f"Average cluster size: {stats['avg_cluster_size']}")
```

### Pure FAISS Performance

Under the hood: battle-tested FAISS with `IndexFlatIP` for cosine similarity.

- **Embedding model:** `all-MiniLM-L6-v2` (384 dims)
- **Search:** C++ SIMD-optimized similarity
- **Cost:** $0 (local inference)

---

## API Reference

### MemoryClient

```python
client = MemoryClient(
    backend="faiss",           # Only "faiss" supported currently
    explainability=True,       # Enable confidence, schemas, reasoning
    embedding_model="all-MiniLM-L6-v2",  # Sentence transformer model
    storage_path=None,         # Path for persistence (Pro feature)
)
```

### Methods

| Method | Description |
|--------|-------------|
| `add(id, content, metadata)` | Add a single memory |
| `add_batch(memories)` | Add multiple memories efficiently |
| `query(query, top_k, explain)` | Query with optional explainability |
| `get_stats()` | Get memory statistics |

### RetrievalResult

```python
@dataclass
class RetrievalResult:
    id: str                    # Memory identifier
    content: str               # Memory content
    score: float               # Similarity score (0-1)
    confidence_depth: str      # "High confidence (based on N similar cases)"
    schema_label: str          # "Pattern: ..." or None
    explanation: str           # Natural language reasoning
    metadata: dict             # User-provided metadata
```

---

## Pricing

| Tier | Price | Features |
|------|-------|----------|
| **Free** | $0 | Full SDK, 10K memories, community support |
| **Pro** | $29/mo | Persistence, filtering, priority support, 100K memories |
| **Team** | $79/mo | 5 users, SSO, shared collections, 500K memories |
| **Enterprise** | Custom | On-prem, SLA, unlimited memories |

Core is open source. Paid tiers add persistence, support, and team features.

---

## Comparison

| Feature | Aeonica | FAISS | Pinecone | Weaviate |
|---------|---------|-------|----------|----------|
| Explainability | Yes | No | No | No |
| Confidence depth | Yes | No | No | No |
| Schema detection | Yes | No | No | No |
| Local/private | Yes | Yes | No | No |
| Cost | $0 | $0 | $70+/mo | $90+/mo |
| Setup time | 3 lines | 50+ lines | Account + API | Account + API |

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     MemoryClient                            │
│  - add() / add_batch() / query()                           │
│  - Explainability layer                                     │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                  HybridRetrieverFAISS                       │
│  - FAISS IndexFlatIP (cosine similarity)                   │
│  - Sentence transformer embeddings                          │
│  - Optional harmonic reasoning (experimental)               │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                  Explainability Components                  │
│  - ConfidenceTracker (cluster-based)                       │
│  - SchemaDetector (pattern discovery)                       │
│  - ExplanationGenerator (natural language)                  │
└─────────────────────────────────────────────────────────────┘
```

---

## Use Cases

### LLM Agent Memory

```python
# Store agent interactions
client.add(f"turn_{i}", f"User asked about {topic}, agent responded with {response}")

# Retrieve relevant context for next turn
context = client.query(user_message, top_k=5)
```

### RAG Systems

```python
# Index documents
for doc in documents:
    client.add(doc.id, doc.text, metadata={"source": doc.source})

# Retrieve with explainability
results = client.query(question, explain=True)
# Now you can cite WHY each source was selected
```

### Knowledge Bases

```python
# Build team knowledge base
client.add_batch([(id, content, {"author": author}) for ...])

# Query with confidence
results = client.query("How do we handle X?")
# "High confidence based on 15 similar cases" vs "Unique case"
```

---

## Governance Module (Enterprise)

The `aeonica_memory.governance` module provides enterprise-grade compliance, audit, and observability features for regulated industries.

### Audit Logging

Every memory operation is logged with cryptographic integrity:

```python
from aeonica_memory import MemoryClient
from aeonica_memory.governance import AuditLog, OperationType

# Create audit log
audit = AuditLog("./audit.jsonl")

# Log operations
entry = audit.log_add(
    memory_id="doc_1",
    content_hash="sha256:abc123...",
    state_root="sha256:xyz789..."
)

# Verify chain integrity (tamper detection)
if audit.verify_chain():
    print("Audit log is intact")

# Get history for compliance
history = audit.get_history("doc_1")
for e in history:
    print(f"{e.timestamp}: {e.operation.value}")
```

### Merkle Tree State Proofs

Prove what the AI knew at any point in time:

```python
from aeonica_memory.governance import StateProver

prover = StateProver(client)

# Compute current state root
root = prover.compute_state_root()

# Prove a specific memory was in the state
proof = prover.prove_inclusion("doc_1")

# Verify the proof (can be done by third party)
is_valid = prover.verify_proof(proof)

# Prove retrieval results came from specific state
query_proof = prover.prove_retrieval(["doc_1", "doc_2"], query_hash)
```

### Compliant Deletion (GDPR)

GDPR "right to be forgotten" with cryptographic proof:

```python
from aeonica_memory.governance import DeletionCertifier, verify_deletion_certificate_standalone

# Setup certifier
certifier = DeletionCertifier(client, audit_log=audit, state_prover=prover)

# Delete with certificate
cert = certifier.delete_with_certificate(
    "user_123_data",
    reason="GDPR Article 17 request",
    rebuild_index=True  # Eliminates semantic residue
)

# Certificate proves deletion
print(cert.to_json())
# {
#   "certificate_id": "del_abc123...",
#   "memory_id": "user_123_data",
#   "pre_state_root": "sha256:...",
#   "post_state_root": "sha256:...",
#   "content_hash": "sha256:...",
#   "deletion_timestamp": "2025-03-15T10:30:00+00:00",
#   "index_rebuilt": true
# }

# Third-party verification (no access to system needed)
result = verify_deletion_certificate_standalone(cert_json)
print(result["verified"])  # True
```

### Temporal Memory

Time-aware memory with decay and importance scoring:

```python
from aeonica_memory.governance import TemporalMemory, ExponentialDecay

# Wrap client with temporal features
temporal = TemporalMemory(
    client,
    decay_function=ExponentialDecay(half_life_days=30)
)

# Add with importance (critical info persists longer)
temporal.add("policy_update", "New vacation policy...", importance=0.9)

# Add with expiration (auto-deletes after 2 days)
temporal.add("temp_notice", "Office closed tomorrow", expires_in_days=2)

# Query with temporal scoring
# Final score = semantic_similarity * temporal_decay * importance
results = temporal.query("vacation policy")

# Run maintenance (archive old, delete expired)
archived, deleted = temporal.run_maintenance(
    archive_threshold=0.1,
    delete_expired=True
)
```

**Decay Functions:**
- `ExponentialDecay`: Natural forgetting curve (default)
- `LinearDecay`: Steady decrease to zero
- `StepDecay`: Defined retention periods (regulatory)
- `NoDecay`: Memories never fade

### Retrieval Tracing

Full observability for RAG debugging:

```python
from aeonica_memory.governance import RetrievalTracer, create_retrieval_report

tracer = RetrievalTracer(client)

# Query with full tracing
results = tracer.traced_query("What is the policy?", top_k=5)

# Get trace details
trace = tracer.get_latest_trace()
print(f"Retrieved {len(trace.final_results)} docs in {trace.total_latency_ms:.1f}ms")

# Human-readable report
print(create_retrieval_report(trace))

# Detailed analysis
analysis = tracer.analyze_trace(trace.trace_id)
print(f"Score range: {analysis['scores']['min']:.3f} - {analysis['scores']['max']:.3f}")
print(f"Issues: {analysis['potential_issues']}")

# Compare traces (A/B testing)
comparison = tracer.compare_traces(trace_id_1, trace_id_2)
print(f"Jaccard similarity: {comparison['comparison']['jaccard_similarity']:.2f}")
```

---

## Roadmap

| Version | Features | Status |
|---------|----------|--------|
| 0.1.0 | Core SDK, explainability, playground | Current |
| 0.2.0 | Persistence (save/load) | Done |
| 0.3.0 | Metadata filtering, CRUD | Done |
| 0.4.0 | Governance module (audit, proofs, deletion) | Done |
| 0.5.0 | LangChain integration | Done |
| 1.0.0 | Production-ready, full documentation | Planned |

---

## Development

```bash
# Clone
git clone https://github.com/aeonica-labs/aeonica-memory
cd aeonica-memory

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black aeonica_memory/
ruff aeonica_memory/
```

---

## License

MIT License - See [LICENSE](LICENSE)

---

## Support

- **GitHub Issues:** [github.com/aeonica-labs/aeonica-memory/issues](https://github.com/aeonica-labs/aeonica-memory/issues)
- **Email:** support@aeonica.dev
- **Discord:** Coming soon

---

**Built by Aeonica Labs**

*Fast, explainable memory for the AI era.*