teolex2020/AuraSDK
ms recall, offline, encrypted.
Ask AI about teolex2020/AuraSDK
Powered by Claude Β· Grounded in docs
I know everything about teolex2020/AuraSDK. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 β
/metricsendpoint with 10+ business-level counters and histograms - OpenTelemetry β
telemetryfeature flag with OTLP export and 17 instrumented spans - MCP Server β Claude Desktop integration out of the box
- WASM-Ready β
StorageBackendtrait 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.
