> ## Documentation Index
> Fetch the complete documentation index at: https://comis-feature-matrix-channel.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Sessions
> Manage conversations, spawn sub-agents, send messages between sessions, and access long-term memory
**What it does:** Lets agents inspect or manipulate their own and others' conversations, spawn sub-agents for specialized tasks, route messages between sessions, and reach into long-term memory.
**Who it's for:** Anyone building multi-agent setups, delegating work to specialists, or asking the agent to recall something it learned earlier. For multi-agent execution graphs (DAGs), see the dedicated [Pipelines](/agent-tools/pipelines) page -- this page covers the simpler one-shot delegation primitives.
## Session tools
| Tool | What It Does |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| `session_search` | Search session history by query |
| `session_status` | Get the current session status |
| `sessions_history` | Retrieve session history entries |
| `sessions_list` | List all sessions for the current agent |
| `sessions_send` | Send a message into another session in 3 modes: `fire-and-forget`, `wait`, `ping-pong` |
| `sessions_spawn` | Create a sub-agent session with workspace isolation, artifact references, and an optional objective |
| `subagents` | Manage running sub-agents (`list`, `kill`, `steer`) |
| `memory_get` | Retrieve a memory entry by key |
| `memory_manage` | Create, update, or delete memory entries (admin CRUD: stats, browse, delete, flush, export, pin, unpin) |
| `memory_search` | Semantic search over agent memory (hybrid text + vector similarity) |
| `memory_store` | Store a new memory entry (secret-detection guard applied) |
| `ctx_search` | In-session full-text search over THIS conversation's compressed history (DAG mode) |
| `ctx_inspect` | Inspect a compressed summary's metadata and immediate children (DAG mode) |
| `ctx_expand` | Recover a compressed region back to its underlying messages (DAG mode) |
The `ctx_*` tools are **in-session recovery** over the DAG (LCD) context engine's lossless store -- they are distinct from the cross-session recall tools (`memory_search`, `session_search`). See [Context expansion tools](#context-expansion-tools) below.
For DAG-style multi-agent workflows (debate, vote, refine, map-reduce, etc.), see [Pipelines](/agent-tools/pipelines) -- the `pipeline` tool is the canonical entry point.
### Session tools
The four session tools (`session_search`, `session_status`, `sessions_history`, `sessions_list`) let agents inspect conversations and discover active sessions.
Shows the current session's status including the agent ID, model, token usage, and duration.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ---------------------- |
| (none) | -- | -- | No parameters required |
Returns the current session's metadata.
Lists all active sessions for the current agent, with optional filters by session kind and recency.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | ------- | -------- | ---------------------------------------------------------------------- |
| `kind` | string | No | Filter by session kind: `all` (default), `dm`, `group`, or `sub-agent` |
| `since_minutes` | integer | No | Only sessions active within the last N minutes |
Returns a list of sessions with their session keys, agent assignments, channels, and last activity timestamps.
Retrieves the conversation history for a specific session by session key.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | ------- | -------- | ---------------------------------------------------------------------------------------------- |
| `session_key` | string | Yes | Session key in `tenantId:filename` form. Use `sessions_list` first to discover available keys. |
| `limit` | integer | No | Maximum messages to return (default: 20) |
| `offset` | integer | No | Skip this many messages (default: 0) |
Search across session messages using FTS keywords or boolean expressions.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | ------- | -------- | -------------------------------------------------------------------------------------------- |
| `query` | string | No | Search query -- keywords, phrases, or boolean expressions. Omit for recent-session metadata. |
| `scope` | string | No | Filter by message role: `all` (default), `user`, `assistant`, or `tool` |
| `summarize` | boolean | No | Summarize matched sessions using LLM (default: true when `query` provided) |
| `limit` | integer | No | Maximum results (default: 10, max: 30) |
### Cross-Agent Coordination
Sends a message into another session. This is the primary way agents communicate with each other. The three modes control how the sending agent waits for a response.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | ------- | -------- | ------------------------------------------------------------------------------- |
| `session_key` | string | Yes | Target session key (use `sessions_list` to discover keys) |
| `text` | string | Yes | The message to send |
| `mode` | string | No | How to handle the response: `fire-and-forget` (default), `wait`, or `ping-pong` |
| `timeout_ms` | integer | No | Wait timeout in ms (for `wait` and `ping-pong` modes) |
| `max_turns` | integer | No | Maximum ping-pong turns 0-5 (for `ping-pong` mode) |
**Modes explained:**
| Mode | Behavior |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `fire-and-forget` | Send the message and continue immediately. Do not wait for a response. Best for notifications and one-way updates. |
| `wait` | Send the message and wait for the target agent to finish processing. Returns the full response. Best for delegation. |
| `ping-pong` | Send the message and receive a conversational exchange. The agents go back and forth until the target completes. Best for collaborative tasks. |
**Example -- Delegate a task and wait:**
```yaml theme={null}
session_key: "default:678314278~peer~678314278"
text: "Research the latest quarterly earnings for ACME Corp and summarize."
mode: "wait"
```
**Example -- Send a notification:**
```yaml theme={null}
session_key: "default:ops-bot~peer~ops-bot"
text: "Deployment to staging completed successfully."
mode: "fire-and-forget"
```
Creates a new sub-agent session with structured context. The spawned agent runs in an isolated workspace with its own conversation history and receives a context packet containing the task, artifact references, domain knowledge, and an optional objective that survives compaction.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------------ | ----------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `task` | string | Yes | Task description for the sub-agent |
| `agent` | string | No | Target agent ID for cross-agent spawning (defaults to the current agent) |
| `async` | boolean | No | Spawn asynchronously, returns `runId` immediately (default: `false` -- waits for result) |
| `model` | string | No | Model override for the sub-agent |
| `artifact_refs` | string\[] | No | File paths for the sub-agent to reference in its workspace |
| `tool_groups` | string\[] | No | Tool group names for sub-agent tool filtering (e.g., `"coding"`, `"web"`) |
| `objective` | string | No | Objective statement that survives context compaction |
| `include_parent_history` | `"none"` or `"summary"` | No | Include a condensed summary of the parent conversation (default: `"none"`) |
| `domain_knowledge` | string\[] | No | Domain knowledge entries to pass to the sub-agent |
| `expected_outputs` | string\[] | No | File paths to validate after sub-agent execution completes |
| `max_steps` | integer | No | Maximum execution steps (floor of 30, default 50, capped at config default) |
| `announce_channel_type` | string | No | Channel type for result announcement |
| `announce_channel_id` | string | No | Channel ID for result announcement |
When `async` is `false` (the default), the parent agent blocks until the sub-agent completes and returns its result. When `async` is `true`, the sub-agent runs in the background and the parent continues working. Use `subagents` to check on background sub-agents.
Sub-agent results are automatically condensed (if over the token threshold) and formatted with metadata tags before being returned to the parent. See [Subagent Context Lifecycle](/agents/subagent-lifecycle) for the full pipeline.
**Example -- Spawn a coding agent (sync):**
```yaml theme={null}
task: "Fix the broken login form validation in src/auth/login.ts"
agent: "coder"
```
**Example -- Spawn an async researcher:**
```yaml theme={null}
task: "Find the top 10 competitors in the AI agent space and write a comparison."
agent: "researcher"
async: true
```
**Example -- Spawn with artifacts and objective:**
```yaml theme={null}
task: "Refactor the authentication module to use JWT"
agent: "coder"
artifact_refs: ["src/auth/login.ts", "src/auth/middleware.ts"]
objective: "Modernize auth to use stateless JWT tokens"
```
Manages sub-agents that were spawned with `sessions_spawn`. You can list running sub-agents, terminate them, or steer them with a new task.
**Parameters:**
| Parameter | Type | Required | Description |
| ---------------- | ------- | -------------- | ------------------------------------------------------------- |
| `action` | string | No | One of `list` (default), `kill`, `steer` |
| `target` | string | For kill/steer | Run ID of the target subagent |
| `message` | string | For steer | The steering message for the subagent |
| `recent_minutes` | integer | No | Include runs from the last N minutes (default 30, for `list`) |
**Actions:**
| Action | What It Does |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list` | Show all running sub-agents with their status and progress |
| `kill` | Terminate a sub-agent by its run ID (discards its in-flight work) |
| `steer` | Redirect a running sub-agent with a steering message. By default this kills the child and respawns it with the message as the new task; when [`security.agentToAgent.steerInject`](/reference/config-yaml#security) is enabled it instead **injects** the message into the running child at its next step boundary, preserving its transcript and progress. A steer never widens the child's tool set -- a denied tool stays denied. See [Steering a running sub-agent](/agents/subagent-lifecycle#steering-a-running-sub-agent). |
**Example -- Check on sub-agents:**
```yaml theme={null}
action: list
```
**Example -- Steer a running sub-agent:**
```yaml theme={null}
action: steer
target: "run_researcher_001"
message: "Focus on open-source competitors only, skip proprietary solutions."
```
For DAG-style multi-agent workflows -- parallel research, debate, vote, sequential refinement, map-reduce, and human approval gates -- use the dedicated `pipeline` tool. It has its own page with the full schema, the 7 built-in node type drivers, and worked examples.
See [Pipelines](/agent-tools/pipelines).
## Memory tools -- Long-term Memory
Agents have access to long-term memory that persists across conversations. Four dedicated tools cover the full memory lifecycle: `memory_search` for hybrid text and vector search, `memory_get` for reading entries by path, `memory_store` for persisting new information, and `memory_manage` for admin CRUD operations. Memory uses hybrid text and vector search, so agents can find relevant information even when the wording differs from the original.
Searches the agent's long-term memory using hybrid text and vector similarity. Returns matching memory entries ranked by relevance.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | --------------------------------------------- |
| `query` | string | Yes | The search text (natural language works best) |
| `limit` | integer | No | Maximum results to return (default: 10) |
Returns matching entries with their paths, content previews, and relevance scores.
**Example:**
```yaml theme={null}
query: "What did the user say about their project deadline?"
limit: 5
```
Reads memory file sections by path, with an optional line range.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | ------- | -------- | ------------------------------------------- |
| `path` | string | Yes | File path relative to the agent's workspace |
| `start_line` | integer | No | Start line (1-based) |
| `end_line` | integer | No | End line (1-based) |
Explicitly stores information in the agent's long-term memory. While Comis automatically stores important information from conversations, this lets agents deliberately save specific facts, preferences, or notes.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | --------- | -------- | -------------------------------- |
| `content` | string | Yes | The information to remember |
| `tags` | string\[] | No | Optional tags for categorization |
**Example:**
```yaml theme={null}
content: "User prefers weekly reports delivered on Monday mornings."
tags: ["preferences", "reporting"]
```
Comis has built-in secret detection. Attempting to store API keys, passwords, tokens, or other secrets will be blocked automatically. This protects against accidental credential leakage into the memory system.
Admin-only memory CRUD operations. Requires admin trust level. The `delete` and `flush` sub-actions require user approval. `pin`/`unpin` mark a single entry as always-injected in recall.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | --------- | ------------- | --------------------------------------------------------------------- |
| `manage_action` | string | Yes | One of `stats`, `browse`, `delete`, `flush`, `export`, `pin`, `unpin` |
| `tenant_id` | string | No | Tenant scope filter |
| `agent_id` | string | No | Agent scope filter |
| `ids` | string\[] | For delete | Memory entry IDs to delete |
| `id` | string | For pin/unpin | Single memory entry ID to pin/unpin |
| `offset` | integer | No | Pagination offset (default: 0) |
| `limit` | integer | No | Maximum results |
| `sort` | string | No | `newest` (default) or `oldest` (for browse) |
| `memory_type` | string | No | Filter by memory type |
| `trust_level` | string | No | Filter by trust level |
| `tags` | string\[] | No | Tag filter |
## Context expansion tools
These three tools recover detail from **the current conversation** when the agent
runs in DAG mode (`contextEngine.version: "dag"`). As a long, tool-heavy session
grows past its token budget, the DAG (LCD) context engine compresses old turns into
a zoomable summary hierarchy. The `ctx_*` tools let the agent zoom back in:
search the compressed history, inspect a summary's coverage, and rehydrate a
compressed region back to its underlying messages.
**In-session, not cross-session.** The `ctx_*` tools operate **only** on the
current conversation's lossless store and share no code with the long-term recall
tools. Use `memory_search` / `session_search` to recall information from *other*
sessions; use `ctx_*` to recover detail the summarizer compressed away *within
this* session. The `ctx_*` tools are **DAG-mode-only** — active by default (DAG is
the default engine) and inactive only in the opt-in `pipeline` mode — **never-export**
(never reachable via the Comis MCP server), and
read-only -- they never reach another session or tenant.
Full-text search over the current conversation's lossless store (compressed
messages and summaries). Uses SQLite FTS5 when available and falls back to a
`LIKE` scan otherwise -- it never hard-fails. Returns matching snippets, which
are treated as untrusted recovered content.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | ------------------------------------------------------------------- |
| `query` | string | Yes | Full-text query over this conversation's compressed history |
| `scope` | string | No | What to search: `messages`, `summaries`, or `both` (default `both`) |
| `limit` | integer | No | Maximum hits to return (default 10, max 30) |
Inspects a single summary in the DAG: its depth, the time range and number of
messages it covers, its token count, and its immediate children. Returns
metadata only (no recovered content), so it is a cheap way to decide which
region is worth expanding.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------------- |
| `summary_id` | string | Yes | The id of the summary to inspect |
Rehydrates a compressed region back to the underlying messages it covers. A
region that partially drifted out of the store is recovered best-effort (the
unrecoverable count is reported -- expansion is never fatal). Large output is
not inlined into the context: it is written to the session's `tool-results/`
directory and returned as a file handle, which you can then open with the file
tools (`read`). Recovered content is treated as untrusted.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | --------------------------------------------------- |
| `summary_id` | string | Yes | The id of the compressed region (summary) to expand |
## Sub-Agent Patterns
Sub-agents are one of the most powerful features in Comis. Here are common patterns for using them effectively:
### Delegation
Spawn a specialist agent for a specific task. For example, a general-purpose assistant can spawn a coding agent to fix a bug, wait for the result, and report back to the user.
```yaml theme={null}
# Parent agent spawns a specialist
task: "Fix the TypeScript compilation error in src/utils/parser.ts"
agent: "coder"
```
### Parallel Work
Spawn multiple sub-agents to work on different parts of a problem simultaneously. Each sub-agent runs independently, and the parent collects results when they finish.
```yaml theme={null}
# Spawn three researchers in parallel (async: true for each)
# Then use subagents list to check progress
# Collect results when all three complete
```
### When to use `sessions_spawn` vs. `pipeline`
| Use this when... | Reach for | Why |
| --------------------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| One specialist needs to run a single task | `sessions_spawn` | Simpler -- no graph definition needed; sub-agent runs in an isolated workspace and returns its result. |
| Several agents need to run in parallel and you want their results collected | `pipeline` (with `barrier_mode: all`) | Pipeline engine handles fan-out, fan-in, dependency ordering, and result interpolation via `{{nodeId.result}}`. |
| You need debate, vote, refine, collaborate, or map-reduce coordination | `pipeline` (with `type_id: debate` / `vote` / etc.) | Built-in node type drivers do the multi-round logic for you. |
| You need a human approval gate mid-flow | `pipeline` (with `type_id: approval-gate`) | The `approval-gate` driver pauses the graph and resumes on the user's decision. |
For all DAG patterns, see the dedicated [Pipelines](/agent-tools/pipelines) page.
## Related
How sessions work under the hood
Multi-agent DAG execution -- the deep dive on the `pipeline` tool
Send messages across channels
Master reference table of all tools