aeonica-memory

Aeonica Memory

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.

pip install aeonica-memory

---

What Makes It Different

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

---

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

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?

---

Quick Start

Installation

pip install aeonica-memory

Basic Usage

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

# 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

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

---

Features

Explainability

Every retrieval result includes:

Schema Detection

Aeonica automatically discovers patterns in your memories:

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

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

RetrievalResult

@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

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

---

Comparison

---

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

# 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

# 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

# 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:

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:

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:

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:

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:

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

---

Development

# 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

---

Support

• GitHub Issues: 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.