Version: 0.50.0

New here? Read docs/start-here.md — one page: what this is, the three ways to use it, and the zero-infra knowledge graph. For AIs, llms.txt is the entry index. Full docs are published here.

🤖 AI agents — this repo is self-deploying. If you were pointed here to set it up: read the 🚀 Zero-to-deployed procedure in AGENTS.md, loop genesis.yaml, and run the agent-utilities-deployment skill (or agent-os-genesis for enterprise). Ask the operator one question — homelab or enterprise? — and take it from there.

Point yourself (or any agent) at this repo, or just run:

# macOS / Linux
curl -fsSL https://knuckles-team.github.io/agent-utilities/install.sh | sh

# Windows (PowerShell)
irm https://knuckles-team.github.io/agent-utilities/install.ps1 | iex

The installer checks your host, installs agent-utilities, drops the skill toolkit into every AI tool you have (Claude Code, Cursor, Codex, Windsurf, …), wires the knowledge-graph MCP server, and hands off to a guided deployment. Pick your shape:

curl -fsSL https://knuckles-team.github.io/agent-utilities/install.sh | sh -s -- --profile enterprise

→ Full procedure: Zero-to-deployed · manifest: genesis.yaml.

agent-utilities is a batteries-included harness for building Pydantic-AI agents that ship with a knowledge graph, orchestration, memory, and tools. The zero-infra default needs no databases or external services — the knowledge graph runs in-process. Use it three ways:

→ Full trade-offs: Consumption Models.

All four surfaces talk to one gateway; the gateway owns one knowledge-graph facade; the facade fronts a fast Rust engine (L1) and durable tiers (L2). Everything below the gateway is shared — the surfaces are just different windows onto the same brain.

flowchart TD
    subgraph Surfaces["Four ways in"]
        WEB[agent-webui] & TUI[agent-terminal-ui] & GB[geniusbot] & IDE[Claude Code / Cursor]
    end
    Surfaces -->|REST / MCP| GW["graph-os MCP + REST gateway<br/>(identity · ActionPolicy · metrics)"]
    GW --> KG["KnowledgeGraph facade<br/>(ontology · routing · memory)"]
    KG --> L1["epistemic-graph<br/>Rust engine — L1 (MessagePack/UDS)"]
    KG --> L2["durable L2<br/>Postgres / pg-age · LadybugDB"]
    KG --> OWL["OWL / SHACL · Fuseki<br/>semantics"]
    GW -. fleet events / autonomy .-> FLEET["reconciler · playbooks · autoscaler"]

pip install agent-utilities          # zero external *service* deps to start

Point it at any model provider (OPENAI_API_KEY, or a local vLLM/Ollama endpoint via .env), then create an agent — skills, tools, and the in-process KG included:

from agent_utilities import create_agent

agent, toolsets = create_agent(name="assistant", skill_types=["universal", "graphs"])
print(agent.run_sync("What can you do?").output)

setup-config generate --profile tiny     # complete config.json (every option)
graph-os &                                # KG MCP server — no database needed
agent-utilities-doctor                    # one health sweep across every subsystem

Scale up (--profile single-node-prod/enterprise), add Stardog + pg-age, or let Claude set itself up — all in the Quick Start and Self-Setup guides.

from agent_utilities.mcp import kg_server   # GRAPH_BACKEND=tiered is the default

# Add knowledge...
await kg_server._execute_tool("graph_write", action="add_node",
    node_id="svc:payments", node_type="Service",
    properties='{"team":"fintech","tier":"critical"}')

# ...and query it back — in-process, no server required.
res = await kg_server._execute_tool("graph_query",
    cypher="MATCH (n:Service) WHERE n.tier='critical' RETURN n")

→ The full capability catalog (search, ingest, orchestrate, ontology, memory) is in docs/capabilities.md; runnable code is in the reference agent.

Heads-up — this is two repos. The heavy graph compute lives in a separate Rust engine, epistemic-graph (reached out-of-process over MessagePack/UDS — no PyO3). agent-utilities ships a pure-Python client for it, so you don't need Rust to get started. Contributing? See CONTRIBUTING.md.

• The Technical Novel: Narrative Journey
• Overview
• Key Features
• Intelligence Graph
• First Principles Architecture
• Concept Map
• Architecture & Orchestration
• Multi-Model Config & Secret Storage
• Installation
• Quick Start
• Creating an Agent
• Building MCP Servers
• API Documentation
• Documentation
• Contributing
• License

This section is aspirational direction, not shipped behavior — it's here so you know where the project is heading. For what works today, see Capabilities.

The direction beyond a single agent harness is distributed agentic evolution: agents that learn from their own failures (the harness-engineering pillar ships the evolution loop today) and, over time, contribute reusable breakthroughs — new skills, TeamConfigs, refined prompts — back to a shared knowledge graph so improvements compound across agents. The building blocks that exist now (unified KG, capability auto-activation, cross-agent protocols) are the substrate; the "agents improving each other at scale" end-state is roadmap.

Designed-but-not-yet-running roadmap items (designs/specs exist; do not expect these to work out of the box today):

• Media Generation & Transcription (CONCEPT:ECO-4.30/4.31): Self-hosted image (flux.2 + Stable Diffusion 3.5), video (hunyuanvideo), speech synthesis (xtts), and transcription (faster-whisper) exposed as agent tools under the MEDIA_TOOLS gate — requires the corresponding self-hosted model services to be deployed.
• In-House Training Substrate: Fine-tune the framework's own open-weight models end-to-end — a deterministic reward/data engine, torch/PEFT SFT/DPO/GRPO trainers (data-science-mcp[training]), a pure-Rust loss/optimizer performance path (epistemic-graph), checkpoint→reliability-suite eval hooks, and a model-registry role deploy seam. Build-now / run-later on the GB10 (first run: OpenSeeker SFT).

Grouped by what they do. Each line links to the deep-dive; the full catalog with every concept ID is in docs/guides/features.md.

🧠 Knowledge graph & memory — the zero-infra core. A tiered KG (native Rust L1 + durable Postgres/pg-age L2 + OWL semantics; contrib Neo4j/FalkorDB/LadybugDB) with Schema-Pack domain profiles (KG-2.22–2.37: zero-LLM typed-edge extraction, transitive/inverse OWL closure, bitemporal as_of recall) over a high-performance Rust compute engine (MessagePack/UDS, no PyO3; measured ~52 kB/agent — see the capacity model for the honestly-projected 100M figure).

🗂 Ontology system (Palantir-Foundry parity, graph-native) — the structured layer. Objects, links, interfaces, value/property types, derived properties, functions, action types, durable edits, object sets & fine-grained permissioning (KG-2.26, 2.38–2.48) — OWL/SHACL-backed, reified many-to-many links, bitemporal edit history, exposed over ontology_* MCP tools and the web-UI Object Explorer. A vendor-neutral ArchiMate upper ontology makes ServiceNow↔ERPNext↔Camunda interchangeable in one query.

🔀 Orchestration & self-evolution — how work gets planned and improved. Spec-Driven Development, emergent architecture (capability auto-activation, TeamConfig coalitions), global-workspace attention over multi-agent waves, ontology-to-workflow execution (KG-2.52/53, ORCH-1.41–43: lift a descriptive process into an executable plan), and governed evolution-to-branch publication (AHE-3.18–21: propose-only, governance + regression gated, never auto-pushed).

🏢 Enterprise integration (Company Brain) — getting your systems in. A document-source connector framework (ECO-4.25–4.32, KG-2.59) — native Postgres/filesystem/REST/web-crawl, with every other system riding the ~58-server MCP fleet via the universal mcp_tool source — feeding the 6-layer Company Brain runtime (KG_BRAIN_ENFORCE: trust-decay conflict resolution, field-level survivorship, data ACLs + tenant scoping, human-correction→rule→eval feedback).

📈 Scale-out planes (all opt-in; default stays zero-infra) — how it grows. Externalized durable state (one STATE_DB_URI, OS-5.16–18), tenant-sharded engines (HRW routing, KG-2.58/OS-5.28), Kafka ingest scale-out (KG-2.55–57, fail-loud), queue-driven agent dispatch (ORCH-1.45), and gateway scaling + Prometheus /metrics (OS-5.23, per-tenant rate limits, circuit breakers, GATEWAY_WORKERS).

🛡 Autonomy & governance — how it acts safely. A fleet-autonomy control plane (OS-5.15, 5.24–27, 5.29: POST /api/fleet/events → fail-closed ActionPolicy gate → reconciler, remediation playbooks, health-gated deploy-watch + rollback, reactive autoscaler), server-minted identity & fail-closed permissioning (OS-5.14, JWT ActorContext, HMAC engine auth), enterprise mutation governance, and a hardened MCP multiplexer (ECO-4.34: per-child limits, circuit breakers, restart-on-crash).

Shipped but lightly documented (real code, importable today):

• Causal reasoning: structural-causal-model types, d-separation, and formal reasoning over KG subgraphs — agent_utilities/knowledge_graph/core/formal_reasoning_core.py.
• Skill compiler (CONCEPT:ORCH-1.8): compiles SKILL.md prose (+ optional references/team.yaml) into executable GraphPlan workflows — agent_utilities/workflows/skill_compiler.py.
• Evolutionary memory & aggregation (CONCEPT:KG-2.1): the self-curating CRUD insight/skill memory banks (agent_utilities/harness/evolving_memory.py) plus the global-workspace score→select→broadcast aggregation over multi-agent waves (agent_utilities/graph/workspace_attention.py).
• KG auto-routing: the strategy-based router (agent_utilities/graph/routing/ — fast-path, workflow-context, and policy strategies) backed by capability designation + reward write-back (agent_utilities/knowledge_graph/retrieval/capability_index.py).
• Reactive framework (CONCEPT:ORCH-1.10): graph-native event sourcing, dynamic behavioral dispatch, and multi-axis budget guardrails — agent_utilities/graph/reactive/.

📖 View the Comprehensive Feature List & Architecture Deep Dives

→ Full Concept Map: docs/concept_map.md — canonical concept registry. → Single Source of Truth: docs/concepts.yaml — machine-generated registry of every concept marker in code. → Concept Index: docs/overview.md — all pillars with descriptions and code paths.

Synthesized from concept markers in the codebase into 183 canonical concepts across 18 pillars.

This count and the table below are generated from docs/concepts.yaml by scripts/gen_docs.py. Do not edit by hand.

The detailed architectural diagrams and deep-dive documentation for agent-utilities have been moved to their respective Pillar documentation pages in /docs.

• 1. Graph Orchestration & Planning
  • Contains: First Principles Architecture, SDD Lifecycle, Execution Flow (Dynamic Multi-Layer Parallelism).
• 2. Epistemic Knowledge Graph
  • Contains: Graph-OS Native Ingestion Pipeline, MAGMA Reasoning Views, Persistent Task Tracking.
• 3. Agentic Harness Engineering
  • Contains: Self-Models, Evolution, Evaluation.
• 4. Ecosystem Peripherals
  • Contains: graph-os MCP Tools, Server Endpoints, MCP Loading & Registry Architecture.
• 5. Agent OS Infrastructure
  • Contains: Human-in-the-Loop Tool Approval, Process Lifecycle, Auth/Security.
• 6. GeniusBot Desktop Cockpit
  • Contains: Premium Systems Cockpit, swappable plugins tab matrix, sandboxed terminal widget, visual finance trading dashboard.
• C4 Architecture Diagrams
  • Contains: Ecosystem Dependency Graph, C4 Container Diagram, Cross-Pillar Data Flows.
• Memory Architecture
  • Contains: Multi-Timescale Memory, Memento Context Management, Observational Memory Bridge.
• Company Brain Runtime
  • Contains: the 6-layer model wired end-to-end — trust/conflict resolution & field-level survivorship, data permissions/tenancy/audit, feedback→rule→eval, retrieval budget, streams, KG_BRAIN_ENFORCE.
• Vendor-Neutral Enterprise Ontology
  • Contains: the canonical ArchiMate crosswalk, vendor adapters, code→capability realization, and virtual REST federation.
• Multi-Tenant graph-os over Streamable-HTTP
  • Contains: hierarchical org→user isolation, private-by-default + commons/markings sharing, the five isolation layers (identity → named-graph → scope/visibility → Postgres RLS → audit), tenant-scoped fleet, and the elastic per-tenant engine pool.

Register the Knowledge Graph in your IDE's mcp_config.json using the standard CLI pattern:

{
  "mcpServers": {
    "graph-os": {
      "command": "uv",
      "args": ["run", "graph-os"],
      "env": {
        "AGENT_ID": "local-developer",
        "WORKSPACE_PATH": "${workspaceFolder}"
      }
    }
  }
}

Note: Model selection, routing logic, and system configurations are centralized in your XDG ~/.config/agent-utilities/config.json. Only local workspace paths, local agent IDs, or environment overrides remain in the environment.

All LLM providers, model registries, safety guardrails, and scheduler policies are managed centrally via the XDG-compliant configuration file at ~/.config/agent-utilities/config.json.

Every field in the config.json has a 1-to-1 environment variable override. The environment variables (detailed in .env.example) act as secondary overrides for all settings.

You only need to declare your model providers; every other field has a sensible default. A minimal working config:

{
  "chat_models": [
    {"id": "qwen/qwen3.5-9b", "provider": "openai", "base_url": "http://vllm.arpa/v1",
     "tools_enabled": true, "can_route": true, "can_kg": true}
  ],
  "embedding_models": [
    {"id": "nomic-embed-text-v2", "provider": "openai", "base_url": "http://vllm-embed.arpa/v1"}
  ]
}

Every config.json key maps 1-to-1 to an uppercase environment-variable override (default_agent_name → DEFAULT_AGENT_NAME). JSON has no comments — keep notes in the guides. The fully-populated production template (auth, secrets, routing, scheduler, OTEL/Langfuse, A2A, sampling) lives in docs/examples/config.json.

For comprehensive definitions and capabilities of specific variables, see the Configuration Guide and Local Secret Storage Guide. The authoritative per-flag inventory and audit (every KG_*/GRAPH_*/EPISTEMIC_* flag, its default, and whether it should exist at all) is docs/architecture/configuration.md.

Install via pip:

pip install agent-utilities

To install with all optional dependencies (including MCP servers, UI, and external graph backends):

pip install "agent-utilities[all]"

For more details, see the Installation Guide.

Out of the box, agent-utilities runs as a single self-contained install with no external service dependencies (no database or graph server to stand up; Python package dependencies still apply). The default knowledge-graph backend is tiered — the always-included Rust-native epistemic_graph (L1) in front of an embedded LadybugDB (L2). No Postgres/Neo4j server is required to get started.

To use a durable PostgreSQL tier in production, just set a DSN — the tiered L2 auto-switches to Postgres (your existing configuration keeps working unchanged):

export GRAPH_BACKEND=tiered
export GRAPH_DB_URI=postgresql://agent:agent@localhost:5432/agent_kg

Full deployment instructions — running graph-os and mcp-multiplexer as standard stdio or streamable-http servers, the centralized REST API gateway, Docker composes, and production hardening — are in the Deployment Guide. The flagship Deployment Configurations guide walks every shape from the zero-infra laptop default to a sharded, queue-driven, policy-governed fleet (STATE_DB_URI, GRAPH_SERVICE_ENDPOINTS, TASK_QUEUE_BACKEND, AGENT_DISPATCH_BACKEND, GATEWAY_WORKERS).

Already deployed and want to turn the enterprise/autonomy capabilities on? They ship off-by-default so the laptop experience stays zero-infra. The Enterprise Enablement Runbook is the ordered push → deploy → flag-enablement sequence (security → state → sharding → brain → autonomy), each stage independently reversible and verified.

Serving thousands of tenants over streamable-HTTP? The Multi-Tenant graph-os architecture covers hierarchical org→user isolation, private-by-default sharing with explicit commons/markings promotion, full tenant-stamped audit, and the elastic per-tenant engine pool — with ready-to-edit k8s and Swarm manifests in deploy/.

You can quickly launch the graph-os MCP server (a thin FastMCP wrapper):

uv run graph-os                       # stdio (default)
uv run graph-os --transport streamable-http --host 0.0.0.0 --port 8004

Or start the standalone agent from your code:

from agent_utilities.core.config import config
from agent_utilities.agent.factory import create_agent

# Configuration is automatically loaded from config.json
agent = create_agent(name="MyAgent")
response = agent.run_sync("Analyze the knowledge graph for recent updates.")
print(response.data)

For a comprehensive walkthrough, see the Quick Start Guide.

For detailed tutorials, installation options, and configuration guides, refer to the docs/guides/ directory:

• Quick Start
• Installation Guide
  • Bare-metal, pip packages, Docker
• Deployment Guide
  • Zero-infra default, graph-os & multiplexer (stdio/streamable-http), API gateway, production hardening
• Configuration & Environment Variables
  • Multi-tiered LLM setup, Models Config; the per-flag audit lives in docs/architecture/configuration.md
• Local Secret Storage (Vault & SQLite)
• Creating an Agent
• Building MCP Servers & API Wrappers
• API Documentation & Swagger

Comprehensive system documentation is available in the docs/ directory:

New to the project? Start with the Concept Overview Map to get oriented.

Contributions are welcome. Please follow these guidelines:

1. Fork the repository and create a feature branch.
2. Write tests for new functionality — all tests must include assertions.
3. Follow existing patterns — use the established Pydantic models, structured prompts, and concept markers.
4. Run the test suite before submitting: uv run pytest tests/ -q.

   Note: All tests are strictly bounded by a 60-second timeout via pytest-timeout. Any test that sleeps or hangs indefinitely will fail automatically. Ensure you don't use time.sleep without bounds.

5. Update documentation in docs/ if your changes affect public APIs.

See AGENTS.md for project-specific conventions and architecture rules.

This project is licensed under the terms specified in the LICENSE file.