Conversations, signals, and sessions
For AI Agents: the Markdown version of this page is at https://ankole.agentbull.com/en-US/docs/conversations-signals-sessions/index.md. The documentation index is at https://ankole.agentbull.com/en-US/llms.txt.
Ankole runs Agents for teams and organizations, where work can start from a chat message, a timer, an external event, or a completed background task—and every piece of work needs an accountable Principal and reliable recovery across process restarts.
To keep responsibilities clear, Ankole separates five records across distinct owners: a conversation stores participant messages, a signal admits new work, a session executes that work, AIGateway persists model session state, and Delivery tracks outbound sends to external platforms.
Four design choices
Keep messages and work in separate records
The conversation record holds the messages visible to human and Agent participants, whereas the work log holds model calls and tool results. Each participating Agent in a conversation owns its own Session and model state: all conversation participants can view the work in that Session, and a Session never crosses conversations.
Each Agent has its own Session in a conversation, and its visible output is shared with the conversation participants. Every turn accesses resources as the executing Agent, including interactive, human-woken may_intervene, scheduled and service-triggered turns. Ordinary Agent messages in shared rooms never wake other Agents; instead, explicit Agent-to-Agent delegation uses send_to_agent to open an isolated agent_peer exchange from a personal_assistant to an ai_colleague under the owner’s frozen Human WorkAccess, projecting any colleague Clarify question or ActionCard directly into the origin conversation (zero-hop pass-through) so the human’s answer wakes the colleague directly. Human employment and instruction versions still determine whether delegated work may continue; they do not intersect Human grants with Agent resource access.
Admit every stimulus through Signals
Messages, timers, external events, and task completions all enter through one admission owner in Ankole.Signals, which persists the Signal, removes duplicates, records attribution and authorization, and resolves the target Session.
A Signal may name its target Session directly; otherwise, Ankole selects the target through conversation participation or a Signal Routing Rule. Conversation-host adapters both observe incoming messages and deliver replies, whereas event-source adapters only emit Signals—allowing new event sources to integrate without adding a separate admission mechanism.
Separate scheduled work from the conversation’s session
Each cron schedule runs in its own stable cron:<schedule_id> Session, and each background task likewise runs in its own Session. When either posts its output to a conversation, the conversation’s next turn reads that posted message cleanly without importing the other Session’s internal model calls and tool results.
Keep one owner for model state
AIGateway provides stateful Responses chains and hosted tools for both internal Agents and external API clients: the Session runtime selects inputs, tools, continuation checkpoints, and compaction triggers, while AIGateway stores the model transcript and executes those operations.
An AIGateway conversation represents model session state rather than the shared participant conversation—duplicating Agent transcript history inside the Session runtime would create a second competing model-state store. When a conversation wakes after its upstream prompt cache has cooled with a large context or after a multi-day external IM idle gap (sessions.wake_recycle), Ankole.Sessions rotates onto a fresh AIGateway model conversation seeded with a bounded 8,000-token <wake-briefing> while leaving the shared Ankole.Conversations message stream untouched.
Source-checked comparison
The comparison below references these repository snapshots, verified on 2026-10-14:
| Project | Verified commit |
|---|---|
| deepseek-harness | 571902028a75 |
pi (packages/durable) |
910149912ca2 |
| qm | cf0e475f50c0 |
| Aspect | deepseek-harness | pi durable | qm | Ankole |
|---|---|---|---|---|
| Record model | Append-only SessionEvent log; model history is a projection. Source |
Immutable entries; task and document updates commit atomically. Source | PostgreSQL session_entries; Slack and Web UI project session history. Store, design |
Separate conversation messages and model work log |
| Shared context | Agent/session history with plugin-defined projections. Source | The host defines message types and application policy. Source | History must be visible to every member of the turn’s audience. Source | One session per Agent in a conversation; shared audience, separate model state; authorization per turn |
| Incoming work | Agent input and scheduled follow-ups; a separate webhook runtime. Schedule, webhook | Submissions and a persistent inbox. Source | Crons, webhooks, and loops have separate mechanisms; its SPEC criticizes the separate loop machinery. Source | One durable signal admission contract for every source |
| Time and external triggers | Durable reminders return to the original session. Webhooks lack a queue, retry, replay, and built-in deduplication. Schedule, webhook | The package supplies submission/task APIs; the host supplies external triggers. Source | Each cron fire uses cron:<id>:fire:<hash>. Source |
A stable cron session; durable external signals; results can enter a target conversation |
| External delivery | Reminder delivery stays in the original session. Source | External channels belong to the host application. Source | Persistent delivery records with expiry. Source | Conversation-host adapters; bounded retry; failed, expired, and unknown outcomes |
| Storage and concurrency | Local JSONL backend; one writer per session, protected by an OS lock. Source | Memory, SQLite, JSONL, or Durable Object storage; one owning process, no cross-process locking. Source | PostgreSQL; current code reads and writes session_entries. Source |
PostgreSQL is authoritative; tenant isolation; authorization checked at each execution start |
| Model context | Derived from the session log. Source | Reduced from committed entries. Source | Built from audience-filtered history. Source | Stored and continued by AIGateway; runtime decides inputs |
Note that qm’s SPEC.md still refers to “tape” as a design term while documenting its completed move to session_entries and subsequent database cleanup; the table above reflects qm’s inspected code rather than its earlier dual-write design. Source
Costs and accepted limits
- More concepts and code. Separating conversations, signals, sessions, delivery, and model state requires maintaining distinct subsystem boundaries.
- Two records to inspect. Diagnosing an incident can require reading both the conversation’s messages and the Session’s work log.
- Shared work can surface results to the room. Information retrieved by the executing Agent and included in its reply enters the conversation’s shared context. Available tools come from its tool catalog; operations inside a tool authorize their resources as the Agent. Human instruction validity is checked separately. In comparison, qm filters session history dynamically per audience. qm source
- Heavier infrastructure. Running PostgreSQL transactions and an OTP control plane adds latency and operational overhead compared with a local single-file harness.
- Uncommitted streaming text is ephemeral. If a process crashes mid-stream, uncommitted partial text is discarded; during recovery, the Session Driver may repeat an interrupted model call, reuses committed tool results, and avoids blindly repeating uncertain Worker operations, so external side effects carry no exactly-once guarantee. By contrast,
pi durablepublishes progress only after storage commit. Source - Wire-protocol constraints. Stateful continuations require an upstream or gateway wire format capable of replaying stored response items losslessly.
- One admission contract across every source. Every event producer and channel adapter must conform to
Ankole.Signals. - Cron session history accumulates. Because
cron:<schedule_id>Sessions preserve context across fires, they rely on periodic compaction, whereas qm opens a fresh session on every cron fire. Source
When another approach fits better
- Single developer working locally with one Agent:
deepseek-harnessorpirequires far less deployment setup. - Embedding a resumable Agent loop inside your own app:
pi durableoffers a smaller library-sized boundary. - A Slack-centered team assistant built around a unified session tape:
qmprovides a more direct single-log design.
Read Architecture for the message-to-work flow and Quick start for the canonical terms.