Noureddine RAMDI / Cairn: a blackboard-driven state-space search engine with stateless agent workers

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
929 Words
github-stars python blackboard-architecture state-space-search docker multi-agent-systems ai

oritera/Cairn

Cairn tackles problem-solving as a pathfinding exercise in an unknown state space by applying a general-purpose state-space search engine built on a blackboard architecture. Instead of relying on predefined workflows or direct agent communication, Cairn organizes knowledge and tasks around a shared board where stateless workers operate independently but coordinate through this common workspace. This approach enabled Cairn to solve all 54 problems at the Tencent Cloud Hackathon AI Penetration Testing Challenge, outperforming 609 competing teams.

how Cairn structures problem-solving with a blackboard architecture

At its core, Cairn models problem-solving as navigating from an origin state to a goal state through a vast, unknown state space. It uses a classic blackboard architecture composed of just three primitives:

  • Facts: Pieces of knowledge or discovered states in the search space.
  • Intents: Tasks or objectives that the system aims to achieve next.
  • Hints: Guidance or heuristics that influence search direction.

These primitives populate a shared blackboard, a global data structure that all worker agents access asynchronously. Instead of explicit messaging or direct inter-agent communication, Cairn relies on stigmergy — indirect coordination through changes to the shared blackboard.

The worker agents are stateless and run an OODA (Observe-Orient-Decide-Act) loop, continuously reading the current blackboard state, deciding on a task, executing it, and writing back new facts, intents, or hints. Importantly, there is only one worker type capable of handling all task types (Bootstrap, Reason, Explore), which are dynamically generated based on the evolving Fact-Intent graph rather than a fixed workflow.

The architecture’s minimalism stands out: no predefined agent roles, no direct communication channels, and zero reliance on external multiparty coordination protocols. Workers containerized with Docker run independently and communicate solely via the blackboard.

what distinguishes Cairn’s design: stateless OODA loop workers and stigmergy coordination

Cairn’s primary technical strength lies in using stateless agents that operate exclusively via a shared blackboard, a design that differs from most multi-agent or AI systems that rely on direct message passing or complex orchestration frameworks.

This choice has several tradeoffs:

  • Simplicity and scalability: Agents don’t maintain internal state or sessions, which simplifies deployment and failure recovery. Scaling is a matter of running more worker containers that read/write to the blackboard.

  • Reduced coupling: Since agents never communicate directly, the system avoids tight coupling and race conditions that plague complex agent coordination.

  • Dynamic task creation: Tasks emerge from the evolving graph of facts and intents, allowing flexible problem-solving strategies instead of rigid pipelines.

  • Limitations: The blackboard can become a bottleneck or synchronization point under heavy load, and designing efficient heuristics for hint propagation is critical for performance.

The codebase is Python-based, and the design favors clarity and modularity. Docker containerization of workers ensures environment consistency and isolation.

The fact that Cairn was the only team to solve all 54 problems at a high-profile AI penetration testing hackathon among more than 600 teams validates this architectural approach in a challenging real-world scenario.

quick start with Cairn using Docker Compose

The repository provides a straightforward Docker Compose setup to get Cairn running. Here are the exact steps from the repo:

# Pull required images

docker pull --platform=linux/amd64 ghcr.io/oritera/cairn-worker-container:latest

# Pull the base image used to build Cairn

docker pull ghcr.io/astral-sh/uv:python3.13-trixie

# Edit dispatch.yaml to fill in your LLM endpoints and API keys, then start services

docker compose up --build

This starts the cairn-server on port 8000 and the cairn-dispatcher after the server passes health checks. The dispatcher mounts dispatch.yaml from the project root and connects to Docker via the host socket. Data persists in ./datas/cairn/.

The setup requires macOS or Linux, Python 3.12 or higher, and Docker installed.

verdict: a robust platform for scalable, stateless multi-agent problem solving

Cairn offers an elegant and minimal architecture for tackling complex search and reasoning problems with multiple stateless worker agents coordinating via a shared blackboard. Its success at a competitive AI challenge shows this approach can handle real-world complexity without brittle orchestration.

This repo is relevant if you need a general-purpose, extensible state-space search engine that avoids complex agent coordination protocols and predefined workflows. The stateless OODA loop worker design and stigmergy-based communication provide a solid foundation for scalable distributed problem solving.

That said, Cairn’s architecture relies heavily on the blackboard as a synchronization point, which could limit throughput in some scenarios. Also, mastering the hint and intent design patterns is crucial to get good performance.

In practice, deploying Cairn means embracing containerized workers, Docker Compose orchestration, and configuring LLM endpoints for reasoning tasks. It’s a good fit for researchers and engineers exploring novel multi-agent architectures as well as applied AI teams tackling search-based problem solving in uncertain environments.

→ GitHub Repo: oritera/Cairn ⭐ 1,116 · Python