aurora-actr 0.3.1

AURORA: Adaptive Unified Reasoning and Orchestration Architecture with MCP Integration

AURORA

Adaptive Unified Reasoning and Orchestration Architecture

A cognitive architecture framework that brings intelligent memory, reasoning, and orchestration capabilities to AI systems. Built on cognitive science principles (ACT-R, SOAR), AURORA enables AI agents to maintain persistent context, learn from experience, and coordinate complex tasks efficiently.

---

Features

MCP Server Integration

• Native Claude Code CLI integration via Model Context Protocol
• 7 powerful tools for seamless codebase search, analysis, and intelligent querying
• No API key required - MCP tools provide context to Claude Code CLI's built-in LLM
• Conversation-driven development workflow directly from your terminal

Cognitive Reasoning

• ACT-R activation-based memory (frequency, recency, semantic similarity)
• SOAR-inspired 9-phase orchestration pipeline for complex reasoning
• Intelligent query assessment with automatic escalation

Semantic Memory & Context

• Persistent memory with sentence-transformer embeddings
• Hybrid retrieval (60% activation + 40% semantic similarity)
• Multi-tier caching for sub-500ms retrieval on 10K+ chunks

Retrieval Quality Handling

• Intelligent detection of no match / weak match / good match scenarios
• Interactive prompts when retrieval quality is low (give users control)
• Automatic groundedness scoring (prevents hallucination on weak context)
• Non-interactive mode for CI/CD and automation (--non-interactive flag)

Decision Matrix:

Scenario	Chunks	Groundedness	Action
No match	0	N/A	Auto-proceed with general knowledge
Weak match	>0	<0.7 OR <3 high-quality	Prompt user (interactive) / auto-continue (non-interactive)
Good match	>0	≥0.7 AND ≥3 high-quality	Auto-proceed with retrieved context

See CLI_USAGE_GUIDE.md for detailed examples

Agent Orchestration

• Discover and coordinate multiple AI agents by capability
• Parallel and sequential task execution
• Support for local, remote, and MCP-based agents

Code Understanding

• Tree-sitter powered parsing for Python (extensible to other languages)
• Intelligent chunking with complexity analysis
• Dependency tracking and docstring extraction

Production Ready

• Cross-platform support (Windows, macOS, Linux)
• Cost tracking and budget enforcement
• Comprehensive error handling with actionable messages
• Retry logic with exponential backoff

---

Installation

From PyPI (Recommended)

# Install with all features
pip install aurora-actr[all]

# Or minimal installation (no ML dependencies)
pip install aurora-actr

# Verify installation
aur --verify

From Source

git clone https://github.com/aurora-project/aurora.git
cd aurora
pip install -e ".[all]"

Note: Package is published as aurora-actr on PyPI, but import as from aurora.core import ...

---

Quick Start

MCP Server with Claude Code CLI (Primary Workflow)

AURORA integrates with Claude Code CLI via the Model Context Protocol, enabling you to search and analyze your codebase directly from your development sessions.

1. Install and Initialize AURORA

pip install aurora-actr[all]
cd /path/to/your/project
aur init

The unified aur init command runs 3 steps:

• Step 1: Sets up Git (if needed) and creates project structure
• Step 2: Indexes your codebase for semantic search
• Step 3: Configures AI coding tools (Claude Code, Universal, etc.)

Note: No API keys required for initialization. AURORA uses environment variables for standalone CLI commands.

2. Set API Key (For Standalone CLI Only)

MCP tools don't require API keys, but standalone commands do:

# Add to ~/.bashrc or ~/.zshrc
export ANTHROPIC_API_KEY=sk-ant-...
source ~/.bashrc

3. Use with Claude Code CLI

Restart Claude Code CLI and AURORA's tools are available in your sessions:

• "Search my codebase for authentication logic" → aurora_search
• "Find all usages of the DatabaseConnection class" → aurora_search
• "Show me error handling in payment processing" → aurora_context
• "What does the UserService module do?" → aurora_context
• "Compare our API patterns with best practices" → aurora_query (auto-escalates to SOAR)

Claude Code CLI automatically uses AURORA's tools to search your indexed codebase and provide contextual answers.

Important: MCP tools do NOT require API keys. They provide context/search results that Claude Code CLI's built-in LLM processes. No additional API costs beyond your Claude subscription.

See: MCP Setup Guide for detailed configuration and troubleshooting.

---

Standalone CLI Usage

Use AURORA's CLI directly for queries, memory management, and autonomous reasoning.

Note: CLI commands like aur query require an ANTHROPIC_API_KEY environment variable (they run LLM inference directly). For API-key-free usage, use MCP integration instead.

Basic Queries

# Simple query (fast direct LLM) - requires API key
aur query "What is a Python decorator?"

# Complex query (full AURORA pipeline with context) - requires API key
aur query "How does the authentication system work?"

# Force specific mode - requires API key
aur query "Explain classes" --force-aurora --verbose

Memory Management

# Index current directory - no API key required
aur mem index

# Search indexed code - no API key required
aur mem search "authentication"

# View statistics - no API key required
aur mem stats

# Advanced search - no API key required
aur mem search "database" --limit 10 --show-content --format json

Headless Mode (Autonomous Reasoning)

# Run autonomous experiment
aur headless experiment.md

# Custom budget and iterations
aur headless experiment.md --budget 10.0 --max-iter 20

# Dry run (validation only)
aur headless experiment.md --dry-run

Safety features: Git branch enforcement, budget limits, iteration caps

Verification and Diagnostics

# Check installation health
aur --verify

# Check MCP server status
aurora-mcp status

# View help
aur --help

CLI Features:

• Automatic escalation (direct LLM vs AURORA pipeline)
• Hybrid search (activation + semantic)
• Configuration management (env vars, config files)
• Rich terminal output with progress bars
• Installation verification and diagnostics

---

Usage Examples

Example 1: Codebase Q&A with Claude Desktop

Scenario: You're working on a large codebase and need to quickly understand authentication logic.

1. Initialize AURORA in your project: aur init
2. Open Claude Desktop
3. Ask: "Find all authentication-related functions and explain the flow"
4. Claude uses AURORA to search, retrieve relevant code, and explain the implementation

Benefits: No manual file hunting, contextual understanding, instant answers

Example 2: Autonomous Code Analysis

Scenario: You want to analyze code quality across your project autonomously.

1. Create experiment file: analyze_code_quality.md
2. Run: aur headless analyze_code_quality.md
3. AURORA executes reasoning loop, analyzes code, generates report
4. Safety controls prevent unwanted changes

Benefits: Hands-free analysis, systematic coverage, safety guarantees

Example 3: Multi-Agent Orchestration

Scenario: Complex task requiring multiple AI capabilities (code generation, review, testing).

from aurora_soar import SOAROrchestrator, AgentRegistry
from aurora_reasoning import AnthropicClient

# Initialize orchestrator with agent registry
orchestrator = SOAROrchestrator(
    store=store,
    agent_registry=AgentRegistry(),
    reasoning_llm=AnthropicClient()
)

# Execute complex query - AURORA decomposes, routes to agents, synthesizes
result = orchestrator.execute(
    query="Implement JWT authentication with tests and security review"
)

print(f"Agents used: {result['metadata']['agents_used']}")
print(f"Confidence: {result['confidence']:.2f}")

Benefits: Coordinated multi-agent execution, automatic routing, cost tracking

---

Python API

Quick examples for programmatic use:

Parse and Store Code

from aurora_core.store import SQLiteStore
from aurora_context_code import PythonParser

store = SQLiteStore("aurora.db")
parser = PythonParser()
chunks = parser.parse_file("example.py")

for chunk in chunks:
    store.save_chunk(chunk)

Context Retrieval with Scoring

from aurora_core.context import CodeContextProvider

provider = CodeContextProvider(store, parser_registry)
results = provider.retrieve("authentication logic", max_results=5)

for chunk in results:
    print(f"{chunk.metadata['name']} (score: {chunk.metadata['_score']:.2f})")

SOAR Orchestrator

from aurora_soar import SOAROrchestrator

orchestrator = SOAROrchestrator(store, agent_registry, reasoning_llm)
result = orchestrator.execute(query="Analyze security vulnerabilities")

Full API documentation: API Reference

---

Architecture

AURORA is organized as a Python monorepo with modular packages:

Core Packages:

• aurora-core - Storage, chunks, configuration, context providers, cost tracking
• aurora-context-code - Code parsing (Python via tree-sitter, extensible)
• aurora-soar - Agent registry, 9-phase orchestration pipeline
• aurora-reasoning - LLM integration (Anthropic, OpenAI, Ollama), reasoning logic
• aurora-testing - Testing utilities, fixtures, mocks, benchmarks

Key Architecture Patterns:

• 9-Phase SOAR Pipeline: Assess → Retrieve → Decompose → Verify → Route → Collect → Synthesize → Record → Respond
• ACT-R Memory Activation: Frequency, recency, semantic similarity, context boost
• Hybrid Retrieval: 60% activation scoring + 40% semantic similarity
• Multi-Tier Caching: Hot cache (LRU) + persistent cache + activation scores (10min TTL)
• Cost Optimization: Keyword-based assessment bypasses LLM for 60-70% of simple queries

Performance:

• Simple query latency: <2s (achieved: 0.002s)
• Complex query latency: <10s
• Memory usage: <100MB for 10K chunks (achieved: 39MB)
• Retrieval: <500ms for 10K chunks

Detailed architecture: SOAR Architecture, Verification Checkpoints

---

Documentation

Getting Started

• MCP Setup Guide - Claude Desktop integration
• Quick Start - Get started in 5 minutes
• CLI Usage Guide - Comprehensive command reference
• Troubleshooting Guide - Common issues and solutions

Architecture & Design

• SOAR Architecture - 9-phase pipeline details
• Verification Checkpoints - Scoring and thresholds
• Agent Integration Guide - Agent formats and execution
• Cost Tracking Guide - Budget management
• Prompt Engineering Guide - Template design

Development

• Pre-Push Validation - Local CI/CD checks before pushing
• API Contracts - API reference
• Migration Guide - Upgrade guide
• Code Review Report - Quality analysis
• Security Audit - Security review

Project History

• Release Notes - Version history
• Phase Archives - Development phases

---

Development

Setup Development Environment

# Clone and install with dev dependencies
git clone https://github.com/aurora-project/aurora.git
cd aurora
make install-dev

# Run quality checks
make quality-check

Common Commands

make test              # Run all tests (1,766+ tests, 97% pass rate)
make test-unit         # Unit tests only
make lint              # Ruff linter
make format            # Format code
make type-check        # MyPy type checker (100% type safety)
make benchmark         # Performance benchmarks
make coverage          # HTML coverage report (81%+ coverage)

Code Quality Standards

• Linting: Ruff with comprehensive rules
• Type Checking: MyPy strict mode (zero type errors)
• Test Coverage: 81%+ coverage maintained
• Security: Bandit security scanning
• Performance: Benchmarks for critical operations

Contributing

Contributions welcome! Please ensure:

1. All tests pass (make test)
2. Code is formatted (make format)
3. Type checking passes (make type-check)
4. New features include tests
5. Documentation updated

---

License

MIT License - see LICENSE for details.

---

Contact

For questions, issues, or discussions:

• GitHub Issues: aurora-project/aurora/issues
• Discussions: aurora-project/aurora/discussions

---

AURORA - Intelligent AI systems with persistent memory and cognitive reasoning