Skip to content
Zooid

Sessions and Threads

In Zooid, a single Matrix thread maps directly to an ongoing ACP session. Every continuous conversation you have with an agent occurs within a thread.

This is a departure from a standard linear chat room. In Zooid, the Matrix thread root serves as the stable identity for an agent’s memory. Every event that belongs to the conversation — the user’s prompt, the agent’s replies, approval cards, and tool-call events — attaches to that thread root.

Creating a Thread

A thread (and therefore a session) is created in one of two ways:

  1. Agent-promotion (Default): You send a regular, top-level message mentioning an agent (e.g., @architect let's build a feature). When the agent replies, it automatically attaches a thread relation referencing your message. Your prompt retroactively becomes the thread root, and all subsequent replies stay in this thread.
  2. User-promotion (Explicit): You click Reply in thread on an existing top-level message in the Zooid web client before the agent replies. The first message sent in that thread mode creates the thread.

Implicit Triggers

In a standard room, agents require an explicit @ mention to respond. However, threads are designed for ongoing collaboration. Zooid implements a thread-aware trigger rule:

  • Once an agent has posted in a thread, or if the agent was explicitly @ mentioned in the thread root, it becomes the implicit addressee.
  • You can simply send a bare reply (e.g., “now do the next file”) in the thread, and the agent will respond without needing to be @ mentioned again.
  • If you @ mention a different agent in the same thread, the new agent will take over the context and become the implicit addressee for future bare replies.

Thread-scoped Clears

Because each thread represents a distinct session, the /clear command is thread-only.

Typing /clear in a thread wipes the agent’s memory for that specific conversation, sending a dev.zooid.session_reset event [ZOD039]. The thread history remains visible in the timeline, but the next message you send will start a fresh session under the same thread. You cannot issue a room-wide /clear to nuke every conversation at once.