CogZero is a high-performance C++ implementation of Agent-Zero, specially optimized for integration with the OpenCog cognitive architecture. It serves as an orchestration workbench system that provides a modular catalog of powerful cognitive tools, skills, abilities, and knowledge enhancements.
The standalone/ directory contains a fully self-contained CLI application (cog0) that runs the complete cognitive loop with no external dependencies beyond a C++17 compiler.
cd standalone
mkdir build && cd build
cmake ..
make -j$(nproc)# Interactive REPL
./cog0
# Built-in demo
./cog0 --demo
# Run N cognitive cycles and print status
./cog0 --cycles 10
# Execute an rc-style script file
./cog0 --script my_agent.cog0
# Execute a single command inline
./cog0 --eval "goal explore-world Explore the environment"cog0> goal <name> [description] Set a new goal
cog0> goals List all goals with priority and status
cog0> task <name> [description] Schedule a task
cog0> percept <text> Inject a text percept
cog0> run [N] Run N cognitive cycles (default: 1)
cog0> infer Run one forward-chaining inference pass
cog0> status Print agent status
cog0> atoms List all atoms in the knowledge store
cog0> help Show command reference
cog0> quit Exit
cog0 accepts plain-text script files — one command per line, # for comments.
This enables autonomous-agency scripting without an interactive terminal:
# my_agent.cog0
goal learn-about-opencog Understand the OpenCog ecosystem
percept AtomSpace is a hypergraph knowledge store
task summarise-components Summarise key OpenCog components
run 5
status
./cog0 --script my_agent.cog0# From the standalone/build directory
ctest -V
# → 147 tests passed (unit + e2e + integration + benchmarks + regression + perception)CogZero implements the AGENT-ZERO-GENESIS initiative, creating a C++ variant of Agent-Zero that provides optimal grip and maximum effectiveness within OpenCog's cognitive architecture. The system creates a well-orchestrated and modular catalog of powerful tools, skills, abilities and knowledge enhancements as a coherent and integrated whole.
CogZero is organized into 9 specialized modules, each optimized for specific cognitive functions:
| Module | Purpose | Key Dependencies |
|---|---|---|
| agentzero-core | Main orchestration engine & cognitive loop | cogutil, atomspace, cogserver |
| agentzero-perception | Multi-modal sensory processing | sensory, vision, perception |
| agentzero-planning | Hierarchical planning & goal management | spacetime, cogserver |
| agentzero-learning | Continuous learning & adaptation | moses, asmoses, learn |
| agentzero-memory | Memory & context management | atomspace-rocks, attention |
| agentzero-communication | NLP & multi-agent communication | lg-atomese, opencog |
| agentzero-tools | External tool integration | external-tools, ros-behavior-scripting |
| agentzero-distributed | Distributed computing support | Network protocols, clustering |
| agentzero-python-bridge | Python interoperability | Python C API, pybind11 |
┌─────────────────────────────────────────────────────────────┐
│ agentzero-core │
│ (Orchestration & Cognitive Loop) │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌───────▼────────┐ ┌──────▼──────┐ ┌────────▼────────┐
│ perception │ │ planning │ │ learning │
└───────┬────────┘ └──────┬───────┘ └────────┬────────┘
│ │ │
└──────────────────┼────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌───────▼────────┐ ┌─────▼──────┐ ┌───────▼────────┐
│ memory │ │ communication│ │ tools │
└────────────────┘ └──────────────┘ └────────────────┘
│ │ │
└──────────────────┼──────────────────┘
│
┌──────────────────┴──────────────────┐
│ │
┌───────▼────────┐ ┌────────────▼────────┐
│ distributed │ │ python-bridge │
└────────────────┘ └─────────────────────┘
Required:
- CMake 3.16+
- C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2017+)
- Boost 1.46+
- OpenCog core components:
Optional (for specific modules):
- PLN (Probabilistic Logic Networks)
- URE (Unified Rule Engine)
- MOSES (Meta-Optimizing Semantic Evolutionary Search)
- Pattern Miner
- Link Grammar
# Clone the repository
git clone https://github.com/o9nn/cogzero.git
cd cogzero
# Create build directory
mkdir build && cd build
# Configure with CMake
cmake ..
# Build the system
make -j$(nproc)
# Run tests
make test
# Install (optional)
sudo make install# Debug build with symbols
cmake -DCMAKE_BUILD_TYPE=Debug ..
# Release build with optimizations
cmake -DCMAKE_BUILD_TYPE=Release ..
# Without examples
cmake -DBUILD_EXAMPLES=OFF ..
# Without tests
cmake -DBUILD_TESTING=OFF ..
# With documentation (requires Doxygen)
cmake -DBUILD_DOCS=ON ..
# Custom install prefix
cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..📖 Complete Documentation Index - Start here for all documentation
Getting Started:
- Quick Start Guide - Get up and running in 30 minutes
- Architecture Overview - System design and components
- Build System Guide - Detailed build instructions
Developer Resources:
- API Reference - Complete API documentation
- Developer Guide - Development workflow and standards
- Integration Guide - OpenCog integration patterns
- Code Standards - Coding conventions
Testing & Quality:
- Testing Guide - Unit, integration, and performance testing
- Benchmarking Guide - Performance measurement
- CI/CD Documentation - Continuous integration setup
Operations:
- Deployment Guide - Production deployment
- Troubleshooting Guide - Common issues and solutions
Project Resources:
- AGENT-ZERO-GENESIS.md - Complete project roadmap
- Module READMEs - Each module has detailed documentation in its subdirectory
- All agent state represented as Atoms
- Knowledge structures use standard AtomSpace types
- Temporal information via TimeNodes and AtTimeLinks
- Goal hierarchies as structured Atom trees
- Agent runs as CogServer module
- Real-time state monitoring via CogServer commands
- Network interface for distributed operation
- Debug and introspection capabilities
- PLN rules for inference and reasoning
- URE integration for flexible reasoning patterns
- Custom Agent-Zero reasoning rules
- Uncertainty handling through TruthValues
- MOSES integration for policy optimization
- Pattern mining for knowledge discovery
- Online learning through AtomSpace updates
- Experience replay using stored trajectories
The standalone/ module ships a comprehensive test suite that is built and run automatically:
cd standalone/build
ctest -V
# Results: 49 passed, 0 failedTest categories:
| Suite | File | Tests | Coverage |
|---|---|---|---|
| AtomStore | test_atom_store.cpp |
11 | CRUD, TruthValues, STI/LTI, type queries |
| TaskManager | test_task_manager.cpp |
7 | Goals, tasks, priorities, execution |
| ReasoningEngine | test_reasoning_engine.cpp |
7 | Rules, forward chaining, queries |
| CognitiveLoop | test_cognitive_loop.cpp |
6 | Single cycle, percepts, hooks, threading |
| Agent | test_agent.cpp |
7 | Full agent API, rules, status |
| E2E Scenarios | test_e2e.cpp |
10 | Full multi-component integration |
| Perception | test_perception.cpp |
36 | MultiModalSensor, PerceptualProcessor, AttentionManager, TextualSensor |
End-to-end scenarios covered:
- Full perception → reasoning → action cycle
- Multiple goals with priority ordering
- Task dependency chains
- Reasoning chains across multiple cycles
- Reflection hook statistics collection
- Agent stability under 50+ cycles
- Percept-driven autonomous goal creation
- Concurrent perception (background thread)
- Status report completeness
- Script-style command sequence
tests/
├── unit-tests/ # Unit tests for individual classes
├── integration-tests/ # Integration tests with OpenCog
├── performance-tests/ # Performance benchmarks
├── regression-tests/ # Regression test suite
├── framework/ # Testing framework utilities
└── mocks/ # Mock objects for testing
# All tests (requires OpenCog)
make test
# Specific test suite
ctest -R unit_tests
# With verbose output
ctest -V
# Performance benchmarks
ctest -R performance
# Integration tests
ctest -R integration- Response Time: < 100ms for routine decisions
- Memory Efficiency: Linear scaling with knowledge base size
- Learning Rate: Demonstrable improvement within 1000 interactions
- Integration Overhead: < 10% vs. standalone Agent-Zero
- Scalability: Support for 10M+ Atoms in knowledge base
We welcome contributions! Please see our contributing guidelines:
- Read the Roadmap: Understand the project vision in AGENT-ZERO-GENESIS.md
- Find a Task: Browse existing issues or check the roadmap
- Setup Environment: Install OpenCog dependencies and build system
- Submit PR: Follow standard GitHub workflow with tests and documentation
- C++17 Standard: Modern C++ features encouraged
- OpenCog Patterns: Follow established OpenCog architectural patterns
- Documentation: Document all public interfaces
- Testing: Comprehensive unit and integration tests
- Performance: Consider memory and CPU optimization
See CODE_STANDARDS.md for detailed guidelines.
| Phase | Focus | Status |
|---|---|---|
| Phase 1 | Foundation Layer | ✅ Implemented |
| Phase 2 | Perception & Action | ✅ Implemented |
| Phase 3 | Knowledge & Reasoning | ✅ Implemented |
| Phase 4 | Planning & Goals | ✅ Implemented |
| Phase 5 | Learning & Adaptation | ✅ Implemented |
| Phase 6 | Communication & NLP | ✅ Implemented |
| Phase 7 | Memory & Context | ✅ Implemented |
| Phase 8 | Tool Integration | ✅ Implemented |
| Phase 9 | Integration & Testing | ✅ Implemented |
| Phase 10 | Advanced Features | ✅ Implemented |
| Phase 11 | Performance Profiling | ✅ Implemented |
| Phase 12 | Advanced Coordination & Observability | ✅ Implemented |
| Phase 13 | CI/CD Hardening | ✅ Implemented |
| Phase 14 | Production Hardening | ✅ Implemented |
See ROADMAP.md for the full development roadmap.
- Standalone CLI application (
cog0) with interactive REPL - rc-style script file execution (
--script) - Inline command evaluation (
--eval) - Comprehensive unit + e2e test suite (210+ tests, 0 failures)
- Full cognitive architecture Phases 1–14 implemented
-
goalsandinferREPL commands for introspection and on-demand inference - Raft-based distributed consensus for
MultiAgentCoordinator - Live agent migration across cluster nodes
- Real-time monitoring dashboard (WebSocket + HTML/JS at
/dashboard) - Structured JSON-lines logging for log-aggregation pipelines
- gRPC agent interface (requires external grpc dependency)
- TLS for MonitoringServer (requires mbedTLS/OpenSSL)
- RocksDB-backed persistent Raft log
See AGENT-ZERO-GENESIS.md for the full architecture specification and ROADMAP.md for the detailed development roadmap.
cogzero/
├── CMakeLists.txt # Main build configuration
├── README.md # This file
├── ROADMAP.md # Development roadmap
├── LICENSE # AGPL-3.0 license
├── AGENT-ZERO-GENESIS.md # Architecture specification
├── BUILD_SYSTEM.md # Build system documentation
├── AGENT_ZERO_CI_README.md # CI/CD documentation
├── cmake/ # CMake configuration files
├── docs/ # Comprehensive documentation
├── standalone/ # ✅ Standalone CLI app (no OpenCog needed)
│ ├── main.cpp # cog0 CLI entry point
│ ├── include/cog0/ # Public headers
│ ├── src/ # Implementation (AtomStore, TaskManager, …)
│ └── tests/ # Unit + e2e test suite (49 tests)
├── agentzero-core/ # Core orchestration module
├── agentzero-perception/ # Perception module
├── agentzero-planning/ # Planning module
├── agentzero-learning/ # Learning module
├── agentzero-memory/ # Memory module
├── agentzero-communication/ # Communication module
├── agentzero-tools/ # Tools integration module
├── agentzero-distributed/ # Distributed computing module
├── agentzero-python-bridge/ # Python bridge module
├── tests/ # Full OpenCog test suites
├── profiling/ # Profiling tools
└── examples/ # Example applications
For comprehensive troubleshooting information, see the Troubleshooting Guide.
Build fails with "cogutil not found"
# Install OpenCog dependencies first
# See: https://github.com/opencog/cogutil
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATHCMake configuration errors
# Ensure CMake 3.16+ is installed
cmake --version
# Check C++17 compiler support
g++ --version # GCC 7+ requiredRuntime errors with AtomSpace
- Check AtomSpace initialization
- Verify proper Handle usage and memory management
- Ensure thread-safe operations where needed
See Troubleshooting Guide for detailed solutions.
This project is licensed under the AGPL-3.0-or-later license. See LICENSE for details.
- OpenCog Foundation - For the cognitive architecture framework
- Agent-Zero Project - For the original agent architecture
- Contributors - All developers who have contributed to this project
- GitHub Issues: Report bugs and request features
- Documentation: Check docs/ directory for comprehensive guides
- OpenCog Community: Join the OpenCog discussion forums
- OpenCog - Cognitive architecture framework
- AtomSpace - Hypergraph knowledge representation
- CogServer - Network server for AtomSpace
- pycog0 - Parent repository with full OpenCog ecosystem
CogZero is part of the AGENT-ZERO-GENESIS initiative to create a C++ variant of Agent-Zero optimized for OpenCog integration as an orchestration workbench system.
Built with ❤️ for the OpenCog community