Aura Memory

Aura turns fragile prompt-only agents into auditable, memory-aware, production-ready systems

Deterministic · No fine-tuning · No cloud training · Local recall · No required embeddings

Your AI model is smart. But it forgets everything after every conversation.

Aura is a local cognitive runtime that runs alongside any frozen model. It gives agents durable memory, explainability, governed correction, bounded recall reranking, and bounded self-adaptation through experience — all locally, without fine-tuning or cloud training.

pip install aura-memory

from aura import Aura, Level

brain = Aura("./agent_memory")
brain.enable_full_cognitive_stack()  # activate all four bounded reranking overlays

# store what happens
brain.store("User always deploys to staging first", level=Level.Domain, tags=["workflow"])
brain.store("Staging deploy prevented 3 production incidents", level=Level.Domain, tags=["workflow"])

# recall — local retrieval with optional bounded cognitive reranking
context = brain.recall("deployment decision")  # local retrieval, no API call

# inspect advisory hints produced from stored evidence
hints = brain.get_surfaced_policy_hints()
# → [{"action": "Prefer", "domain": "workflow", "description": "deploy to staging first"}]

No API keys. No embeddings required. No cloud. The model stays the same — the cognitive layer becomes more structured, more inspectable, and more useful over time.

⭐ If Aura is useful to you, a GitHub star helps us get funding to continue development from Kyiv.

Why Aura?

The Core Idea: Cheap Model + Aura > Expensive Model Alone

Fine-tuning costs thousands of dollars and weeks of work. RAG requires embeddings and a vector database. Context windows are expensive per token.

Aura gives you a third path: a local cognitive runtime that accumulates structured experience between conversations — free and local.

Week 1: GPT-4o-mini + Aura                Week 1: GPT-4 alone
  → average answers                          → average answers

Week 4: GPT-4o-mini + Aura                Week 4: GPT-4 alone
  → recalls your workflow                    → still forgets everything
  → surfaces patterns you repeat             → same cost per token
  → exposes explainability + correction      → no improvement
  → boundedly adapts from experience         → no durable learning
  → $0 compute cost                          → still billing per call

The model stays the same. The cognitive layer gets stronger. That's Aura.

Performance

Measured from the Aura 1.58.0 release wheel with 1,000 records on Windows 10, an AMD Ryzen 5 5600X, and CPython 3.13.14. These are observations from one local run, not latency guarantees; hardware, stored content, query shape, cache state, enabled features, and background load all affect the result.

The first maintenance cycle in this run took 487.09 ms because it processed the newly populated store; repeated cycles had less pending work. Aura recall uses local computation and makes no required embedding or LLM API call. No cross-product speedup is claimed here because a valid comparison requires the same dataset, hardware, query workload, cache state, and quality target.

Reproduce the table with:

python benchmarks/bench_all.py 1000

The complete machine-readable output is stored in benchmarks/results.json.

_{¹ Values above are from the measured Windows build. The wheel was 2,772,715 bytes; installed size and artifacts for other Python versions and platforms vary.}

What Ships Today

Aura's full cognitive recall pipeline is active and bounded:

Record → Belief (±5%) → Concept (±4%) → Causal (±3%) → Policy (±2%)

Enable everything in one call:

brain.enable_full_cognitive_stack()   # activates all four bounded reranking phases
brain.disable_full_cognitive_stack()  # back to raw RRF baseline

Or configure individual phases:

brain.set_belief_rerank_mode("limited")   # belief-aware ranking
brain.set_concept_surface_mode("limited") # concept annotations + bounded concept reranking
brain.set_causal_rerank_mode("limited")   # causal chain boost
brain.set_policy_rerank_mode("limited")   # policy hint shaping

Higher layers also expose advisory surfaced output:

• get_surfaced_concepts() — stable concept abstractions over repeated beliefs
• get_surfaced_causal_patterns() — learned cause→effect patterns
• get_surfaced_policy_hints() — advisory recommendations (Prefer / Avoid / Warn)
• no automatic behavior influence — all output is advisory and read-only

Aura also ships operator-facing and plasticity-facing surfaces:

• explainability:
  • explain_recall()
  • explain_record()
  • provenance_chain()
  • explainability_bundle()
• governed correction:
  • targeted retract/deprecate APIs
  • persistent correction log
  • correction review queue
  • suggested corrections without auto-apply
• bounded autonomous plasticity:
  • capture_experience()
  • ingest_experience_batch()
  • maintenance-phase integration
  • anti-hallucination guards
  • plasticity risk scoring
  • purge / freeze controls
• bounded v6 cognitive guidance:
  • salience:
    • mark_record_salience()
    • get_high_salience_records()
    • get_salience_summary()
  • reflection:
    • get_reflection_summaries()
    • get_latest_reflection_digest()
    • get_reflection_digest()
  • contradiction and instability:
    • get_belief_instability_summary()
    • get_contradiction_clusters()
    • get_contradiction_review_queue()
  • honest explainability support:
    • unresolved-evidence markers in recall explanations
    • bounded answer-support phrasing for agent / UI layers

How Memory Works

Aura organizes memories into 4 levels across 2 tiers. Important memories persist, trivial ones decay naturally:

CORE TIER (slow decay — weeks to months)
  Identity  [0.99]  Who the user is. Preferences. Personality.
  Domain    [0.95]  Learned facts. Domain knowledge.

COGNITIVE TIER (fast decay — hours to days)
  Decisions [0.90]  Choices made. Action items.
  Working   [0.80]  Current tasks. Recent context.