Using open source software without proper attribution or in violation of license terms is not only ethically problematic but may also constitute a legal violation
If you're using code or tools from this repository or GitHub, please ensure you maintain all attribution notices and comply with all applicable licenses.
The license above is a modified MIT LICENSE for the purpose of this project π
π For full legal terms and enforcement policy, read the Neuron Legal Notice & Enforcement Terms.
Warning
This repository is no longer actively maintained.
The author has since begun using it for a specific use case and is no longer developing it as a general project. Issues and pull requests may not receive a response.
After about 20+ reachouts from the developer community, Iβm excited to officially drop Series 1 of our OpenClaw x Neuron notebook system.
Building agents is easy. Building reliable agents that work in production? Thatβs the real challenge.
Series 1 is laser-focused on Reliability and Defensive Strategies. Weβre using Neuronβs cognitive architecture to tackle the "dark arts" of OpenClaw agent engineering:
- Persistent Agent Memory (Episodic & Semantic)
- Hallucination Guardrails via Circuit Logic
- Competitive Debate Architectures (The "Wild Card" vs. "The Quant")
- Prompt Injection Defense & Synaptic Bus Security
- Skill Health Monitoring for Malicious Code Detection
- Contradictory Instruction Resolution
These are local-first, GPU agnostic patterns that you can drop into your OpenClaw architectures today.
This is only the beginning. While Series 1 hardens your foundation with Neuronβs defensive layers, the next 10 notebooks will dive deep into:
- Agentic Intelligence
- Advanced Reasoning
- Autonomous Multi-lane Sync
Agentic systems are only as smart as they are stable. Start with the shield, then build the brain.
π Explore Series 1 at: https://neuronsystems.org/openclaw-neuron
Neuron is a composable AI framework that thinks in circuits, not chains.
Traditional AI orchestration tools collapse under real-world complexityβcontradictions, sarcasm, conflicting goals, or mixed data formats. Neuron addresses these breakdown zones through modular reasoning circuits inspired by how the brain actually processes information.
βββββββββββββββββββββββββββββββββββββββββββ
β NEURON ARCHITECTURE β
βββββββββββββββββββββββββββββββββββββββββββ
β
ββββββββββββββββ¬ββββββββββΌββββββββββ¬βββββββββββββββ
β β β β β
βΌ βΌ βΌ βΌ βΌ
ββββββββββββ βββββββββββ βββββββββ βββββββββββ βββββββββββ
βPerceptionβ β Memory β βSynapticβ βReasoningβ βExpressionβ
β Modules β β System β β Bus β β Modules β β Modules β
β β β β β β β β β β
ββ’ LanguageβββΊββ’ EpisodicβββΊβ Coord βββΊββ’ Logic βββΊββ’ Responseβ
ββ’ Vision β ββ’ Semanticβ β Layer β ββ’ Planningβ ββ’ Adapt β
ββ’ Audio β ββ’ Working β β β ββ’ Temporalβ ββ’ Format β
ββ’ Multi.. β ββ’ Context β β β ββ’ Causal β ββ’ Tone β
ββββββββββββ βββββββββββ βββββββββ βββββββββββ βββββββββββ
β β
βΌ βΌ
ββββββββββββββββββββ ββββββββββββββββββββ
β Self-Monitoring β β Adaptability β
β β β β
ββ’ Error Detection β ββ’ Dynamic Routing β
ββ’ Uncertainty β ββ’ Context Shift β
ββ’ Explanation β ββ’ Resource Alloc β
ββββββββββββββββββββ ββββββββββββββββββββ
Cognitive Multi-Agent Architecture for Complex AI Systems
Neuron is a research framework exploring cognitive architectures through modular multi-agent coordination. Built on neuroscience-inspired principles, it provides sophisticated agent coordination patterns and memory systems for developing resilient AI applications.
π¬ Current Status: Advanced Research Platform - Production-ready architecture with agent behavior modeling. Suitable for research, prototyping, and foundational development of cognitive AI systems.
Neuron excels in scenarios traditional AI struggles with:
- π Resilient Processing: Handles ambiguous inputs, contradictory information, and incomplete data without system failure
- π§ Persistent Memory: Maintains context across extended interactions for longitudinal reasoning
- β‘ Selective Activation: Dynamically combines only needed capabilities rather than running every component
- π Parallel Coordination: Processes multiple tasks simultaneously while maintaining consistency
- ποΈ Complete Observability: Every decision is traceable with full reasoning paths and evidence trails
Currently live and serving 325+ content creators during NFL primetime, this implementation demonstrates Neuron's capacity for high-velocity, stateful agent coordination.
- Codebase: See the
FFSappandFS_Neuronand other private directories. - Scale: Orchestrates 1,500+ concurrent agents with 99.9% uptime.
- Performance: Achieves 187ms end-to-end latency (Analysis β Agent Consensus β Voice Generation).
- Voice Integration: Routes high-leverage emotional moments to ElevenLabs and standard commentary to GCP.
- Architecture: Utilizes a stable of 6 distinct agent personalities (e.g., "The Wild Card", "The Quant") that debate live game events in real-time.
| Use Case | Traditional AI | Neuron Agent Approach |
|---|---|---|
| Contradictory Customer Requests | Fails or picks one instruction | Agent consensus detects contradiction, requests clarification |
| Multi-Session Medical History | Loses context between visits | Memory agents maintain episodic history with temporal reasoning |
| Emergency Response Triage | Static rule-based priority | Coordination agents provide dynamic multi-modal assessment |
| Regulatory Compliance | Rigid rule checking | Reasoning agents perform contextual interpretation with conflict resolution |
git clone https://github.com/ShaliniAnandaPhD/Neuron.git
cd Neuron
pip install -e . # the framework (numpy, psutil, PyYAML)
pip install -e ".[dev]" # plus pytest and lintersA circuit is a set of agents joined by connections. Input goes to the INPUT
agents; each agent's reply travels along its connections to the next agents;
replies from OUTPUT agents come back from get_output(). This example is
examples/quickstart.py and runs as part of the
test suite:
import asyncio
from neuron import BaseAgent, CircuitDefinition, initialize
class Intake(BaseAgent):
"""Tags a support message with positive and negative signals."""
def _initialize(self):
pass
async def process_message(self, message):
text = message.content["message"].lower()
signals = {
"positive": any(word in text for word in ("love", "great", "thanks")),
"negative": any(word in text for word in ("broken", "refund", "angry")),
}
await self.send_message(message.sender, {**message.content, "signals": signals})
class ContradictionCheck(BaseAgent):
"""Flags messages that are positive and negative at the same time."""
def _initialize(self):
pass
async def process_message(self, message):
signals = message.content["signals"]
mixed = signals["positive"] and signals["negative"]
await self.send_message(
message.sender, {**message.content, "contradiction": mixed}
)
class Responder(BaseAgent):
"""Writes the reply."""
def _initialize(self):
pass
async def process_message(self, message):
if message.content["contradiction"]:
reply = "Sounds like you like it but it isn't working. Repair or refund?"
else:
reply = "Thanks, we're on it."
await self.send_message(message.sender, {"reply": reply})
async def main():
core = initialize()
core.start() # components run as tasks on this event loop
for agent_type in (Intake, ContradictionCheck, Responder):
core.agent_manager.register_agent_type(agent_type)
circuit = CircuitDefinition.create(
name="CustomerSupportCircuit",
description="Detects mixed signals and asks a clarifying question",
agents={
"intake": {"type": "Intake", "role": "INPUT"},
"checker": {"type": "ContradictionCheck", "role": "PROCESSOR"},
"responder": {"type": "Responder", "role": "OUTPUT"},
},
connections=[
{"source": "intake", "target": "checker", "connection_type": "direct"},
{"source": "checker", "target": "responder", "connection_type": "direct"},
],
)
circuit_id = await core.circuit_designer.create_and_deploy(circuit)
message = "I love this product but it's completely broken and I want a refund"
await core.circuit_designer.send_input(circuit_id, {"message": message})
output = await core.circuit_designer.get_output(circuit_id, timeout=5)
print(f"{output['agent']}: {output['content']['reply']}")
await core.circuit_designer.terminate_circuit(circuit_id)
await core.shutdown_async()
if __name__ == "__main__":
asyncio.run(main())python examples/quickstart.py
# responder: Sounds like you like it but it isn't working. Repair or refund?The framework is asynchronous: call initialize() and core.start() from
inside a coroutine, as above, and await the circuit methods. Connections can
be direct, conditional or filtered (a Python expression over message
in the connection's metadata), or transformed (an expression that rewrites
the content). Expressions are evaluated with eval, so only deploy circuit
definitions you trust.
python -m pytest tests agents src/neuronsCI runs these on Python 3.10 and 3.13, plus each sub-project's tests and a repository-wide lint, on every push (workflow).
| Folder | What it is | Run it | In CI |
|---|---|---|---|
src/neuron |
The framework: agents, SynapticBus, circuits, memory, monitoring, CLI | pip install -e ., then Quick Start |
β |
examples |
Runnable examples (the Quick Start circuit) | python examples/quickstart.py |
β |
agents |
Industry use case agents (healthcare, financial, insurance, legal, manufacturing, retail) | python agents/neuron_agent.py --list |
β |
Microservices |
Ambiguity resolution, healthcare record integration, multilingual documentation, each a Neuron circuit | Microservices README | β |
hallucination_detection |
Uncertainty, self-consistency and fact verification checks | python hallucination_detection/examples.py |
β |
high_velocity_AI_pipeline |
Real-time pipeline with hot-swapping between OpenAI and Groq agents | its README | β |
neuron-framework-t1 |
Vision model hot-swap test (OpenAI primary, Claude fallback) | its quick start | β |
src/neurons |
Small memory and decision agents | python -m pytest src/neurons |
β |
neuron-bench |
Benchmark datasets and analysis scripts | its README | |
chaos_engineering |
Chaos scenarios for agent pools (failures, partitions, exhaustion) | its README | |
llam3-neuron-framework |
Multi-agent REST service on a self-hosted LLaMA 3 | docker compose up (README) |
|
FFSapp, FS_Neuron |
Fantasy Football Neuron app and its NFL data pipeline | FFSapp README | |
safety |
Safety monitor for agent health | python safety/safety_monitor.py |
|
Tutorials |
Colab notebooks (self-contained) | Open in Colab | |
scripts, configs, data, compliance_rules |
Fine-tuning pipeline and IP protection toolkit | Fine-tuning workflow, IP toolkit docs | |
Integrations/Oxen.ai |
Dataset versioning walkthrough with screenshots | Read | |
sandbox |
Sandbox notes | Read |
Every agent subclasses BaseAgent and implements process_message; it
replies with send_message. The framework ships four built-in types:
ReflexAgent (rule-based, fast), DeliberativeAgent (multi-step
reasoning), LearningAgent (adapts from feedback) and CoordinatorAgent
(runs workflows across other agents). Register your own types and use them
by name in circuits, as in the Quick Start.
from neuron import ReflexAgent, create_agent
# inside a coroutine, after initialize() and core.start()
agent_id = create_agent(ReflexAgent, name="Intake", description="Classifies requests")
core.agent_manager.register_agent_type(MyAgent) # a BaseAgent subclassFive memory systems, inspired by human memory: WORKING, EPISODIC,
SEMANTIC, PROCEDURAL and EMOTIONAL.
from neuron import MemoryType
memory = core.memory_manager
await memory.store(
{"event": "customer_complaint", "resolution": "replacement_offered"},
MemoryType.EPISODIC,
importance=0.8,
metadata={"customer_id": "12345"},
)
history = await memory.query(
{"metadata.customer_id": "12345"}, memory_type=MemoryType.EPISODIC
)Agents exchange Messages over the SynapticBus. Inside a circuit, an agent
replies to whoever sent it a message and the circuit forwards the reply
along its connections. Outside a circuit, address agents directly:
from neuron import Message
await core.synaptic_bus.send(Message.create(
sender="intake_agent",
recipients=[reasoning_agent_id],
content={"type": "customer_issue", "sentiment": "mixed"},
metadata={"priority": "high"},
))A circuit wires agents together. Each connection has a type:
| Type | Behaviour |
|---|---|
direct, weighted |
Forward every message |
conditional, filtered |
Forward when a Python expression over message is true (metadata.condition_code / metadata.filter_condition) |
transformed |
Rewrite the content first (metadata.transform_code) |
{"source": "intake", "target": "escalation", "connection_type": "conditional",
"metadata": {"condition_code": "message.content['urgency'] == 'high'"}}Built-in templates (sequential_pipeline, star_network) are listed by
neuron circuit list. Expressions are evaluated with eval; only deploy
circuit definitions you trust.
neuron --help
neuron agent list # available agent types
neuron circuit list # circuit templates
neuron start # run the framework until Ctrl+CEach command runs in its own process, so state (such as a deployed circuit) does not carry over from one command to the next; use the Python API for anything stateful.
Working implementations in this repository:
- Healthcare, finance, insurance, legal, manufacturing, retail: one
configurable agent per industry use case, with the compliance standards
that apply (
agents/). - Ambiguity resolution: detects politeness that masks urgency in
support requests and resolves intent and urgency
(
Microservices/ambiguity). - Healthcare record integration: merges multilingual patient records
from several providers, standardizes units and terminology, and flags
care gaps (
Microservices/healthcare). - Medical device documentation: adapts technical documents across
languages while preserving safety-critical content
(
Microservices/multilingual). - Hallucination detection: uncertainty quantification, self-consistency
and fact verification (
hallucination_detection/).
- Health monitoring:
core.neuro_monitor.get_health_status()reports system, agent, communication and circuit health;get_metrics(pattern)returns collected metrics. - Tracing:
neuron.observabilityrecords and visualizes message traces through a circuit. - Fallback and simulation:
neuron.agents.fallback_handlerandneuron.agents.simulation_planner. - Model providers: Hugging Face models as agents
(
pip install -e ".[models]", seeneuron.model_providers). - Resilience testing:
chaos_engineering/injects failures into agent pools;neuron-bench/analyses benchmark results across architectures.
- Memory: Persistent multi-layered agent memory vs. token-level context
- Reasoning: Parallel multi-agent coordination vs. sequential chains
- Observability: Full agent decision traces vs. execution logs only
- Adaptability: Dynamic agent reconfiguration vs. manual flow updates
- State Management: Rich agent memory systems vs. stateless calls
- Error Handling: Graceful agent degradation vs. hard failures
- Coordination: Multi-agent orchestration vs. single-shot responses
- Explainability: Complete agent reasoning traces vs. black box outputs
- Brain-Inspired Design: Neuroscience-based agent principles vs. generic multi-agent
- Memory Architecture: Sophisticated agent persistence vs. simple conversation history
- Fault Tolerance: Component-level agent resilience vs. system-wide failures
- Observability: Deep agent introspection vs. basic logging
- Install Neuron and run the quick start example
- Go through the Tutorials in Google Colab to understand the architecture
- Read the Evaluation Notebook to understand capabilities
- Join the Community for support and contributions
We welcome contributions! See CONTRIBUTING.md for guidelines.
Modified MIT License, see LICENSE.md for the terms.
References
-
Anderson, J. R., & Lebiere, C. (2003). The Newell Test for a theory of cognition. Behavioral and Brain Sciences, 26(5), 587-640. Relevance: Foundational work on cognitive architectures that inspired Neuron's modular agent design and memory integration patterns.
-
Hassabis, D., Kumaran, D., Summerfield, C., & Botvinick, M. (2017). Neuroscience-inspired artificial intelligence. Neuron, 95(2), 245-258. Relevance: Provides the theoretical framework for translating neuroscience principles into AI architectures, particularly memory systems and hierarchical processing.
-
Stone, P., & Veloso, M. (2000). Multiagent systems: A survey from a machine learning perspective. Autonomous Robots, 8(3), 345-383. Relevance: Establishes foundational principles for multi-agent coordination and communication protocols that inform Neuron's SynapticBus architecture.
-
Tulving, E. (2002). Episodic memory: From mind to brain. Annual Review of Psychology, 53(1), 1-25. Relevance: Seminal work on episodic memory systems that directly influenced Neuron's multi-layered memory architecture and temporal reasoning capabilities.
-
Gal, Y., & Ghahramani, Z. (2016). Dropout as a Bayesian approximation: Representing model uncertainty in deep learning. International Conference on Machine Learning, 1050-1059. Relevance: Theoretical foundation for uncertainty quantification methods used in Neuron's confidence-based routing and self-monitoring systems.
-
Cox, M. T. (2005). Metacognition in computation: A selected research review. Artificial Intelligence, 169(2), 104-141. Relevance: Provides the conceptual framework for self-monitoring and introspective capabilities that enable Neuron's error detection and adaptive behavior mechanisms.
This software was created and is maintained by Shalini Ananda (GitHub: @ShaliniAnandaPhD). Any use of this framework without attribution, or any commercial repackaging, is a violation of the license terms and may constitute copyright infringement.
Please review the LICENSE.md for conditions. Reach out via GitHub Sponsors for partnership or licensing discussions.