Nexus uses a 7-layer modular architecture with a dual-process routing system inspired by cognitive science.
┌─────────────────────────────────────────────────┐
│ CLI (Interactive REPL · Bun Runtime) │
├─────────────────────────────────────────────────┤
│ Intelligence Layer │
│ ├── System 1/2 Dual-Process Router │
│ ├── Skill Store (Procedural Memory) │
│ ├── Experience Learner (Reflect + Evolve) │
│ ├── Mode Manager (Zero-Code Specialization) │
│ └── Memory Manager (Wiki + Semantic) │
├─────────────────────────────────────────────────┤
│ Governance Layer │
│ ├── Permission Guard │
│ ├── Policy Engine │
│ ├── Approval Queue │
│ ├── Budget Store │
│ ├── Audit Logger │
│ ├── Behavioral Monitor │
│ └── Network Guard │
├─────────────────────────────────────────────────┤
│ Middleware Pipeline │
│ ├── Timing │
│ ├── Prompt Firewall (Injection Detection) │
│ ├── Budget Enforcer (Cost Limits) │
│ ├── Permission Middleware │
│ ├── Network Middleware │
│ ├── Supervision Middleware │
│ ├── Monitor Middleware │
│ ├── Memory Context Builder │
│ ├── Artifact Tracker │
│ ├── Tool Compactor │
│ ├── Output Scanner │
│ └── Logger │
├─────────────────────────────────────────────────┤
│ Agent Core (Tool Dispatch + LLM Loop) │
│ ├── Tool Registry │
│ ├── Tool Executor │
│ ├── LLM Provider │
│ └── Context Manager │
├─────────────────────────────────────────────────┤
│ Provider Abstraction (Zero SDK Dependencies) │
│ ├── Anthropic │
│ ├── OpenAI │
│ ├── Google Gemini │
│ ├── Ollama (Local) │
│ └── OpenRouter │
├─────────────────────────────────────────────────┤
│ Runtime Layer │
│ ├── MCP Manager │
│ ├── Cron Scheduler │
│ └── Sandbox Manager │
└─────────────────────────────────────────────────┘
Purpose: User interface and interaction
Components:
- Interactive REPL with readline support
- Slash command parser
- Banner display
- Event handlers
Key File: apps/cli/src/index.ts
Purpose: Learning, routing, and specialization
Components:
- Dual-Process Router — Routes tasks to System 1 (fast) or System 2 (full)
- Skill Store — Manages learned skills with Wilson confidence
- Experience Learner — Reflects, evolves, approves, and retires skills
- Mode Manager — Loads and manages zero-code modes
- Memory Manager — Wiki memory and semantic search
Key Files: packages/intelligence/src/
Inspired by Kahneman's "Thinking, Fast and Slow":
- System 1: Fast, automatic, skill-based execution (60-80% cheaper)
- System 2: Slow, deliberate, full LLM reasoning
Router assesses task risk and complexity:
- Low risk + skill match → System 1
- High risk or no skill → System 2
5-stage learning pipeline:
- STORE — Save task trajectories
- REFLECT — LLM analyzes what worked/didn't
- EVOLVE — Mutate skills based on failures
- APPROVE — Wilson confidence evaluation
- RETIRE — Remove underperforming skills
Purpose: Security, permissions, and audit
Components:
- Permission Guard — Path and tool-level access control
- Policy Engine — Security policy enforcement
- Approval Queue — HITL approval for dangerous operations
- Budget Store — Budget tracking and enforcement
- Audit Logger — Immutable audit trail
- Behavioral Monitor — Anomaly detection
- Network Guard — Network access control
Key Files: packages/governance/src/
Purpose: Cross-cutting concerns
Components:
- Timing, prompt firewall, budget enforcer
- Permission, network, supervision middleware
- Memory context builder, artifact tracker
- Tool compactor, output scanner, logger
Key Files: packages/core/src/middleware/
Purpose: Tool dispatch and LLM loop
Components:
- Tool Registry — Manages available tools
- Tool Executor — Executes tools in parallel
- LLM Provider — Multi-provider abstraction
- Context Manager — Manages conversation context
Key Files: packages/core/src/agent.ts
1. Build context (messages + tools + memory)
2. Run middleware (before)
3. Call LLM with retry logic
4. Parse tool calls
5. Execute tools in parallel
6. Compress context if needed
7. Check budget
8. Repeat until tool calls complete
9. Run middleware (after)
10. Return response
Purpose: Multi-LLM provider support
Components:
- Anthropic, OpenAI, Google, Ollama, OpenRouter
- Direct HTTP calls (zero SDK dependencies)
- Token estimation
- Error handling and retry
Key Files: packages/providers/src/
Purpose: Integration and orchestration
Components:
- MCP Manager — Model Context Protocol integration
- Cron Scheduler — Scheduled task execution
- Sandbox Manager — Code execution sandboxing
Key Files: packages/runtime/src/
User Input → CLI → Router → [Middleware] → Agent Core → Provider → LLM
↓
Tool Execution
↓
[Middleware] → Response
Task Execution → Trajectory Storage → Reflection → Skill Creation/Mutation
↓
Shadow Evaluation
↓
Approval (Auto/Manual)
↓
Trusted Status
↓
Retirement (if needed)
Cross-cutting concerns are handled by middleware, not core logic. This keeps the agent core clean and focused.
Zero SDK dependencies means easy addition of new providers. Direct HTTP calls to provider APIs.
Full TypeScript coverage with strict mode enabled. Types are exported for consumer use.
All layers are composable. Use only what you need.
All events are emitted for monitoring and debugging.
Routine tasks use skill execution instead of full LLM reasoning:
- 60-80% cost reduction
- 3-5x faster execution
- Lower token usage
When approaching token limits:
- Summarize old messages
- Remove redundant tool outputs
- Keep recent context high-fidelity
Independent tools run in parallel:
- Faster overall execution
- Better resource utilization
- Lower latency
O(1) lookup for skill commands:
- Fast routing
- Minimal overhead
- Scalable to thousands of skills
Multiple layers of security:
- Prompt firewall (injection detection)
- Permission guard (access control)
- Network guard (network restrictions)
- Supervision (HITL approval)
- Audit logging (immutable trail)
- Behavioral monitoring (anomaly detection)
All operations are monitored:
- Tool calls are tracked
- File access is logged
- Network requests are audited
- Anomalies are detected
All actions are logged to an immutable audit trail:
- Hash chain for integrity
- SQLite-backed for reliability
- Queryable for investigations
Add custom middleware for your needs:
const customMiddleware: Middleware = async (context, next) => {
// Your logic
return next(context);
};Add custom tools to the tool registry:
const customTool = {
schema: {
name: "custom_tool",
description: "A custom tool",
parameters: { /* ... */ },
},
handler: async (params) => {
// Your logic
},
};Add zero-code modes by dropping markdown files in modes/:
# My Mode
> Description
Focus on:
- Task 1
- Task 2- CLI Reference — CLI commands and options
- Contributing — How to contribute
- FAQ — Frequently asked questions