How elarion12/geryon works
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: pybind_main.cpp Python bindings · agent.py Python agent · Agent.cpp C++ agent · SwarmOrchestrator.hpp Swarm orchestrator
Components 21
Python API
- Python agent
python/geryon/agent.py - Python tools
python/geryon/tools.py - Python bindings
src/bindings/pybind_main.cpp
Agent Runtime
- C++ agent
src/cpp_engine/agent/Agent.cpp - Output parser
src/cpp_engine/parser/OutputParser.cpp - Tool registry
src/cpp_engine/tools/ToolRegistry.hpp - Swarm orchestrator
src/cpp_engine/swarm/SwarmOrchestrator.hpp
Memory Systems
- Context buffer
src/cpp_engine/memory/ContextBuffer.hpp - Vector memory
src/cpp_engine/memory/VectorBuffer.hpp - HNSW index
src/cpp_engine/memory/HNSWIndex.hpp - SQ8 quantizer
src/cpp_engine/memory/SQ8Quantizer.hpp - KV-cache pages
src/cpp_engine/memory/KVCacheArena.hpp - Shared memory
python/geryon/shared_memory.py
Native Core
- Thread pool
src/c_core/threading/thread_pool.c - Telemetry ring
src/c_core/telemetry/ringbuf.c - Arena allocator
src/c_core/memory/allocator.c
Integrations
- Ollama client
python/geryon/llm.py - MCP bridge
python/geryon/mcp_client.py
Other components
- Application developer
- MCP server
- Ollama service
Connections 21
- Application developer → Python agent: configures and runs
README.md - Python agent → Ollama client: requests plans
python/geryon/agent.py - Ollama client → Ollama service: sends HTTP requests
python/geryon/llm.py - Python agent → Python tools: dispatches tools
python/geryon/agent.py - Python agent → MCP bridge: connects MCP tools
python/geryon/agent.py - MCP bridge → MCP server: communicates over stdio
python/geryon/mcp_client.py - Python agent → Shared memory: writes worker results
python/geryon/agent.py - Python bindings → C++ agent: exposes to Python
src/bindings/pybind_main.cpp - Python bindings → Vector memory: exposes to Python
src/bindings/pybind_main.cpp - Python bindings → KV-cache pages: exposes to Python
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
src/cpp_engine/memory/ContextBuffer.hpp - Vector memory → HNSW index: supports indexing
src/cpp_engine/memory/VectorBuffer.hpp - Vector memory → SQ8 quantizer: uses quantization
src/cpp_engine/memory/VectorBuffer.hpp - Swarm orchestrator → Thread pool: submits worker tasks
src/cpp_engine/swarm/SwarmOrchestrator.hpp - Swarm orchestrator → Shared memory: shares worker results
README.md - Swarm orchestrator → Telemetry ring: records events
README.md - Python bindings → Swarm orchestrator: exposes to Python
src/bindings/pybind_main.cpp - Python bindings → Telemetry ring: exposes telemetry
src/bindings/pybind_main.cpp