How elarion12/cerberus works
Cerberus is a three-language agent runtime: Python exposes the agent API and local-model/tool integrations, while a C++ reasoning engine and C11 primitives provide native execution and memory support. The principal workflow accepts a task, plans with an LLM, dispatches tools, and incorporates results into context for further reasoning. README diagrams document the Python-to-native bridge and memory/RAG capabilities. Source excerpts establish selected calls and dependencies; links to unsampled implementation details are omitted or marked unverified.
Main entry points: pybind_main.cpp Pybind Bridge · Agent.cpp C++ Agent · agent.py Python Agent · SwarmOrchestrator.hpp Swarm Orchestrator
Components 25
Python Agent API
- Prompt Runner
run_prompt.py - Python Agent
python/cerberus/agent.py - Ollama Client
python/cerberus/llm.py - Python Tools
python/cerberus/tools.py - MCP Client
python/cerberus/mcp_client.py - Filesystem MCP
python/cerberus/mcp_filesystem_server.py - Python Shared Memory
python/cerberus/shared_memory.py
Native Reasoning
- Pybind Bridge
src/bindings/pybind_main.cpp - C++ Agent
src/cpp_engine/agent/Agent.cpp - Output Parser
src/cpp_engine/parser/OutputParser.cpp - Tool Registry
src/cpp_engine/tools/ToolRegistry.hpp - Dynamic Tool Registry
src/cpp_engine/tools/DynamicToolRegistry.cpp - Swarm Orchestrator
src/cpp_engine/swarm/SwarmOrchestrator.hpp
Memory and RAG
- Context Buffer
src/cpp_engine/memory/ContextBuffer.hpp - KV Cache Arena
src/cpp_engine/memory/KVCacheArena.hpp - Vector Buffer
src/cpp_engine/memory/VectorBuffer.hpp - HNSW Index
src/cpp_engine/memory/HNSWIndex.hpp - SQ8 Quantizer
src/cpp_engine/memory/SQ8Quantizer.hpp
C Runtime Core
- Shared Memory
src/cpp_engine/core/SharedMemory.hpp - C Arena Allocator
src/c_core/memory/allocator.c - C Thread Pool
src/c_core/threading/thread_pool.c - Telemetry Ring
src/c_core/telemetry/ringbuf.c - Process Executor
src/c_core/executor/executor.c
Other components
- User
- Ollama Server
Connections 31
- User → Prompt Runner: submits prompt
README.md - Prompt Runner → Python Agent: starts agent
README.md - Python Agent → Ollama Client: requests plans
python/cerberus/agent.py - Ollama Client → Ollama Server: sends generation request
python/cerberus/llm.py - Python Agent → Python Tools: registers tools
python/cerberus/agent.py - Python Agent → MCP Client: uses MCP bridge
python/cerberus/agent.py - MCP Client → Filesystem MCP: connects over stdio
- Python Agent → Python Shared Memory: uses memory
python/cerberus/agent.py - Python Agent → Pybind Bridge: exposes native API
- Prompt Runner → Pybind Bridge: uses native bridge
README.md - Pybind Bridge → C++ Agent: exposes agent
src/bindings/pybind_main.cpp - Pybind Bridge → Context Buffer: exposes context
src/bindings/pybind_main.cpp - Pybind Bridge → Tool Registry: exposes registry
src/bindings/pybind_main.cpp - Pybind Bridge → Dynamic Tool Registry: exposes dynamic tools
src/bindings/pybind_main.cpp - Pybind Bridge → Vector Buffer: exposes vector memory
src/bindings/pybind_main.cpp - Pybind Bridge → KV Cache Arena: exposes KV cache
src/bindings/pybind_main.cpp - Pybind Bridge → Swarm Orchestrator: exposes orchestration
src/bindings/pybind_main.cpp - Pybind Bridge → Shared Memory: exposes shared memory
src/bindings/pybind_main.cpp - C++ Agent → Context Buffer: uses context
- C++ Agent → Dynamic Tool Registry: uses tool registry
- C++ Agent → Output Parser: uses parser
- C++ Agent → Shared Memory: accesses shared memory
- C++ Agent → Swarm Orchestrator: delegates workers
- Vector Buffer → HNSW Index: indexes vectors
src/cpp_engine/memory/VectorBuffer.hpp - Vector Buffer → SQ8 Quantizer: quantizes vectors
src/cpp_engine/memory/VectorBuffer.hpp - HNSW Index → SQ8 Quantizer: uses quantizer
src/cpp_engine/memory/HNSWIndex.hpp - Context Buffer → C Arena Allocator: allocates in
src/cpp_engine/memory/ContextBuffer.hpp - Shared Memory → C Arena Allocator: uses scratch arena
src/cpp_engine/core/SharedMemory.hpp - Swarm Orchestrator → C Thread Pool: submits worker tasks
src/cpp_engine/swarm/SwarmOrchestrator.hpp - Swarm Orchestrator → Telemetry Ring: records spans
- C++ Agent → Process Executor: uses process execution