| name | session-ops |
| description | Use when the user wants to review past conversations, search session history or memory, check context usage/compression stats, inspect which model/provider a session is using (model resolution chain), inspect session metadata, or configure session settings (switch agent, set timezone). Also use when asking "what model am I using" or debugging model routing. |
Session Operations
CLI commands for inspecting, summarizing, and configuring sessions. All commands output to stdout.
list-sessions
List all sessions with summary status. Filtered by recent activity.
exec: {{WORKSPACE}}/bin/nagobot list-sessions [--days N] [--user-only] [--changed-only] [--fields f1,f2,...]
--days N: Only show sessions active within N days (default: 2)--user-only: Exclude cron:* and :threads: sessions (only real user sessions)--changed-only: Exclude sessions with changed_since_summary=false or message_count=0--fields f1,f2,...: Only include specified fields per session (e.g. key,is_running,has_heartbeat)
Output: JSON with fields per session:
key: Session identifier (e.g. telegram:12345, cli)timezone: IANA timezone if configured (e.g. Asia/Shanghai), empty if not setupdated_at: Last activity timestampmessage_count: Total messages (including tool messages)summary: Current summary text (empty if none)summary_at: When summary was last writtenchanged_since_summary: true if session has new activity since last summaryis_running: Whether the session's thread is currently executing (only populated via RPC)has_heartbeat: Whether the session has a non-empty heartbeat.mdlast_user_active_at: Timestamp of last message from a real user channel (null if no user activity)
Also includes filter, total_sessions, shown_sessions metadata.
read-session
Read filtered chat history with pagination.
exec: {{WORKSPACE}}/bin/nagobot read-session <key> [--offset N] [--limit N] [--tail N] [--full]
<key>: Session key (e.g. cli, telegram:12345)--offset N: Start from Nth filtered message (default: 0)--limit N: Number of messages to return (default: 20)--tail N: Show last N messages (overrides offset)--full: Show full message content without truncation (default: truncated to 500 chars)
Tool messages (role=tool), system messages, and tool-call-only assistant messages are filtered out. Output includes pagination info and a Next: hint when more messages remain.
sample-session
Evenly sample filtered messages across the full conversation.
exec: {{WORKSPACE}}/bin/nagobot sample-session <key> [--count N]
<key>: Session key--count N: Number of messages to sample (default: 20)
Sampling is deterministic (no randomness): messages are picked at evenly spaced intervals. The output header explains the sampling mechanism. Each message shows its original position index [N] in the filtered sequence. YAML frontmatter in messages is automatically stripped. After the sampled messages, the last 5 recent messages not already in the sample are appended.
set-summary
Set or update the summary for a session.
exec: {{WORKSPACE}}/bin/nagobot set-summary <key> <summary>
<key>: Session key<summary>: Summary text (≤200 characters recommended)
Writes to system/sessions_summary.json. Automatically cleans up entries with summary_at older than 7 days and reports what was cleaned.
session-stats
Show context usage stats and model resolution chain for a session.
exec: {{WORKSPACE}}/bin/nagobot session-stats <key>
<key>: Session key (e.g. cli, telegram:12345)
Output: JSON with fields:
model_resolution: Full model resolution chain for this session
steps[]: Each step of the resolution chain:
step: Step name (session_agent, agent_specialty, model_routing)lookup: What was queried (e.g. sessionAgents["discord:123"])found: Result (empty string if miss)status: hit or missfallback: Value used on miss (only present when status is miss)
resolved_provider: Final provider name (e.g. openai, openrouter)resolved_model: Final model identifier (e.g. gpt-5.4, minimax/minimax-m3)resolved_context_window: Context window size for the resolved modelis_default: true if no agent-specific routing was found (using global default)
message_count: Total messages in sessionrole_counts: Breakdown by role (user, assistant, tool, system)compressed_messages: Number of messages with Tier 1 compressed contentrole_tokens: Per-role token breakdown (user, assistant, tool) using compressed contentsystem_prompt_tokens: Estimated token count of the system prompt (rebuilt from agent template; approximate because runtime vars like TIME/TOOLS are not injected)raw_tokens: Token estimate using original contentcompressed_tokens: Token estimate using compressed content (what the LLM actually sees)tokens_saved: Difference (raw - compressed)context_window_tokens: Context window size for the resolved model (model-aware, not global default)usage_ratio: compressed_tokens / context_window_tokenswarn_ratio: Configured pressure threshold (default 0.8)pressure_status: ok, warning (≥64% of window), or pressure (≥80% of window)
Use model_resolution to determine the exact model a session is using and debug routing issues. The steps array shows exactly which config entries were consulted and whether each step hit or fell back to a default.
search-memory
Search across all session messages (current + history backups, merged and deduplicated by message ID). Searches original message content for all roles (user, assistant, tool).
exec: {{WORKSPACE}}/bin/nagobot search-memory <keyword1> [keyword2] ... [--days N] [--limit N] [--session <key>]
<keywords>: One or more search keywords (AND logic — all must match). Case-insensitive.--days N: Only search sessions active within N days (default: 30)--limit N: Maximum results to return (default: 20)--session <key>: Limit search to a specific session key--after <date>: Only include messages after this date (YYYY-MM-DD or RFC3339)--before <date>: Only include messages before this date (YYYY-MM-DD or RFC3339)
Output: JSON with fields:
query: Original search queryhits[]: Matching messages, each with session_key, message_id, role, timestamp, snippet, scoretotal: Total matches foundshown: Number returned (capped by limit)scanned: Total messages scanned
Context browse mode
Browse messages around a specific message ID (from search results).
exec: {{WORKSPACE}}/bin/nagobot search-memory --context <message-id> [--window N]
--context <id>: Message ID to center on (session key is derived from the ID)--window N: Number of messages before and after the target (default: 5)
Output: JSON with target_id, session_key, messages[] (each with message_id, role, timestamp, content, is_target), position, total.
Workflow
- Use keyword search to find relevant messages
- Use
--context with a message ID from the results to see surrounding conversation
set-agent
Set or clear the agent for a session.
exec: {{WORKSPACE}}/bin/nagobot set-agent --session <session_key> --agent <agent_name>
Pin a specific provider/model to a session (writes a type:session rule into thread.models):
exec: {{WORKSPACE}}/bin/nagobot set-agent --session <session_key> --provider <provider> --model <model>
Clear the override — both the agent assignment AND the session model rule (revert to default):
exec: {{WORKSPACE}}/bin/nagobot set-agent --session <session_key>
--session: session key (required). Examples: discord:123456, telegram:78910, cli.--agent: agent template name from agents/*.md. Omit or empty to clear the assignment. Writes the session→agent mapping to meta.json.--provider / --model: pin a model to this session. Writes a type:session rule to config.yaml > thread.models — this overrides the agent's specialty routing for this session. No agent file is created.
--agent and --provider/--model are independent and can be combined (session→agent in meta.json + session→model in the rule list). A session model rule has the highest resolution precedence (session > agent > specialty > default).
set-timezone
Set or clear the IANA timezone for a session.
exec: {{WORKSPACE}}/bin/nagobot set-timezone --session <session_key> --timezone <iana_timezone>
Clear the timezone (revert to system default):
exec: {{WORKSPACE}}/bin/nagobot set-timezone --session <session_key>
--session: session key (required). Examples: discord:123456, telegram:78910, cli.--timezone: IANA timezone name. Examples: Asia/Shanghai, America/New_York, Europe/London. Omit or empty to clear.
Note: set-agent and set-timezone changes take effect on the next message in that session. Changes persist across server restarts (saved to config.yaml).
Per-Session Model Switching
When a user asks to use a specific model for a session:
Case 1: User wants to switch to an existing agent — use set-agent --session <key> --agent <name>.
Case 2: User wants a specific provider/model — use set-agent --session <key> --provider <provider> --model <model>. This writes a type:session rule that pins the model for that session only, overriding specialty routing. No agent file is created, no other config touched.
