Multi-agent coordination server. Shared infrastructure for AI agents: task board, unified knowledge base, messaging, resource locking, graph edges, and project context — exposed as 71 MCP tools over Streamable HTTP and as a stateless CLI (orchy) for agents without MCP support.

orchy is not an orchestrator. Agents bring the intelligence; orchy provides the coordination layer and enforces the rules.

• Docker (or Podman with podman-compose / docker-compose)
• Rust 1.85+ (for building from source)

git clone https://github.com/aboglioli/orchy.git
cd orchy

docker compose up -d
# or: podman compose up -d

The server binds to http://localhost:4310. Uses PostgreSQL with pgvector. The CLI is available inside the container as orchy:

docker compose exec server orchy bootstrap --json
docker compose exec server orchy task list --json

MCP endpoint:  http://localhost:4310/mcp
Bootstrap:     http://localhost:4310/bootstrap/<project>
REST API:      http://localhost:4310/api/

No database container needed. SQLite works out of the box for single-node usage.

git clone https://github.com/aboglioli/orchy.git
cd orchy

cargo run -p orchy-server

Creates orchy.db in the working directory. The server starts at http://127.0.0.1:4310.

Start PostgreSQL first, then point the server at it:

# Start Postgres (or use compose.yml)
docker compose up -d postgres
# or: podman compose up -d postgres

# Run the server with postgres config
cat > config.toml <<EOF
[server]
host = "127.0.0.1"
port = 4310

[store]
backend = "postgres"

[store.postgres]
url = "postgres://orchy:orchy@localhost:5432/orchy"
EOF

cargo run -p orchy-server

The orchy CLI targets agents without MCP support. Configure once:

# ~/.orchy/config.toml or env vars: ORCHY_URL, ORCHY_API_KEY, ORCHY_PROJECT, ORCHY_ALIAS
cat > ~/.orchy/config.toml <<EOF
url      = "http://localhost:4310"
api_key  = "your-key"
project  = "myproject"
alias    = "coder-1"
EOF

orchy bootstrap              # agent briefing: inbox, tasks, skills, handoff context
orchy task list --json
orchy task claim <id>
orchy knowledge write auth/decision --kind decision --title "..." --content "..."

[server]
host = "127.0.0.1"
port = 4310
heartbeat_timeout_secs = 300

[store]
backend = "sqlite"              # "sqlite" (default), "postgres", or "memory"

[store.sqlite]
path = "orchy.db"

# [store.postgres]
# url = "postgres://orchy:orchy@localhost:5432/orchy"

# [auth]
# jwt_duration_hours = 24
# cookie_secure = false
# bcrypt_cost = 10
# keys_dir = "keys"

# [skills]
# dir = "skills"

# [embeddings]
# provider = "openai"
# [embeddings.openai]
# url = "https://api.openai.com/v1/embeddings"
# model = "text-embedding-3-small"
# dimensions = 1536

Orchy's four main entities — Agents, Tasks, Knowledge, and Messages — are connected through two mechanisms:

1. Direct references (fields on entities) — runtime state, ownership, hierarchy
2. Graph edges (semantic links) — relationships, provenance, dependencies

Task.parent_id, Task.depends_on, and Knowledge.agent_id were migrated to graph edges (spawns, depends_on, owned_by) in Phase 2/3 of the graph rollout. They no longer exist as columns.

Edges model relationships that cross entity boundaries. They are:

• Typed (15 relation types)
• Directed (A → B)
• Traversable (multi-hop graph queries)
• Temporal (point-in-time snapshots)

Resource kinds that can be linked: task, knowledge, agent

Messages cannot be graph nodes — use message threading instead.

Note: assigned_to (task field) is runtime assignment — who is actively working on the task. owned_by edge is semantic ownership — who is responsible for the resource long-term. A task can be assigned_to agent A while owned_by agent B.

The system automatically creates graph edges during these operations:

// Task produces knowledge
write_knowledge(task_id="task-123", ...)     // Task →[produces]→ Knowledge

// Split task into subtasks
split_task(parent_id="task-123", subtasks=[...])   // Parent →[spawns]→ Children

// Delegate subtask (non-blocking)
delegate_task(task_id="task-123", ...)       // Parent →[spawns]→ Subtask

// Replace obsolete task
replace_task(task_id="task-123", replacements=[...])   // Replacement →[supersedes]→ Original

// Merge multiple tasks
merge_tasks(task_ids=["a", "b", "c"], ...)    // Merged ←[merged_from]— Sources

// Add dependency
add_dependency(task_id="task-a", dependency_id="task-b")   // TaskA →[depends_on]→ TaskB

// Create subtask via parent
post_task(parent_id="task-123", ...)         // Parent →[spawns]→ Child

// Create task with dependencies
post_task(depends_on=["task-a", "task-b"], ...)   // Task →[depends_on]→ Deps

Manual edges for semantic relationships not covered above:

// Task implements a plan
add_edge(from_kind="task", from_id="impl-123",
         to_kind="knowledge", to_id="plan-456",
         rel_type="implements")

// Knowledge derived from task
add_edge(from_kind="knowledge", from_id="decision-789",
         to_kind="task", to_id="research-001",
         rel_type="derived_from")

// Resource ownership
add_edge(from_kind="task", from_id="task-123",
         to_kind="agent", to_id="agent-456",
         rel_type="owned_by")

// Evidence chain
add_edge(from_kind="knowledge", from_id="evidence-001",
         to_kind="knowledge", to_id="claim-002",
         rel_type="supported_by")

Knowledge edge resolution: when add_edge references a knowledge entry by path (e.g. from_id="auth/decision"), the server resolves it to the entry's UUID before storing. This guarantees edges survive renames and moves. If the entry doesn't exist yet, the path is stored as-is as a fallback.

Several tools can load referenced resources in a single call:

get_task materialization flags:

get_task(
    task_id: "task-123",
    include_dependencies: true,      // Load full Task objects for depends_on IDs
    include_knowledge: true,         // Load linked knowledge entries
    knowledge_limit: 5,              // Max knowledge entries
    knowledge_kind: "decision",      // Filter by kind
    knowledge_tag: "critical",       // Filter by tag
    knowledge_content_limit: 500     // Truncate content
)

assemble_context — curated context for AI consumption:

assemble_context(kind: "task", id: "task-123", max_tokens: 4000)
// Returns: core_facts, open_dependencies, relevant_decisions, recent_changes, risk_flags

The organization's persistent memory. Agents don't retain state between sessions — every insight, decision, or convention must be written to knowledge or it's gone. Knowledge entries are the org's wiki.

Each entry has a kind, a hierarchical path, title, content, tags, and a version for optimistic concurrency control. Two agents writing the same entry concurrently will get a conflict error on the stale write.

Addressing: entries are looked up by (project, namespace, path). Paths use forward slashes for sub-topics: db-choice, auth/jwt-strategy, api/error-handling. The path is the canonical identifier — write to it to create or update.

Kinds categorize the intent of an entry:

Skills (kind=skill) are inherited through the namespace hierarchy: an agent in /backend/auth sees skills from /, /backend, and /backend/auth. Child namespaces override parent skills with the same path.

Search supports both full-text (FTS) and semantic (embedding-based) queries via search_knowledge. The hybrid scoring blends embedding similarity with keyword overlap and boosts entries linked to the query's anchor resource via the edge graph.

Metadata is a free-form HashMap<String, String> attached to any entry. Useful for tagging structured facts (e.g. {"status": "superseded", "ticket": "ORG-42"}).

The work board. Tasks are the unit of work agents claim and execute.

Pending → Claimed → InProgress → Completed
   │         │          │
   └─────────┴──────────┴──────→ Failed → Cancelled
                                          ↑
                            Blocked ───────┘ (also Pending)

Assignment is exclusive: only one agent holds a task at a time via the assigned_to field. Claiming reserves it; starting moves it to in-progress; completing, failing, or cancelling terminates it.

Stale task reclaim: when an agent disconnects, claimed or in-progress tasks become stale after stale_after_secs of inactivity (no touch_task calls). Other agents can then reclaim them via get_next_task or claim_task — the new claimant takes ownership and the task resets to claimed. Use touch_task to keep long-running work alive.

State machine guards:

• Blocked can only transition to Pending (unblock) or Cancelled
• Pending cannot complete directly — must be claimed and started first (exception: auto_complete for split-task parents)
• Completed, Failed, Cancelled are terminal (archive only)

Ownership (via owned_by edge) is semantic — who is responsible for the resource. This survives task reassignment and persists after completion.

Hierarchy: tasks can have a parent_id. split_task blocks the parent and creates subtasks; the parent auto-completes when all subtasks finish or are cancelled. delegate_task creates a subtask without blocking the parent. Both operations auto-create spawns edges.

Dependencies: depends_on is a list of task IDs that must complete before this task can be claimed. A task with unmet dependencies starts as blocked and unblocks automatically when its last dependency completes. Failed dependencies send a system notification to the waiting task's last assignee. Dependencies are also represented as depends_on edges in the graph.

Priority: low, normal (default), high, critical. get_next_task returns the highest-priority available task matching the agent's roles.

Roles: assigned_roles restricts which agents can claim a task. Empty means any agent can claim it. orchy auto-assigns agent roles from the set of pending role requirements on startup.

Tags are free-form labels for grouping and filtering.

Real-time communication between agents — the coordination bus.

Messages are immutable once sent. You reply to a message (creating a thread), but you cannot edit or delete one.

Addressing modes:

Role, namespace, user, and broadcast messages support optional claim/unclaim semantics — claimed messages are hidden from sibling inboxes.

Threading: any message can set reply_to pointing at another message ID. list_conversation walks the full chain up and down from any message in the thread.

Delivery tracking: messages start as pending, move to delivered when the recipient polls their mailbox, and to read when explicitly marked. For role and broadcast messages, each recipient is tracked independently via message_receipts. check_sent_messages shows per-message delivery status.

System messages: orchy itself sends messages to agent mailboxes for dependency failure notifications. Agents should poll check_mailbox regularly or use poll_updates to catch these.

Note: Messages are not part of the graph edge system. Use message centeric tools (send_message, check_mailbox, list_conversation) instead.

1. register_agent(alias, project, description) — roles auto-assigned from task demand. Org derived from API key.
2. get_agent_context — everything in one call: agent info, project, inbox, pending tasks, skills, handoff context
3. get_next_task — claim (claim: true, default) or peek (claim: false) the next available task matching your roles
4. heartbeat every ~30s; on timeout: agent becomes stale, tasks become reclaimable, locks freed
5. Disconnect recovery: when an agent disconnects, its claimed/in-progress tasks go stale after stale_after_secs. Other agents reclaim them via get_next_task. touch_task prevents staleness for long-running work.

TTL-based locking for any named resource. Auto-expires and cleaned up on agent disconnect.

Projects can link to other projects to share knowledge entries.

Every state change is recorded as a semantic domain event. Query with poll_updates.

Graph operations are available under /graph/ for REST clients and the CLI. Org is derived from the API key (Bearer token).

POST   /graph/edges                    add_edge
DELETE /graph/edges/{edge_id}          remove_edge
GET    /graph/relations                query_relations (query params: anchor_kind, anchor_id, rel_types, direction, max_depth, as_of)
GET    /graph/edges                    list edges (admin/debug)
POST   /graph/context                  assemble_context

GET /tasks/{id}, GET /knowledge/{*path}, and GET /agents/{id} also accept rel_types, direction, and max_depth query params to inline an EntityNeighborhood in the response without a separate call.

orchy is a stateless CLI client targeting agents without MCP support (e.g. pi coding agent, Codex). Every invocation is a single REST request — no session, no heartbeat required.

Config resolution (lowest → highest priority):

1. ~/.orchy/config.toml — global defaults
2. .orchy.toml — repo-local config (walked up from cwd, like mise)
3. Env vars: ORCHY_URL, ORCHY_API_KEY, ORCHY_PROJECT, ORCHY_NAMESPACE, ORCHY_ALIAS
4. Per-call flags: --url, --api-key, --project, --namespace, --agent

Output: text by default, --json on every command for machine-parseable output.

Key commands:

orchy bootstrap --json          # full agent briefing (inbox, tasks, skills, handoff)
orchy task list --json
orchy task claim <id>
orchy task complete <id> --summary "..."
orchy knowledge write <path> --kind decision --title "..." --content "..."
orchy knowledge read <path> --json
orchy message send --to broadcast --body "..."
orchy edge add --from-kind task --from-id <id> --to-kind knowledge --to-id <id> --rel-type produces
orchy edge query --anchor-kind task --anchor-id <id> --json
orchy lock acquire myfile.rs --ttl 120

# Namespace-aware operations (global flag, place before subcommand)
orchy --namespace /backend task create --title "Backend task" --description "..."
orchy --namespace /backend knowledge write config/db --kind config --title "DB" --content "..."
orchy agent switch <alias> --namespace /backend/auth     # jump between namespaces
orchy message send --to ns:/backend --body "..."       # send to namespace

Full command reference: orchy --help / orchy <domain> --help.

Authoritative definitions: crates/orchy-server/src/mcp/tools/ and crates/orchy-server/src/mcp/params.rs. A running server exposes the current set via MCP list_tools.

Session — yes means call register_agent first. no — callable without registration. partial — list_agents only: pass project, or register to use the session project.

Tools that do not require registration: register_agent, session_status, list_knowledge_types, and list_agents when project is passed.

Register as an agent. Required before almost every other tool. Identity is alias-based — re-registering with the same (org, project, alias) resumes the existing agent. Org is derived from the API key. Roles are auto-assigned from pending task demand if omitted.

Check whether this MCP session is bound to an orchy agent, and how to resume after an orchy or MCP transport restart. Does not require registration. Call after the client has reconnected (new MCP initialize) if tools failed with session errors or you are unsure whether you still need register_agent.

Get everything you need in one call: your agent info, project metadata, inbox messages, pending tasks matching your roles, skills, and handoff context from previous sessions. Call this after register_agent to bootstrap quickly. No parameters — uses the session agent.

At least one of project or namespace is required. Switching projects releases claimed tasks and locks in the old project.

Create a task. Use split_task for subtasks with hierarchy, add_dependency for dependencies, or delegate_task for non-blocking subtasks.

Create a subtask under a claimed/in-progress task without blocking the parent. Unlike split_task, the parent keeps its status. Creates spawns edge.

Split a task into subtasks. The parent task is blocked and will auto-complete when all subtasks finish. Agents should work on subtasks directly, not the parent. Creates spawns edges from parent to each subtask.

Cancel a task and create replacements that inherit the original's parent (if any). Creates supersedes edges from each replacement to the original task.

Merge multiple tasks into one. Source tasks must be pending, blocked, or claimed. They are cancelled and a new consolidated task is created with the highest priority, combined roles, combined dependencies, and collected notes. Creates merged_from edges from new task to each source.

Get the next available task matching your roles. When claim is true (default), claims the task and returns full context. When false, returns the top candidate without claiming (peek). Skips tasks with incomplete dependencies.

Get a task by ID with full context (ancestors + children). Can materialize referenced dependencies and linked knowledge entries.

Merge or remove knowledge entry metadata without changing title, content, or kind.

Change the kind of an existing knowledge entry. Does not run on write_knowledge updates — use this tool explicitly. Bumps version when the kind actually changes.

Traverse the edge graph from a root resource and assemble a rich structured context object: the root node's content, linked tasks with acceptance criteria and status, linked knowledge entries (truncated to budget), and the raw edge list. Useful for giving an agent the full picture of a task or knowledge cluster without manual graph traversal.

Typed directed edges between resources. Use the graph to model relationships between tasks, knowledge entries, and agents: what a task produced, which knowledge entry supersedes another, which task spawned which agent.

Relationship types: derived_from, produces, supersedes, merged_from, summarizes, implements, spawns, related_to, depends_on, invalidates, confirms, supported_by, contradicted_by, owned_by, reviewed_by.

Resource kinds (source/target): task, knowledge, agent. (message is not allowed as an edge endpoint.)

Edges can have a valid_until expiry (set internally for TTL-based edges) and are soft-deleted. Historical state is queryable via as_of.

These operations automatically create edges:

Traverse the graph from an anchor resource and return an EntityNeighborhood with inlined peer data (no separate fetches needed).

Acquire a named distributed lock. Fails if held by another agent. Locks auto-expire after ttl_secs (default 300).

Build and test commands via just:

just              # list all recipes
just build        # cargo build --workspace
just test         # unit tests (no containers)
just lint         # cargo clippy --workspace --all-targets -- -D warnings
just fmt          # cargo fmt --all
just server       # cargo run -p orchy-server
just cli -- --help

# Integration tests (testcontainers, requires Docker/Podman)
just it-pg          # PostgreSQL store tests
just it-conformance # store conformance suite
just it-sqs         # SQS event backend
just it-kafka       # Kafka event backend
just it             # all of the above

# Single test by pattern
just t pg_reader_streaming

The justfile auto-sets DOCKER_HOST for rootless Podman and disables Ryuk. Override DOCKER_HOST if using a different container runtime.

For raw cargo invocations:

export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock
export TESTCONTAINERS_RYUK_DISABLED=true
cargo test -p <crate> --features integration-tests -- --test-threads=1

MIT