Sessions

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 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 below. For DAG-style multi-agent workflows (debate, vote, refine, map-reduce, etc.), see 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.

session_status -- View current session

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.

sessions_list -- List active sessions

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.

sessions_history -- Browse conversation history

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)

session_search -- Search/browse conversation history

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

sessions_send -- Send a message to another session

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:

session_key: "default:678314278~peer~678314278"
text: "Research the latest quarterly earnings for ACME Corp and summarize."
mode: "wait"

Example — Send a notification:

session_key: "default:ops-bot~peer~ops-bot"
text: "Deployment to staging completed successfully."
mode: "fire-and-forget"

sessions_spawn -- Spawn a sub-agent session

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 for the full pipeline.Example — Spawn a coding agent (sync):

task: "Fix the broken login form validation in src/auth/login.ts"
agent: "coder"

Example — Spawn an async researcher:

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:

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"

subagents -- Manage running sub-agents

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` 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.

Example — Check on sub-agents:

action: list

Example — Steer a running sub-agent:

action: steer
target: "run_researcher_001"
message: "Focus on open-source competitors only, skip proprietary solutions."

pipeline -- multi-agent execution graphs

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.

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.

memory_search -- Search long-term memory

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:

query: "What did the user say about their project deadline?"
limit: 5

memory_get -- Read a memory entry

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)

memory_store -- Store a memory entry

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:

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.

memory_manage -- Admin CRUD

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.

ctx_search -- Search this conversation's compressed history

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)

ctx_inspect -- Inspect a compressed summary's metadata

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

ctx_expand -- Recover a compressed region to its messages

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.

# 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.

# 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 page.

Agent Sessions

How sessions work under the hood

Pipelines

Multi-agent DAG execution — the deep dive on the pipeline tool

Messaging

Send messages across channels

Agent Tools Overview

Master reference table of all tools

Overview

Tool Guides

Platform Actions

Session tools

Session tools

Cross-Agent Coordination

Memory tools — Long-term Memory

Context expansion tools

Sub-Agent Patterns

Delegation

Parallel Work

When to use `sessions_spawn` vs. `pipeline`

Agent Sessions

Pipelines

Messaging

Agent Tools Overview

​Session tools

​Session tools

​Cross-Agent Coordination

​Memory tools — Long-term Memory

​Context expansion tools

​Sub-Agent Patterns

​Delegation

​Parallel Work

​When to use sessions_spawn vs. pipeline

​Related

Agent Sessions

Pipelines

Messaging

Agent Tools Overview

Session tools

Session tools

Cross-Agent Coordination

Memory tools — Long-term Memory

Context expansion tools

Sub-Agent Patterns

Delegation

Parallel Work

When to use `sessions_spawn` vs. `pipeline`

Related