# Tachikoma — Full Context for LLMs > Your AI agents deserve real infrastructure. Everyone's building agents. Nobody's building the infrastructure they need — permissions, audit trails, shared context, human-in-the-loop. --- ## Overview Tachikoma is a 6-layer framework that gives AI agents the same governance you'd give a new hire. Each layer works independently and composes with others. Start with one agent. Scale to a team. Ship to production. Open source, self-hosted, zero vendor lock-in. --- ## The Enterprise AI Gap Most teams duct-tape 4+ tools to get agents into production. LangChain for orchestration, a separate auth system, manual audit logs, no shared context. The result: agents with god-mode API keys, no audit trail, and compliance nightmares. Sourced stats that frame the problem: - 61% of enterprises have data not AI-ready (Enterprise Knowledge, 2025) - Only 1 in 5 companies has mature agent governance (CSA, 2025) - EU AI Act fines up to 35M EUR or 7% of global revenue (2026) - 3.4x more effective governance with dedicated platforms (Gartner, 2025) - 40% of enterprise apps will feature AI agents by 2026 (Gartner) Tachikoma solves this with 1 framework, 6 layers, every agent action audited. --- ## Layer 1: U&A2CUI SDK — User & Agent to Collaborative UI Users and agents as equal participants in the same collaborative space. Not an agent chatbot bolted onto a UI — a shared workspace where both humans and agents see, act, and react in real-time. Key capabilities: - Users and agents share the same session state via CRDT - Both can trigger UI features, push context, and respond to events - Permission-scoped views — each participant only sees what they're allowed to, automatically - 3 transport modes (Agent SSE, AG-UI, LLM) for zero lock-in - All computation offloaded to backend via StatefulRecord with TypeScript mirrors - The UI doesn't distinguish between a human clicking a button and an agent making a decision — same event model, same reactivity, same audit trail - Mixed collaboration models: 1-1 (agent-user), N-1 (team-agent), N-M (multi-participants) --- ## Layer 2: Progressive Hive Context Protocol A distributed, living graph model for contextual computation. Inject context into a living hive and watch behavior emerge. Agents plug into any loop at runtime — no redeploy, no config change. Key capabilities: - Hives are stream processors — not orchestrators, propagators - Cast injects signals, Gazer observes results - Switch routes conditionally, Dispatch broadcasts in parallel, Route decides with async logic - Agents plug into any loop dynamically — zero restart, zero config - Context Composer with active/passive providers — XML, MCP, filesystem, all uniform - Two modes: to_loop() for continuous stream processing, to_agent() for discrete workflow steps (WOT mode) - Distributed state tables — fast queries without external database, CRDT-ready - TraceContext auto-propagation (W3C, B3, Jaeger) ```python # Hive pipeline with branching hive = Hive(app, name="orders", tracer=tracer) hive.from_topic(orders_topic) .dispatch() .branch(filter=lambda e: e.status == 'new', name='new') .to_loop(intake_handler) .branch(filter=lambda e: e.status == 'done', name='done') .to_agent(archive_agent) .build() ``` --- ## Layer 3: Law&States Machine Agents join your org chart — not just your API. An agent with an API key is a liability. Law&States Machine is the answer. Key capabilities: - StatefulRecord = State Machine + Event Journal — every entity has a state machine with 10 automatic steps per transition - LawMachine: Actor -> Groups -> Roles -> Rules -> Resources with RBAC + ABAC - BorrowACL handles JWT, refresh tokens, 72h invitations, instant revocation (Rust) - Agents as collaborators: identity in UserRegistry, roles, permissions, complete audit trail - Agents borrow human authorizations when they need elevated access — with full traceability, never permanently - Structured EventJournal: who did what, when, with trace_id correlation --- ## Layer 4: Enterprise-Grade Agentic Layer 3 composable sub-layers that build on each other: ### Sub-layer 1: Agent Objects Multi-provider backend abstraction. Same interface for Claude SDK, OpenClaw (local), Z.AI, or any OpenAI-compatible provider. ```python from tachikoma.agent.backends import ClaudeSDKBackend, OpenClawBackend claude = ClaudeSDKBackend(model="claude-sonnet-4-6") openclaw = OpenClawBackend(host="localhost", port=8080) # Both implement AgentBackend: query(), create_session(), send_message() ``` AgentHive for simple multi-agent orchestration (parallel, sequential, vote, first). 4 execution modes: Direct Call, Session-Based, Stream Processing, Ray Distributed. ### Sub-layer 2: RLM — Recursive Living Context 3-phase iteration cycles: ANALYZE -> EXECUTE -> ENRICH. Each pass enriches the context for the next. The system detects convergence and stops automatically. - ANALYZE phase: Explorer (peek), Searcher (grep), Aggregator (summarize) — work ON the context - EXECUTE phase: Consumer (task execute), Producer (enrich), Validator (quality gate) — work WITH the context - ENRICH phase: Coordinator integrates enrichments, creates new context version - Dual-Layer ChatContext: raw messages + RLM snapshots with conversational time travel - StateSync via Yjs CRDT for real-time context sharing between agents ### Sub-layer 3: WOT — Workflow of Thought Directed graph where each agent step has a clear objective and typed data flows between them. ```python review = Hive(app, name="code-review", type="wot", will="Review code for quality and security vulnerabilities") review.from_input() .to_agent(analyst, name="analyst") .will({"findings": "findings", "summary": "summary"}) .to_agent(security, name="security") .cast("human_review", prompt="Review findings", timeout=120.0) .will({"findings": "findings", "vulnerabilities": "vulns"}) .to_agent(scorer, name="scorer") .feedback({"feedback": "summary"}, max_iterations=3, convergence_threshold=0.05) .to_output() .build() result = await review.ask({"diff": pr_diff}) ``` - Will Global = workflow-level objective (drives convergence/fork decisions) - Will Local = typed data mapping between agent steps - Will Composition = sub-WOT's Will Global collapses to parent's Will Local (fractal composition) - WOT Debugger: breakpoints, step-into subgraph, inspect inputs/outputs, modify inputs, multi-user debug, history replay - ComponentTemplate: reusable, versionable agent templates with ComponentRegistry (filesystem discovery, semantic search, cluster sync) - Lobby System: mixed human-agent collaboration spaces with WOT orchestration --- ## Layer 5: Dynamic MCP Mesh Enterprise MCP with ACL-driven dynamic tool exposure. Key capabilities: - Per-token ACL: each user and agent has their own MCP token from their ACL profile - integration.xml defines 3 modes per capability: on (full access), off (hidden), borrow (agent can USE a secret via tool call but can NEVER READ the actual value) - Users and agents create groups, roles, and integration profiles through ACL-gated operations — each profile generates a dedicated MCP token - Hot-reload: permissions change -> tool lists update live in <5s, zero restart - MCPRegistry: distributed catalog with health checks, version tracking, semantic discovery via Graphiti - SessionBridge: per-token scoping with dynamic FastAPI routers - ComposedTool: chain MCP calls into Hive-backed workflows with human approval gates - Full audit: every call traced in ClickHouse with permission mode (on/borrow/denied) - Agents are first-class accounts with their own profiles — same system as users ```python # Per-token MCP mcp_token = await mcp_auth.create_token(profile=alice_dev_profile) bridge = await SessionBridge.from_token(mcp_token) tools = await bridge.list_tools() # Only tools authorized by Alice's profile ``` --- ## Layer 6: Omnirepo Your enterprise as a living context graph — the digital twin of your organizational knowledge. Key capabilities: - 28+ XML entity types: User, Agent, Computer, Service, Credential, Secret, Flow, Action, Task, Template, Space, Galaxy, System, and more - Galaxy -> System -> Space hierarchy mirrors org chart with config inheritance - Event-driven sync pipeline: XML -> DomainEvents -> StatefulRecords -> automatic Unix provisioning - 50+ event types covering full entity lifecycle - Agents get Unix accounts like employees — same ACL, same SSH keys, same permissions - Lazy sync: context synchronized only where participants are active - Secrets vault: encrypted in XML, decrypted only in isolated subprocess, injected as env vars, output sanitized - CRDT-based real-time collaborative editing of shared entities - Everything versioned in git, everything traced in ClickHouse - MANIFEST.xml as single source of truth, compiled to hierarchy.json for fast lookups ```xml ``` --- ## Use Cases ### Security Audit Before: 3 weeks, 5 tools, manual reports, no audit trail. After: 3 RLM cycles, 5 agents, WOT workflow with human approval gates, every step in ClickHouse. Result: Audit-grade report in hours, not weeks. ### Code Review Pipeline Before: One reviewer, manual checklist, missed edge cases, no security scan. After: Analyst, security scanner, scorer orchestrated in a WOT graph. Cast pauses for human approval on critical findings. Result: Comprehensive review with zero blind spots. ### Multi-Agent Data Pipeline Before: 200 lines of boilerplate, new topics, new consumers, manual tracing. 2 sprints. After: 3 branches in a Hive dispatch. Each agent plugs in at runtime. Auto-tracing via ClickHouse. Result: From 2 sprints to 2 hours. ### AI Governance & Compliance Before: No audit trail, agents with god-mode API keys, manual compliance reports. After: Law&States Machine enforces every action. BorrowACL traces permissions. Every agent action in ClickHouse. Result: Compliance-ready from day one. --- ## Compliance SOC 2 Ready, GDPR Compliant, HIPAA Audit Trail, ISO 27001. --- ## Technical Stack - Runtime: Kafka (event streaming), ClickHouse (tracing), Ray (distributed compute) - Auth: BorrowACL (Rust), LawMachine (RBAC+ABAC), JWT tokens - State: StatefulRecord (state machines + event journal), Yjs CRDT - Knowledge: Graphiti + Neo4j (persistent memory), semantic search - Frontend: React, Tailwind, Radix UI, Motion (animations) - Protocols: W3C Trace Context, B3, Jaeger, MCP (Model Context Protocol) - Declarative: XML entities, MANIFEST.xml, hierarchy.json - CLI: mise tasks for build/deploy/expose ## Links - Docs: https://holichrys.github.io/tachikoma - GitHub: https://github.com/HoliChrys/tachikoma