# elarion12/cerberus architecture

> Architecture diagram of the GitHub repository elarion12/cerberus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elarion12/cerberus
- Repository: https://github.com/elarion12/cerberus

## Overview

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: [`src/bindings/pybind_main.cpp`](https://github.com/elarion12/cerberus/blob/main/src/bindings/pybind_main.cpp) (Pybind Bridge), [`src/cpp_engine/agent/Agent.cpp`](https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/agent/Agent.cpp) (C++ Agent), [`python/cerberus/agent.py`](https://github.com/elarion12/cerberus/blob/main/python/cerberus/agent.py) (Python Agent), [`src/cpp_engine/swarm/SwarmOrchestrator.hpp`](https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/swarm/SwarmOrchestrator.hpp) (Swarm Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python Agent API"]
  node_runner["Prompt Runner<br/>[run_prompt.py]"]
  node_pyagent["Python Agent<br/>[agent.py]"]
  node_llm["Ollama Client<br/>[llm.py]"]
  node_pytools["Python Tools<br/>[tools.py]"]
  node_mcpclient["MCP Client<br/>[mcp_client.py]"]
  node_mcpserver["Filesystem MCP"]
  node_pymemory["Python Shared Memory<br/>[shared_memory.py]"]
end

subgraph group_engine["Native Reasoning"]
  node_binding["Pybind Bridge<br/>[pybind_main.cpp]"]
  node_agent["C++ Agent<br/>[Agent.cpp]"]
  node_parser["Output Parser<br/>[OutputParser.cpp]"]
  node_registry["Tool Registry<br/>[ToolRegistry.hpp]"]
  node_dynamic["Dynamic Tool Registry"]
  node_swarm["Swarm Orchestrator"]
end

subgraph group_memory["Memory and RAG"]
  node_context["Context Buffer<br/>[ContextBuffer.hpp]"]
  node_kv["KV Cache Arena<br/>[KVCacheArena.hpp]"]
  node_vectors["Vector Buffer<br/>[VectorBuffer.hpp]"]
  node_hnsw["HNSW Index<br/>[HNSWIndex.hpp]"]
  node_sq8["SQ8 Quantizer<br/>[SQ8Quantizer.hpp]"]
end

subgraph group_core["C Runtime Core"]
  node_shm["Shared Memory<br/>[SharedMemory.hpp]"]
  node_arena["C Arena Allocator<br/>[allocator.c]"]
  node_pool["C Thread Pool<br/>[thread_pool.c]"]
  node_telemetry["Telemetry Ring<br/>[ringbuf.c]"]
  node_executor["Process Executor<br/>[executor.c]"]
end

node_user(("User"))
node_ollama["Ollama Server"]

node_user -->|"submits prompt"| node_runner
node_runner -->|"starts agent"| node_pyagent
node_pyagent -->|"requests plans"| node_llm
node_llm -->|"sends generation request"| node_ollama
node_pyagent -->|"registers tools"| node_pytools
node_pyagent -->|"uses MCP bridge"| node_mcpclient
node_mcpclient -.->|"connects over stdio"| node_mcpserver
node_pyagent -->|"uses memory"| node_pymemory
node_pyagent -.->|"exposes native API"| node_binding
node_runner -->|"uses native bridge"| node_binding
node_binding -->|"exposes agent"| node_agent
node_binding -->|"exposes context"| node_context
node_binding -->|"exposes registry"| node_registry
node_binding -->|"exposes dynamic tools"| node_dynamic
node_binding -->|"exposes vector memory"| node_vectors
node_binding -->|"exposes KV cache"| node_kv
node_binding -->|"exposes orchestration"| node_swarm
node_binding -->|"exposes shared memory"| node_shm
node_agent -->|"uses context"| node_context
node_agent -->|"uses tool registry"| node_dynamic
node_agent -->|"uses parser"| node_parser
node_agent -->|"accesses shared memory"| node_shm
node_agent -.->|"delegates workers"| node_swarm
node_vectors -->|"indexes vectors"| node_hnsw
node_vectors -->|"quantizes vectors"| node_sq8
node_hnsw -->|"uses quantizer"| node_sq8
node_context -->|"allocates in"| node_arena
node_shm -->|"uses scratch arena"| node_arena
node_swarm -->|"submits worker tasks"| node_pool
node_swarm -.->|"records spans"| node_telemetry
node_agent -.->|"uses process execution"| node_executor

click node_runner "https://github.com/elarion12/cerberus/blob/main/run_prompt.py"
click node_pyagent "https://github.com/elarion12/cerberus/blob/main/python/cerberus/agent.py"
click node_llm "https://github.com/elarion12/cerberus/blob/main/python/cerberus/llm.py"
click node_pytools "https://github.com/elarion12/cerberus/blob/main/python/cerberus/tools.py"
click node_mcpclient "https://github.com/elarion12/cerberus/blob/main/python/cerberus/mcp_client.py"
click node_mcpserver "https://github.com/elarion12/cerberus/blob/main/python/cerberus/mcp_filesystem_server.py"
click node_pymemory "https://github.com/elarion12/cerberus/blob/main/python/cerberus/shared_memory.py"
click node_binding "https://github.com/elarion12/cerberus/blob/main/src/bindings/pybind_main.cpp"
click node_agent "https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/agent/Agent.cpp"
click node_parser "https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/parser/OutputParser.cpp"
click node_registry "https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/tools/ToolRegistry.hpp"
click node_dynamic "https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/tools/DynamicToolRegistry.cpp"
click node_swarm "https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/swarm/SwarmOrchestrator.hpp"
click node_context "https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/memory/ContextBuffer.hpp"
click node_kv "https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/memory/KVCacheArena.hpp"
click node_vectors "https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/memory/VectorBuffer.hpp"
click node_hnsw "https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/memory/HNSWIndex.hpp"
click node_sq8 "https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/memory/SQ8Quantizer.hpp"
click node_shm "https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/core/SharedMemory.hpp"
click node_arena "https://github.com/elarion12/cerberus/blob/main/src/c_core/memory/allocator.c"
click node_pool "https://github.com/elarion12/cerberus/blob/main/src/c_core/threading/thread_pool.c"
click node_telemetry "https://github.com/elarion12/cerberus/blob/main/src/c_core/telemetry/ringbuf.c"
click node_executor "https://github.com/elarion12/cerberus/blob/main/src/c_core/executor/executor.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_pyagent,node_llm,node_pytools,node_mcpclient,node_mcpserver,node_pymemory,node_user toneBlue
class node_binding,node_agent,node_parser,node_registry,node_dynamic,node_swarm toneAmber
class node_context,node_kv,node_vectors,node_hnsw,node_sq8,node_ollama toneMint
class node_shm,node_arena,node_pool,node_telemetry,node_executor toneRose
```

## Components

### Python Agent API

- [Prompt Runner](https://github.com/elarion12/cerberus/blob/main/run_prompt.py): `run_prompt.py`
- [Python Agent](https://github.com/elarion12/cerberus/blob/main/python/cerberus/agent.py): `python/cerberus/agent.py`
- [Ollama Client](https://github.com/elarion12/cerberus/blob/main/python/cerberus/llm.py): `python/cerberus/llm.py`
- [Python Tools](https://github.com/elarion12/cerberus/blob/main/python/cerberus/tools.py): `python/cerberus/tools.py`
- [MCP Client](https://github.com/elarion12/cerberus/blob/main/python/cerberus/mcp_client.py): `python/cerberus/mcp_client.py`
- [Filesystem MCP](https://github.com/elarion12/cerberus/blob/main/python/cerberus/mcp_filesystem_server.py): `python/cerberus/mcp_filesystem_server.py`
- [Python Shared Memory](https://github.com/elarion12/cerberus/blob/main/python/cerberus/shared_memory.py): `python/cerberus/shared_memory.py`

### Native Reasoning

- [Pybind Bridge](https://github.com/elarion12/cerberus/blob/main/src/bindings/pybind_main.cpp): `src/bindings/pybind_main.cpp`
- [C++ Agent](https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/agent/Agent.cpp): `src/cpp_engine/agent/Agent.cpp`
- [Output Parser](https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/parser/OutputParser.cpp): `src/cpp_engine/parser/OutputParser.cpp`
- [Tool Registry](https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/tools/ToolRegistry.hpp): `src/cpp_engine/tools/ToolRegistry.hpp`
- [Dynamic Tool Registry](https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/tools/DynamicToolRegistry.cpp): `src/cpp_engine/tools/DynamicToolRegistry.cpp`
- [Swarm Orchestrator](https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/swarm/SwarmOrchestrator.hpp): `src/cpp_engine/swarm/SwarmOrchestrator.hpp`

### Memory and RAG

- [Context Buffer](https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/memory/ContextBuffer.hpp): `src/cpp_engine/memory/ContextBuffer.hpp`
- [KV Cache Arena](https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/memory/KVCacheArena.hpp): `src/cpp_engine/memory/KVCacheArena.hpp`
- [Vector Buffer](https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/memory/VectorBuffer.hpp): `src/cpp_engine/memory/VectorBuffer.hpp`
- [HNSW Index](https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/memory/HNSWIndex.hpp): `src/cpp_engine/memory/HNSWIndex.hpp`
- [SQ8 Quantizer](https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/memory/SQ8Quantizer.hpp): `src/cpp_engine/memory/SQ8Quantizer.hpp`

### C Runtime Core

- [Shared Memory](https://github.com/elarion12/cerberus/blob/main/src/cpp_engine/core/SharedMemory.hpp): `src/cpp_engine/core/SharedMemory.hpp`
- [C Arena Allocator](https://github.com/elarion12/cerberus/blob/main/src/c_core/memory/allocator.c): `src/c_core/memory/allocator.c`
- [C Thread Pool](https://github.com/elarion12/cerberus/blob/main/src/c_core/threading/thread_pool.c): `src/c_core/threading/thread_pool.c`
- [Telemetry Ring](https://github.com/elarion12/cerberus/blob/main/src/c_core/telemetry/ringbuf.c): `src/c_core/telemetry/ringbuf.c`
- [Process Executor](https://github.com/elarion12/cerberus/blob/main/src/c_core/executor/executor.c): `src/c_core/executor/executor.c`

### Other components

- **User**
- **Ollama Server**

## Connections

- User → Prompt Runner: submits prompt (evidence: `README.md`)
- Prompt Runner → Python Agent: starts agent (evidence: `README.md`)
- Python Agent → Ollama Client: requests plans (evidence: `python/cerberus/agent.py`)
- Ollama Client → Ollama Server: sends generation request (evidence: `python/cerberus/llm.py`)
- Python Agent → Python Tools: registers tools (evidence: `python/cerberus/agent.py`)
- Python Agent → MCP Client: uses MCP bridge (evidence: `python/cerberus/agent.py`)
- MCP Client → Filesystem MCP: connects over stdio
- Python Agent → Python Shared Memory: uses memory (evidence: `python/cerberus/agent.py`)
- Python Agent → Pybind Bridge: exposes native API
- Prompt Runner → Pybind Bridge: uses native bridge (evidence: `README.md`)
- Pybind Bridge → C++ Agent: exposes agent (evidence: `src/bindings/pybind_main.cpp`)
- Pybind Bridge → Context Buffer: exposes context (evidence: `src/bindings/pybind_main.cpp`)
- Pybind Bridge → Tool Registry: exposes registry (evidence: `src/bindings/pybind_main.cpp`)
- Pybind Bridge → Dynamic Tool Registry: exposes dynamic tools (evidence: `src/bindings/pybind_main.cpp`)
- Pybind Bridge → Vector Buffer: exposes vector memory (evidence: `src/bindings/pybind_main.cpp`)
- Pybind Bridge → KV Cache Arena: exposes KV cache (evidence: `src/bindings/pybind_main.cpp`)
- Pybind Bridge → Swarm Orchestrator: exposes orchestration (evidence: `src/bindings/pybind_main.cpp`)
- Pybind Bridge → Shared Memory: exposes shared memory (evidence: `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 (evidence: `src/cpp_engine/memory/VectorBuffer.hpp`)
- Vector Buffer → SQ8 Quantizer: quantizes vectors (evidence: `src/cpp_engine/memory/VectorBuffer.hpp`)
- HNSW Index → SQ8 Quantizer: uses quantizer (evidence: `src/cpp_engine/memory/HNSWIndex.hpp`)
- Context Buffer → C Arena Allocator: allocates in (evidence: `src/cpp_engine/memory/ContextBuffer.hpp`)
- Shared Memory → C Arena Allocator: uses scratch arena (evidence: `src/cpp_engine/core/SharedMemory.hpp`)
- Swarm Orchestrator → C Thread Pool: submits worker tasks (evidence: `src/cpp_engine/swarm/SwarmOrchestrator.hpp`)
- Swarm Orchestrator → Telemetry Ring: records spans
- C++ Agent → Process Executor: uses process execution
