# elarion12/geryon architecture

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

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

## Overview

Geryon is a lightweight framework for tool-calling agents backed by an external model, with Python APIs over a native C/C++ runtime. The main workflow is task → planning → tool dispatch → result in conversation context → another plan or final answer. The README also describes vector memory, MCP tools, swarm execution, shared memory, telemetry, and KV-cache pages. Some of these implementations were not excerpted; those capability links are documented in the README, while internal call paths are shown only where evidence supports them.

Main entry points: [`src/bindings/pybind_main.cpp`](https://github.com/elarion12/geryon/blob/main/src/bindings/pybind_main.cpp) (Python bindings), [`python/geryon/agent.py`](https://github.com/elarion12/geryon/blob/main/python/geryon/agent.py) (Python agent), [`src/cpp_engine/agent/Agent.cpp`](https://github.com/elarion12/geryon/blob/main/src/cpp_engine/agent/Agent.cpp) (C++ agent), [`src/cpp_engine/swarm/SwarmOrchestrator.hpp`](https://github.com/elarion12/geryon/blob/main/src/cpp_engine/swarm/SwarmOrchestrator.hpp) (Swarm orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python API"]
  node_py_agent["Python agent<br/>[agent.py]"]
  node_python_tools["Python tools<br/>[tools.py]"]
  node_native_binding["Python bindings<br/>[pybind_main.cpp]"]
end

subgraph group_agent["Agent Runtime"]
  node_native_agent["C++ agent<br/>[Agent.cpp]"]
  node_parser["Output parser<br/>[OutputParser.cpp]"]
  node_registry["Tool registry<br/>[ToolRegistry.hpp]"]
  node_swarm["Swarm orchestrator"]
end

subgraph group_memory["Memory Systems"]
  node_context["Context buffer<br/>[ContextBuffer.hpp]"]
  node_vector_memory[("Vector memory<br/>[VectorBuffer.hpp]")]
  node_hnsw["HNSW index<br/>[HNSWIndex.hpp]"]
  node_sq8["SQ8 quantizer<br/>[SQ8Quantizer.hpp]"]
  node_kv_cache[("KV-cache pages<br/>[KVCacheArena.hpp]")]
  node_shared_board[("Shared memory<br/>[shared_memory.py]")]
end

subgraph group_native["Native Core"]
  node_thread_pool["Thread pool<br/>[thread_pool.c]"]
  node_telemetry[("Telemetry ring<br/>[ringbuf.c]")]
  node_arena["Arena allocator<br/>[allocator.c]"]
end

subgraph group_integrations["Integrations"]
  node_ollama["Ollama client<br/>[llm.py]"]
  node_mcp_bridge["MCP bridge<br/>[mcp_client.py]"]
end

node_user(("Application developer"))
node_mcp_server["MCP server"]
node_ollama_service["Ollama service"]

node_user -->|"configures and runs"| node_py_agent
node_py_agent -->|"requests plans"| node_ollama
node_ollama -->|"sends HTTP requests"| node_ollama_service
node_py_agent -->|"dispatches tools"| node_python_tools
node_py_agent -->|"connects MCP tools"| node_mcp_bridge
node_mcp_bridge -->|"communicates over stdio"| node_mcp_server
node_py_agent -->|"writes worker results"| node_shared_board
node_native_binding -->|"exposes to Python"| node_native_agent
node_native_binding -->|"exposes to Python"| node_vector_memory
node_native_binding -->|"exposes to Python"| node_kv_cache
node_native_agent -->|"uses context"| node_context
node_native_agent -->|"owns tool registry"| node_registry
node_native_agent -->|"parses tool output"| node_parser
node_context -->|"allocates prompt memory"| node_arena
node_vector_memory -->|"supports indexing"| node_hnsw
node_vector_memory -->|"uses quantization"| node_sq8
node_swarm -->|"submits worker tasks"| node_thread_pool
node_swarm -.->|"shares worker results"| node_shared_board
node_swarm -.->|"records events"| node_telemetry
node_native_binding -->|"exposes to Python"| node_swarm
node_native_binding -->|"exposes telemetry"| node_telemetry

click node_py_agent "https://github.com/elarion12/geryon/blob/main/python/geryon/agent.py"
click node_ollama "https://github.com/elarion12/geryon/blob/main/python/geryon/llm.py"
click node_python_tools "https://github.com/elarion12/geryon/blob/main/python/geryon/tools.py"
click node_mcp_bridge "https://github.com/elarion12/geryon/blob/main/python/geryon/mcp_client.py"
click node_native_binding "https://github.com/elarion12/geryon/blob/main/src/bindings/pybind_main.cpp"
click node_native_agent "https://github.com/elarion12/geryon/blob/main/src/cpp_engine/agent/Agent.cpp"
click node_context "https://github.com/elarion12/geryon/blob/main/src/cpp_engine/memory/ContextBuffer.hpp"
click node_parser "https://github.com/elarion12/geryon/blob/main/src/cpp_engine/parser/OutputParser.cpp"
click node_registry "https://github.com/elarion12/geryon/blob/main/src/cpp_engine/tools/ToolRegistry.hpp"
click node_vector_memory "https://github.com/elarion12/geryon/blob/main/src/cpp_engine/memory/VectorBuffer.hpp"
click node_hnsw "https://github.com/elarion12/geryon/blob/main/src/cpp_engine/memory/HNSWIndex.hpp"
click node_sq8 "https://github.com/elarion12/geryon/blob/main/src/cpp_engine/memory/SQ8Quantizer.hpp"
click node_kv_cache "https://github.com/elarion12/geryon/blob/main/src/cpp_engine/memory/KVCacheArena.hpp"
click node_shared_board "https://github.com/elarion12/geryon/blob/main/python/geryon/shared_memory.py"
click node_swarm "https://github.com/elarion12/geryon/blob/main/src/cpp_engine/swarm/SwarmOrchestrator.hpp"
click node_thread_pool "https://github.com/elarion12/geryon/blob/main/src/c_core/threading/thread_pool.c"
click node_telemetry "https://github.com/elarion12/geryon/blob/main/src/c_core/telemetry/ringbuf.c"
click node_arena "https://github.com/elarion12/geryon/blob/main/src/c_core/memory/allocator.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_py_agent,node_python_tools,node_native_binding toneBlue
class node_native_agent,node_parser,node_registry,node_swarm toneAmber
class node_context,node_vector_memory,node_hnsw,node_sq8,node_kv_cache,node_shared_board,node_mcp_server toneMint
class node_thread_pool,node_telemetry,node_arena toneRose
class node_ollama,node_mcp_bridge,node_user,node_ollama_service toneIndigo
```

## Components

### Python API

- [Python agent](https://github.com/elarion12/geryon/blob/main/python/geryon/agent.py): `python/geryon/agent.py`
- [Python tools](https://github.com/elarion12/geryon/blob/main/python/geryon/tools.py): `python/geryon/tools.py`
- [Python bindings](https://github.com/elarion12/geryon/blob/main/src/bindings/pybind_main.cpp): `src/bindings/pybind_main.cpp`

### Agent Runtime

- [C++ agent](https://github.com/elarion12/geryon/blob/main/src/cpp_engine/agent/Agent.cpp): `src/cpp_engine/agent/Agent.cpp`
- [Output parser](https://github.com/elarion12/geryon/blob/main/src/cpp_engine/parser/OutputParser.cpp): `src/cpp_engine/parser/OutputParser.cpp`
- [Tool registry](https://github.com/elarion12/geryon/blob/main/src/cpp_engine/tools/ToolRegistry.hpp): `src/cpp_engine/tools/ToolRegistry.hpp`
- [Swarm orchestrator](https://github.com/elarion12/geryon/blob/main/src/cpp_engine/swarm/SwarmOrchestrator.hpp): `src/cpp_engine/swarm/SwarmOrchestrator.hpp`

### Memory Systems

- [Context buffer](https://github.com/elarion12/geryon/blob/main/src/cpp_engine/memory/ContextBuffer.hpp): `src/cpp_engine/memory/ContextBuffer.hpp`
- [Vector memory](https://github.com/elarion12/geryon/blob/main/src/cpp_engine/memory/VectorBuffer.hpp): `src/cpp_engine/memory/VectorBuffer.hpp`
- [HNSW index](https://github.com/elarion12/geryon/blob/main/src/cpp_engine/memory/HNSWIndex.hpp): `src/cpp_engine/memory/HNSWIndex.hpp`
- [SQ8 quantizer](https://github.com/elarion12/geryon/blob/main/src/cpp_engine/memory/SQ8Quantizer.hpp): `src/cpp_engine/memory/SQ8Quantizer.hpp`
- [KV-cache pages](https://github.com/elarion12/geryon/blob/main/src/cpp_engine/memory/KVCacheArena.hpp): `src/cpp_engine/memory/KVCacheArena.hpp`
- [Shared memory](https://github.com/elarion12/geryon/blob/main/python/geryon/shared_memory.py): `python/geryon/shared_memory.py`

### Native Core

- [Thread pool](https://github.com/elarion12/geryon/blob/main/src/c_core/threading/thread_pool.c): `src/c_core/threading/thread_pool.c`
- [Telemetry ring](https://github.com/elarion12/geryon/blob/main/src/c_core/telemetry/ringbuf.c): `src/c_core/telemetry/ringbuf.c`
- [Arena allocator](https://github.com/elarion12/geryon/blob/main/src/c_core/memory/allocator.c): `src/c_core/memory/allocator.c`

### Integrations

- [Ollama client](https://github.com/elarion12/geryon/blob/main/python/geryon/llm.py): `python/geryon/llm.py`
- [MCP bridge](https://github.com/elarion12/geryon/blob/main/python/geryon/mcp_client.py): `python/geryon/mcp_client.py`

### Other components

- **Application developer**
- **MCP server**
- **Ollama service**

## Connections

- Application developer → Python agent: configures and runs (evidence: `README.md`)
- Python agent → Ollama client: requests plans (evidence: `python/geryon/agent.py`)
- Ollama client → Ollama service: sends HTTP requests (evidence: `python/geryon/llm.py`)
- Python agent → Python tools: dispatches tools (evidence: `python/geryon/agent.py`)
- Python agent → MCP bridge: connects MCP tools (evidence: `python/geryon/agent.py`)
- MCP bridge → MCP server: communicates over stdio (evidence: `python/geryon/mcp_client.py`)
- Python agent → Shared memory: writes worker results (evidence: `python/geryon/agent.py`)
- Python bindings → C++ agent: exposes to Python (evidence: `src/bindings/pybind_main.cpp`)
- Python bindings → Vector memory: exposes to Python (evidence: `src/bindings/pybind_main.cpp`)
- Python bindings → KV-cache pages: exposes to Python (evidence: `src/bindings/pybind_main.cpp`)
- C++ agent → Context buffer: uses context
- C++ agent → Tool registry: owns tool registry
- C++ agent → Output parser: parses tool output
- Context buffer → Arena allocator: allocates prompt memory (evidence: `src/cpp_engine/memory/ContextBuffer.hpp`)
- Vector memory → HNSW index: supports indexing (evidence: `src/cpp_engine/memory/VectorBuffer.hpp`)
- Vector memory → SQ8 quantizer: uses quantization (evidence: `src/cpp_engine/memory/VectorBuffer.hpp`)
- Swarm orchestrator → Thread pool: submits worker tasks (evidence: `src/cpp_engine/swarm/SwarmOrchestrator.hpp`)
- Swarm orchestrator → Shared memory: shares worker results (evidence: `README.md`)
- Swarm orchestrator → Telemetry ring: records events (evidence: `README.md`)
- Python bindings → Swarm orchestrator: exposes to Python (evidence: `src/bindings/pybind_main.cpp`)
- Python bindings → Telemetry ring: exposes telemetry (evidence: `src/bindings/pybind_main.cpp`)
