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 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)
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	New task description 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
steer	Redirect a running sub-agent with a new task message

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.

Parameters:

Parameter	Type	Required	Description
manage_action	string	Yes	One of stats, browse, delete, flush, export
tenant_id	string	No	Tenant scope filter
agent_id	string	No	Agent scope filter
ids	string[]	For delete	Memory entry IDs to delete
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.

Related

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