⚡ NexusAgent

The Zero-Config, Self-Evolving Local AI Agent Framework

Privacy-first · GraphRAG memory · Skill auto-generation · Plugin ecosystem

Install · Quick Start · Features · CLI · Website · Config · Plugins

---

Table of Contents

• Features
• Architecture
• Installation
• Quick Start
• CLI Reference
• Configuration
• Plugin System
• API Reference
• Enterprise Features
• Comparison
• Performance
• Roadmap
• Contributing
• License
• Acknowledgments

---

✨ Features

• 🧠 GraphRAG Memory — Persistent knowledge graph using NetworkX for intelligent context retrieval
• 🔧 Auto Skill Generation — Agent writes its own tools during runtime and saves them permanently
• 🔌 Plugin System — Extend with custom plugins, hot-reload support, hook-based architecture
• 🐳 Docker Ready — Full containerization with Docker and docker-compose support
• 🌐 Web Dashboard — Optional FastAPI dashboard for monitoring skills, memory, and task history
• 🔒 Privacy-First — Local-first execution with Ollama. Optional cloud models via LiteLLM.
• ⚡ Zero Config — Works out of the box with Ollama; configurable when you need it
• 📦 Sandboxed Execution — Isolated skill execution with timeouts and memory limits
• 🤖 Multi-Agent System — Orchestrate multiple agents with task delegation and role-based routing
• 🛡️ Enterprise Security — Encrypted cloud sync (Fernet), audit logging with RBAC
• 🎤 Voice Interface — Speech-to-text (Whisper) and text-to-speech integration
• 💻 IDE Integration — JSON-RPC server for VS Code, JetBrains, and other editors
• 🚀 Self-Updating — Check for new versions, auto-update skills from a registry
• 💾 Export System — Export skills, graphs, and reports as JSON, Markdown, or skill packs
• 🎯 Multi-Model — Works with any model via LiteLLM (Ollama, OpenAI, Anthropic, etc.)

🏗 Architecture

graph TB
    CLI[CLI / Web Dashboard] --> Agent[NexusAgent Core]
    Agent --> LiteLLM[LiteLLM Router]
    LiteLLM --> Ollama[Ollama / OpenAI / Anthropic]
    
    Agent --> Memory[GraphRAG Memory<br/>NetworkX]
    Agent --> Skills[Skill Tree<br/>Auto-Generated Tools]
    Agent --> Plugins[Plugin Manager<br/>Hot-Reload]
    Agent --> Sandbox[Sandbox Executor<br/>Isolated Subprocess]
    
    Config[Config Manager<br/>YAML/JSON] --> Agent
    Updater[Self-Updater<br/>PyPI + Registry] --> Agent
    Exporter[Export Engine<br/>JSON / MD / ZIP] --> Agent
    
    Memory --> Persist[(Local Storage<br/>.nexus/)]
    Skills --> Persist
    Plugins --> PluginDir[.nexus/plugins/]
    
    style Agent fill:#0ea5e9,color:#fff
    style Memory fill:#22c55e,color:#fff
    style Skills fill:#a855f7,color:#fff
    style Plugins fill:#f59e0b,color:#fff

Loading

📦 Installation

pip (Recommended)

pip install nexus-agent

pipx (Isolated)

pipx install nexus-agent

Docker

docker pull rudra496/nexus-agent
docker run -it -v $(pwd):/workspace rudra496/nexus-agent run "Explain quantum computing"

From Source

git clone https://github.com/rudra496/nexus-agent.git
cd nexus-agent
pip install -e .

Requires: Python 3.10+ and Ollama for local models (optional for cloud models).

🚀 Quick Start

# 1. Start Ollama (if using local models)
ollama serve

# 2. Pull a model
ollama pull llama3

# 3. Run your first task
nexus run "Create a Python function to calculate Fibonacci numbers"

# 4. Check status
nexus status

# 5. Trigger self-evolution — scans your workspace and builds GraphRAG memory
nexus evolve

# 6. View generated skills
nexus skills

📋 CLI Reference

Command	Description
nexus run "prompt"	Execute a task with the AI agent
nexus evolve	Scan workspace and build GraphRAG memory
nexus status	View memory, skills, and plugin diagnostics
nexus skills	List all auto-generated skills
nexus config show	Display current configuration
nexus config set model.default ollama/codellama	Set a config value
nexus config reset	Reset config to defaults
nexus web	Launch the web dashboard (port 8420)
nexus export -f json -k skills	Export skills as JSON
nexus export -f markdown -k report	Export full report
nexus export -f skillpack	Export shareable skill pack
nexus plugin list	List installed plugins
nexus plugin reload	Hot-reload plugins
nexus update	Check for updates and self-update
nexus sync push	Push local data to encrypted cloud sync
nexus sync pull	Pull data from cloud sync target
nexus sync status	Show cloud sync status
nexus audit log	View audit log entries
nexus audit stats	Show audit log statistics
nexus marketplace search "query"	Search marketplace for skills
nexus marketplace install <name>	Install a skill from marketplace
nexus marketplace list	List all available marketplace skills
nexus benchmark run	Run all performance benchmarks
nexus benchmark compare <f1> <f2>	Compare two benchmark files
nexus agents register <name> --role coder	Register a new agent
nexus agents status	Show multi-agent system status
nexus voice	Voice interface: listen and respond
nexus analyze [path]	AST-aware code analysis
nexus mobile	Start mobile companion API server

⚙ Configuration

NexusAgent uses a YAML config file at ~/.nexus/config.yaml (auto-created on first run).

model:
  default: "ollama/llama3"
  fallback: null
  max_tokens: 2048
  temperature: 0.7

memory:
  max_nodes: 10000
  max_edges: 50000
  persistence_file: ".nexus/memory/graph.pkl"

skills:
  directory: ".nexus/skills"
  auto_evolve: true
  sandbox_enabled: true
  timeout_seconds: 30

plugins:
  directory: ".nexus/plugins"
  hot_reload: true

web:
  enabled: false
  host: "127.0.0.1"
  port: 8420

See docs/configuration.md for the full reference.

🔌 Plugin System

Extend NexusAgent with custom plugins. Drop a .py file in .nexus/plugins/:

# .nexus/plugins/my_plugin.py

def nexus_pre_execute(prompt: str) -> str:
    """Hook called before agent execution."""
    print(f"[MyPlugin] Processing: {prompt[:50]}...")
    return prompt

def nexus_post_execute(response: str) -> str:
    """Hook called after agent execution."""
    return response.upper()  # Example transform

nexus plugin list    # See loaded plugins
nexus plugin reload  # Hot-reload changed plugins

See docs/plugin-guide.md for the full plugin development guide.

📖 API Reference

from src.agent import NexusAgent
from src.config import load_config, save_config
from src.plugins import PluginManager
from src.export import export_skills_json, export_markdown_report
from src.sandbox import Sandbox

# Create agent with custom model
agent = NexusAgent(model="ollama/codellama")

# Execute a task
response = agent.execute("Write a sorting algorithm")

# Evolve (scan workspace)
stats = agent.evolve()

# Export data
export_skills_json(agent, "skills.json")
export_markdown_report(agent, "report.md")

# Sandbox execution
sandbox = Sandbox(timeout=30, max_memory_mb=256)
result = sandbox.execute("print('Hello from sandbox!')")

See docs/api-reference.md for complete API docs.

🔐 Enterprise Features

NexusAgent includes enterprise-grade features for team deployments:

• Audit Logging — Structured JSON-lines audit log tracking all agent actions with log rotation
• RBAC — Role-based access control with admin, user, and viewer roles
• Encrypted Sync — Fernet symmetric encryption for all synced data
• CLI: nexus audit log, nexus audit stats, nexus sync push/pull/status

📊 Comparison

Feature	NexusAgent	Aider	Continue.dev	Cursor	OpenHands
Runs Locally (with Ollama)	✅	✅	✅	✅	✅
GraphRAG Memory	✅	❌	❌	❌	❌
Self-Evolving Skills	✅	❌	❌	❌	❌
Plugin System	✅	❌	✅	✅	✅
Web Dashboard	✅	❌	❌	✅	✅
Zero-Config Setup	✅	⚠️	⚠️	✅	⚠️
Sandboxed Execution	✅	❌	❌	❌	✅
CLI Interface	✅	✅	✅	❌	✅
Open Source (MIT)	✅	✅	✅ (Apache)	❌	✅

⚠️ = Requires some configuration. This comparison reflects publicly available documentation as of April 2026 and is provided in good faith — please verify for your specific use case.

⚡ Performance

NexusAgent is designed for minimal overhead. Key performance characteristics:

Component	Design Target	Notes
Startup	Near-instant	Only loads config + existing skills
Graph Retrieval	Proportional to graph size	Keyword-based lookup over NetworkX
Skill Execution	Bounded by sandbox timeout	Configurable, default 30s
Plugin Load	On-demand	Loaded once, hot-reloaded on change

Run nexus benchmark run to measure actual performance on your hardware. Use nexus benchmark compare to track regressions across versions.

🗺 Roadmap

See docs/roadmap.md for the full roadmap.

✅ v0.1 — Core Agent

• GraphRAG memory with NetworkX
• Auto skill generation
• Basic CLI (run, evolve, status, skills)
• LiteLLM multi-model support + Ollama

✅ v0.2 — Plugins & Dashboard

• Configuration management (YAML/JSON)
• Plugin system with hot-reload
• Web dashboard (FastAPI + REST API)
• Sandboxed execution (timeout, memory limits)
• Export system (JSON, Markdown, ZIP skill packs)
• Self-updater + skill registry
• Docker support
• CI/CD + tests

✅ v0.3 — Multi-Agent

• Multi-agent orchestration engine
• Task delegation and intelligent routing
• Collaborative shared memory
• Agent communication protocol (broadcast + direct messaging)
• Agent roles (coder, reviewer, tester, planner, researcher)
• Priority-based task queue with load balancing

✅ v0.4 — Voice & IDE

• Voice interface (Whisper STT + pyttsx3/edge-tts TTS)
• IDE integration base (JSON-RPC, VS Code manifest, JetBrains ready)
• AST-aware code memory (functions, classes, imports, dependencies)
• Context window management (token budgeting, priority selection)
• nexus voice and nexus analyze CLI commands

✅ v1.0 — Production

• Encrypted cloud sync (Fernet, local/S3/WebDAV, delta sync)
• Audit logging & RBAC (JSON-lines, admin/user/viewer, log rotation)
• Skill marketplace (search, install, rate, 6 categories)
• Performance benchmark suite (4 benchmarks, compare runs)
• Mobile companion API (REST + JWT, mobile web UI)
• 140+ tests across all modules

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

Please read our Code of Conduct and Security Policy.

🐛 Troubleshooting

Ollama not running? Start it with ollama serve or verify it's running at http://localhost:11434.

Windows compatibility — NexusAgent uses sys.executable for sandboxed execution, ensuring cross-platform compatibility.

Import errors — Make sure you installed with pip install -e ".[all]" for all optional dependencies.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

🙏 Acknowledgments

• LiteLLM — Unified LLM API
• NetworkX — GraphRAG memory backbone
• Rich — Beautiful CLI output
• Typer — CLI framework
• FastAPI — Web dashboard framework
• Ollama — Local LLM runtime

💖 Sponsor

If you find NexusAgent useful, consider supporting its development:

👤 Author

Rudra Sarker

---

_{Built with ⚡ by Rudra Sarker}

---

More Open Source Projects

Project	Stars	Description
StealthHumanizer		Free AI text humanizer — 13 providers, no login
EdgeBrain		Edge AI inference — sub-100ms, no cloud
DevRoadmaps		17 career paths, 1700+ free resources
CodeVista		AI code analysis & security scanner
MindWell		Free mental health support platform
ScienceLab 3D		40+ virtual STEM experiments
SightlineAI		AI smart glasses for the blind

---

⭐ Star this repo · 🍴 Fork it · 👤 Follow @rudra496