AuraSDK

Cognitive Memory Engine for AI Agents

Learns from experience · <1ms recall · No LLM calls · No cloud · ~3 MB

     

---

LLMs forget everything. Every conversation starts from zero. Existing solutions bolt on vector databases and LLM calls for basic recall, adding latency, cloud dependency, and cost to every operation.

Aura gives your AI agent an adaptive cognitive layer: memory that decays, consolidates, learns from feedback, and evolves over time. Every record carries a semantic type (fact, decision, trend, preference, contradiction, serendipity) that shapes how it decays, promotes, and surfaces in recall. Like a brain, not a database. One pip install, works fully offline.

pip install aura-memory

from aura import Aura, Level

brain = Aura("./agent_memory")

brain.store("User prefers dark mode", level=Level.Identity, tags=["ui"],
            semantic_type="preference")
brain.store("Deploy to staging first", level=Level.Decisions, tags=["workflow"],
            semantic_type="decision")

context = brain.recall("user preferences")  # <1ms — inject into any LLM prompt

Your agent now remembers. No API keys. No embeddings. No config.

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

---

Why Aura?

	Aura	Mem0	Zep	Cognee	Letta/MemGPT
Architecture	Cognitive engine	Vector + LLM	Vector + LLM	Graph + LLM	LLM orchestration
LLM required	No	Yes	Yes	Yes	Yes
Recall latency	<1ms	~200ms+	~200ms	LLM-bound	LLM-bound
Works offline	Fully	Partial	No	No	With local LLM
Cost per operation	$0	API billing	Credit-based	LLM + DB cost	LLM cost
Binary size	~3 MB	~50 MB+	Cloud service	Heavy (Neo4j+)	Python pkg
Semantic memory types	Built-in (6 types)	No	No	No	No
Memory decay & promotion	Built-in	Via LLM	Via LLM	No	Via LLM
Trust & provenance	Built-in	No	No	No	No
Encryption at rest	ChaCha20 + Argon2	No	No	No	No
Language	Rust	Python	Proprietary	Python	Python

Performance

Benchmarked on 1,000 records (Windows 10 / Ryzen 7):

Operation	Latency	vs Mem0
Store	0.09 ms	~same
Recall (structured)	0.74 ms	~270× faster
Recall (cached)	0.48 µs	~400,000× faster
Maintenance cycle	1.1 ms	No equivalent

Mem0 recall requires an embedding API call (~200ms+) + vector search. Aura recall is pure local computation.

---

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.

SEMANTIC TYPES (modulate decay & promotion)
  fact          Default knowledge record.
  decision      More persistent than a standard fact. Promotes earlier.
  preference    Long-lived user or agent preference.
  contradiction Preserved longer for conflict analysis.
  trend         Time-sensitive pattern tracked over repeated activation.
  serendipity   Cross-domain discovery record.

One call runs the lifecycle — decay, promotion, consolidation, and archival:

report = brain.run_maintenance()  # background memory maintenance

---

Key Features

Core Memory Engine

• Fast Local Recall - Multi-signal ranking with optional embedding support
• Two-Tier Memory — Cognitive (ephemeral) + Core (permanent) with decay, promotion, and archival
• Semantic Memory Types — 6 roles (fact, decision, trend, preference, contradiction, serendipity) that influence memory behavior and insighting
• Phase-Based Insights — Detects conflicts, trends, preference patterns, and cross-domain links
• Background Maintenance — Continuous memory hygiene: decay, reflect, insights, consolidation, archival
• Namespace Isolation — namespace="sandbox" keeps test data invisible to production recall
• Pluggable Embeddings - Optional embedding support: bring your own embedding function

Trust & Safety

• Trust & Provenance — Source authority scoring: user input outranks web scrapes, automatically
• Source Type Tracking — Every memory carries provenance: recorded, retrieved, inferred, generated
• Auto-Protect Guards — Detects phone numbers, emails, wallets, API keys automatically
• Encryption — ChaCha20-Poly1305 with Argon2id key derivation

Adaptive Memory

• Feedback Learning — brain.feedback(id, useful=True) boosts useful memories, weakens noise
• Semantic Versioning — brain.supersede(old_id, new_content) with full version chains
• Snapshots & Rollback — brain.snapshot("v1") / brain.rollback("v1") / brain.diff("v1","v2")
• Agent-to-Agent Sharing — export_context() / import_context() with trust metadata

Enterprise & Integrations

• Multimodal Stubs — store_image() / store_audio_transcript() with media provenance
• Prometheus Metrics — /metrics endpoint with 10+ business-level counters and histograms
• OpenTelemetry — telemetry feature flag with OTLP export and 17 instrumented spans
• MCP Server — Claude Desktop integration out of the box
• WASM-Ready — StorageBackend trait abstraction (FsBackend + MemoryBackend)
• Pure Rust Core — No Python dependencies, no external services

---

Quick Start

Trust & Provenance

from aura import Aura, TrustConfig

brain = Aura("./data")

tc = TrustConfig()
tc.source_trust = {"user": 1.0, "api": 0.8, "web_scrape": 0.5}
brain.set_trust_config(tc)

# User facts always rank higher than scraped data in recall
brain.store("User is vegan", channel="user")
brain.store("User might like steak restaurants", channel="web_scrape")

results = brain.recall_structured("food preferences", top_k=5)
# -> "User is vegan" scores higher, always

Pluggable Embeddings (Optional)

from aura import Aura

brain = Aura("./data")

# Plug in any embedding function: OpenAI, Ollama, sentence-transformers, etc.
from sentence_transformers import SentenceTransformer
model = SentenceTransformer("all-MiniLM-L6-v2")
brain.set_embedding_fn(lambda text: model.encode(text).tolist())

# Now "login problems" matches "Authentication failed" via semantic similarity
brain.store("Authentication failed for user admin")
results = brain.recall_structured("login problems", top_k=5)

Without embeddings, Aura continues to use its local recall pipeline - still fast, still effective.

Encryption

brain = Aura("./secret_data", password="my-secure-password")
brain.store("Top secret information")
assert brain.is_encrypted()  # ChaCha20-Poly1305 + Argon2id

Semantic Memory Types

brain = Aura("./data")

# Decisions are treated as higher-value memory
brain.store("Use PostgreSQL over MySQL", semantic_type="decision", tags=["db"])

# Preferences persist longer than generic working notes
brain.store("User prefers dark mode", semantic_type="preference", tags=["ui"])

# Contradictions are preserved for conflict analysis
brain.store("User said vegan but ordered steak", semantic_type="contradiction")

# Search by semantic type
decisions = brain.search(semantic_type="decision")

# Cross-domain insights surface higher-level patterns
insights = brain.insights(phase=2)
# Example:
# [{'insight_type': 'preference_pattern', 'description': 'Preference cluster around ui', ...}]

Namespace Isolation

brain = Aura("./data")

brain.store("Real preference: dark mode", namespace="default")
brain.store("Test: user likes light mode", namespace="sandbox")

# Recall only sees "default" namespace — sandbox is invisible
results = brain.recall_structured("user preference", top_k=5)

---

Cookbook: Personal Assistant That Remembers

The killer use case: an agent that remembers your preferences after a week offline, with zero API calls.

See examples/personal_assistant.py for the full runnable script.

from aura import Aura, Level

brain = Aura("./assistant_memory")

# Day 1: User tells the agent about themselves
brain.store("User is vegan", level=Level.Identity, tags=["diet"])
brain.store("User loves jazz music", level=Level.Identity, tags=["music"])
brain.store("User works 10am-6pm", level=Level.Identity, tags=["schedule"])
brain.store("Discuss quarterly report tomorrow", level=Level.Working, tags=["task"])

# Simulate a week passing — run maintenance cycles
for _ in range(7):
    brain.run_maintenance()  # decay + reflect + consolidate + archive

# Day 8: What does the agent remember?
context = brain.recall("user preferences and personality")
# -> Still remembers: vegan, jazz, schedule (Identity, strength ~0.93)
# -> "quarterly report" decayed heavily (Working, strength ~0.21)

Identity persists. Tasks fade. Important patterns get promoted. Like a real brain.

---

MCP Server (Claude Desktop)

Give Claude persistent memory across conversations:

pip install aura-memory

Add to Claude Desktop config (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "aura": {
      "command": "python",
      "args": ["-m", "aura", "mcp", "C:\\Users\\YOUR_NAME\\aura_brain"]
    }
  }
}

Provides 8 tools: recall, recall_structured, store, store_code, store_decision, search, insights (with phase filtering), consolidate. Store and search support semantic_type filtering.

---

Dashboard UI

Aura includes a standalone web dashboard for visual memory management. Download from GitHub Releases.

./aura-dashboard ./my_brain --port 8000

Features: Analytics · Memory Explorer with filtering · Recall Console with live scoring · Batch ingest

Platform	Binary
Windows x64	aura-dashboard-windows-x64.exe
Linux x64	aura-dashboard-linux-x64
macOS ARM	aura-dashboard-macos-arm64
macOS x64	aura-dashboard-macos-x64

---

Integrations & Examples

Try now: — zero install, runs in browser

Integration	Description	Link
Ollama	Fully local AI assistant, no API key needed	ollama_agent.py
LangChain	Drop-in Memory class + prompt injection	langchain_agent.py
LlamaIndex	Chat engine with persistent memory recall	llamaindex_agent.py
OpenAI Agents	Dynamic instructions with persistent memory	openai_agents.py
Claude SDK	System prompt injection + tool use patterns	claude_sdk_agent.py
CrewAI	Tool-based recall/store for crew agents	crewai_agent.py
AutoGen	Memory protocol implementation	autogen_agent.py
FastAPI	Per-user memory middleware with namespace isolation	fastapi_middleware.py

FFI (C/Go/C#): aura.h · go/main.go · csharp/Program.cs

More examples: basic_usage.py · encryption.py · agent_memory.py · edge_device.py · maintenance_daemon.py · research_bot.py

---

Architecture

Aura uses a Rust core with Python bindings and a local-first memory runtime.

Publicly documented concepts are:

• Two-tier memory: cognitive + core
• Semantic roles for records
• Local multi-signal recall
• Trust, provenance, and namespace isolation
• Maintenance, insights, consolidation, and versioning

The public repository documents the user-facing behavior and integration surface. Detailed internal architecture, tuning, and research notes are intentionally not published.

---

Resources

• Demo Video (30s) — Quick overview
• Examples — Ready-to-run scripts
• Landing Page — Project overview

---

Contributing

Contributions welcome! See CONTRIBUTING.md for setup instructions and guidelines, or check the open issues.

⭐ If Aura saves you time, a GitHub star helps others discover it and helps us continue development.

---

License & Intellectual Property

• Code License: MIT — see LICENSE.
• Patent Notice: Core architectural concepts are Patent Pending (US Provisional Application No. 63/969,703). See PATENT for details. The SDK source code is available under MIT. Separate commercial licensing is available for organizations that want contractual rights around patented architecture, OEM embedding, enterprise deployment, or dedicated support.
• Commercial Licensing: If you want to embed Aura's architecture into a commercial product, see COMMERCIAL.md.

---

Built in Kyiv, Ukraine 🇺🇦 — including during power outages.
_{Solo developer project. If you find this useful, your star means more than you think.}