Neuro-Adaptive Reasoning Engine (NARE)

The core reasoning engine that powers adaptive AI agents

⚠️Note on Versioning > This repository contains the stable base architecture of the NARE Core. It is intentionally decoupled from the production-ready CLI to provide the community with a clean, lightweight engine for integration. For the full feature set and latest reasoning modules, stay tuned for the official NARE CLI release.⚠️

NARE is a research-grade reasoning engine that combines neural episodic memory, verified synthesis, and meta-learning to create AI agents that improve from experience.

This is the core library. For the production CLI tool, see NARE CLI.

---

What is NARE?

NARE is a reasoning engine — not a chatbot or coding assistant. It's the underlying system that enables AI agents to:

1. Remember — Store successful solutions with semantic embeddings
2. Retrieve — Find similar past solutions in <100ms
3. Synthesize — Generate new solutions with formal verification
4. Learn — Discover patterns and compile reusable skills
5. Adapt — Improve performance over time

Think of it as the "brain" that powers adaptive AI agents.

---

Architecture

┌─────────────────────────────────────────────────────┐
│                   NARE Core Engine                  │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Memory System              Reasoning Engine       │
│  ├─ Episodic Memory         ├─ LLM Interface       │
│  ├─ Neural Embeddings       ├─ Critic              │
│  ├─ Graph Memory            ├─ Oracle Validation   │
│  └─ FAISS Indexing          └─ Meta-Abduction      │
│                                                     │
│  Execution Layer            Tools & Utilities      │
│  ├─ Sandbox Isolation       ├─ Domain Detection    │
│  ├─ Verified Synthesis      ├─ Path Validation     │
│  └─ Code Execution          └─ Query Fingerprinting│
└─────────────────────────────────────────────────────┘

---

Key Features

1. Episodic Memory

NARE stores every successful solution as an episode with:

• Full solution trace
• Semantic embedding (FAISS-indexed)
• Confidence score
• Execution metadata

Retrieval is fast: Sub-100ms similarity search over thousands of episodes.

2. Verified Synthesis

When generating new solutions, NARE:

1. Generates candidate solution
2. Validates with oracle (test execution)
3. If failed → auto-repair with error feedback
4. Repeats until verified or max attempts

No untested code. Every solution is validated before storage.

3. Meta-Learning

NARE discovers patterns across episodes:

• Clusters similar queries (DBSCAN)
• Identifies repeated patterns
• Compiles patterns into instant skills
• Prunes low-value memories

The system gets smarter over time.

4. Modular Design

NARE is designed as a library, not an application:

• Use individual components (memory, synthesis, oracle)
• Build custom agents on top
• Integrate into existing systems

---

Installation

pip install nare-core

Or install from source:

git clone https://github.com/Nare-Labs/Neuro-Adaptive-Reasoning-Engine.git
cd Neuro-Adaptive-Reasoning-Engine
pip install -e .

---

Quick Start

Basic Usage

from nare.core.agent import Agent
from nare.core.config import Config

# Initialize agent
config = Config(memory_dir="~/.nare/memory")
agent = Agent(config=config)

# Solve a task
result = agent.solve(
    query="Implement quicksort in Python",
    oracle=lambda code: test_quicksort(code)
)

print(result["solution"])
print(f"Verified: {result['verified']}")
print(f"Attempts: {result['attempts']}")

With Memory Retrieval

from nare.memory.memory import Memory

# Load memory
memory = Memory(persist_dir="~/.nare/memory")
memory.load()

# Retrieve similar episodes
episodes = memory.retrieve_episodes(
    query="sort algorithm",
    k=5
)

for ep in episodes:
    print(f"Query: {ep['query']}")
    print(f"Similarity: {ep['similarity']:.2f}")
    print(f"Solution: {ep['solution'][:100]}...")

Custom Oracle

def my_oracle(code: str) -> bool:
    """Validate generated code."""
    try:
        # Run tests
        exec(code)
        result = quicksort([3, 1, 4, 1, 5])
        return result == [1, 1, 3, 4, 5]
    except Exception:
        return False

result = agent.solve(
    query="Implement quicksort",
    oracle=my_oracle
)

---

Core Components

Memory System (nare/memory/)

• memory.py — Episodic storage with FAISS indexing
• neural_memory.py — Neural embedding generation
• graph_memory.py — Graph-based memory structure
• metrics.py — Performance tracking

Reasoning Engine (nare/reasoning/)

• llm.py — LLM interface (Anthropic Claude)
• critic.py — Solution quality scoring
• oracle.py — Formal verification
• meta_abduction.py — Pattern discovery

Execution Layer (nare/execution/)

• sandbox.py — Isolated code execution
• sandbox_subprocess.py — Subprocess-based isolation

Tools (nare/tools/)

• domain_detector.py — Task domain classification
• path_validator.py — File path validation
• repo_manager.py — Repository management
• query_fingerprint.py — Query deduplication
• rl_retriever.py — RL-based retrieval
• arc_adapter.py — ARC benchmark adapter

---

Configuration

from nare.core.config import Config

config = Config(
    # Memory settings
    memory_dir="~/.nare/memory",
    max_episodes=5000,
    embedding_dim=1024,
    
    # Synthesis settings
    max_synthesis_attempts=8,
    temperature=0.2,
    
    # Retrieval settings
    similarity_threshold=0.85,
    retrieval_k=5,
    
    # Learning settings
    enable_meta_learning=True,
    pattern_min_occurrences=3,
)

---

Research Background

NARE implements ideas from:

• Episodic Memory — Store and retrieve past experiences
• Verified Synthesis — Formal verification of generated code
• Meta-Learning — Learn from patterns across tasks
• Neural Retrieval — Semantic similarity search

Key Papers

• Neural Module Networks
• Episodic Memory in Lifelong Learning
• Program Synthesis with Learned Code Idioms

---

Benchmarks

NARE has been evaluated on:

• ARC Challenge — Abstract reasoning tasks
• SWE-bench — Real-world software engineering
• GSM8K — Math word problems

See benchmarks/ for evaluation scripts and results.

---

Development

Running Tests

pytest tests/

Project Structure

nare/
├── core/              # Core agent logic
│   ├── agent.py       # Main agent
│   ├── synthesis.py   # Verified synthesis
│   ├── config.py      # Configuration
│   └── solve_context.py
├── memory/            # Memory system
│   ├── memory.py      # Episodic storage
│   ├── neural_memory.py
│   ├── graph_memory.py
│   └── metrics.py
├── reasoning/         # Reasoning engine
│   ├── llm.py         # LLM interface
│   ├── critic.py      # Quality scoring
│   ├── oracle.py      # Verification
│   └── meta_abduction.py
├── execution/         # Code execution
│   ├── sandbox.py
│   └── sandbox_subprocess.py
└── tools/             # Utilities
    ├── domain_detector.py
    ├── path_validator.py
    └── ...

---

Use Cases

1. Research

Use NARE as a foundation for research in:

• Lifelong learning
• Program synthesis
• Meta-learning
• Neural-symbolic AI

2. Custom Agents

Build specialized agents on top of NARE:

• Code generation agents
• Data analysis agents
• Automated testing agents

3. Integration

Integrate NARE into existing systems:

• Add memory to your AI pipeline
• Use verified synthesis for code generation
• Leverage meta-learning for pattern discovery

---

Limitations

See LIMITATIONS.md for detailed discussion of:

• Memory capacity constraints
• Synthesis verification scope
• Domain-specific challenges
• Performance considerations

---

Related Projects

• NARE CLI — Production-ready CLI tool built on NARE
• NARE VSCode — VSCode extension (coming soon)
• NARE API — REST API wrapper (coming soon)

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Areas of interest:

• Memory system optimizations
• New oracle implementations
• Meta-learning algorithms
• Benchmark evaluations

---

Citation

If you use NARE in your research, please cite:

@software{nare2026,
  title={NARE: Neuro-Adaptive Reasoning Engine},
  author={NARE Labs},
  year={2026},
  url={https://github.com/Nare-Labs/Neuro-Adaptive-Reasoning-Engine}
}

---

License

MIT License - see LICENSE

---

Contact

• GitHub: Nare-Labs
• Issues: Report bugs
• Discussions: Join the community

---

NARE — The reasoning engine for adaptive AI agents.

⭐ Star us on GitHub if you're interested in AI that learns from experience.