Sessions and Automatic Memory

Advanced Runtime workflow. Use Cloud MCP for durable memory, context, knowledge bases, files, and workspace governance. Install the standalone CLI only when you need local Agent capture, directed Task execution, communication, or endpoint diagnostics.

Sessions record normal Agent work in one auditable timeline. TokST captures a valid user request, the final reply, and useful tool results, then creates a readable session compilation. A session can produce zero or more long-term memories when it contains reusable facts, decisions, preferences, rules, or architecture.

Tasks have their own documentation and workflow. A Session only records work already performed; it can provide context when a user later creates a task.

TokST redacts credentials, private keys, passwords, cookies, sensitive personal data, raw reasoning, and transient tool output before persistence.

When to Use It

Use Sessions to inspect automatic capture, compilation versions, extracted memories, and diagnostics from normal work in Pi, OpenCode, WorkBuddy, Codex, or Claude Code. Typical examples include implementing a feature, investigating an incident, preparing a release, reviewing a contract, or coordinating several Agents.

Use a regular memory for facts and decisions that remain useful across work. The task guide covers directed execution and assignment.

Lifecycle

The explicit Session commands below remain available through the connected CLI Runtime and existing automation integrations. Automatic capture follows the same privacy, evidence, review, and archive rules.

CLI Workflow

Use TOKST_AGENT=1 for Agent runs so output stays structured and the server records the trusted Agent identity attached to the API key.

# 1. Start with the Atlas context needed for this task.
TOKST_AGENT=1 tokst session start \
  --atlas-id <atlas-id> \
  --task "Implement workspace invitation expiry" \
  --idempotency-key invite-expiry-v1 \
  --json

# 2. Capture only a confirmed, reusable conclusion.
TOKST_AGENT=1 tokst session capture \
  --session <ses-id> \
  "Pending invitations expire after the selected duration." \
  --kind decision \
  --title "Invitation expiry rule" \
  --tags workspace,invitations \
  --confidence 0.95 \
  --source-event-id issue-482-decision \
  --json

# 3. Checkpoint before a handoff or a long pause.
TOKST_AGENT=1 tokst session checkpoint \
  --session <ses-id> \
  "Migration and API are complete; finish dashboard validation next." \
  --json

# 4. Finalize the work. Candidates become formal memories by default.
TOKST_AGENT=1 tokst session finalize \
  --session <ses-id> \
  "Completed the expiry workflow and recorded the validation follow-up." \
  --json

Useful follow-up commands:

# Read one session with candidates, checkpoints, snapshot, and scoped context.
tokst session status <ses-id> --json

# List your sessions in the selected workspace.
tokst session list --workspace <workspace-id> --status active --json

# Owner/Admin: inspect the whole workspace, including archived sessions.
tokst session list --workspace <workspace-id> --scope managed --archived --json

# Read the workspace review queue before opening an individual Session.
tokst session candidates --workspace <workspace-id> --scope managed --status pending --json

# Owner/Admin: govern a candidate after review.
tokst session candidate --session <ses-id> --candidate <candidate-id> --action compile --json
tokst session candidate --session <ses-id> --candidate <candidate-id> --action dismiss --reason "Superseded" --json
tokst session candidate --session <ses-id> --candidate <candidate-id> --action revert --reason "Incorrect decision" --json

# Keep history while removing a finished session from the active list.
tokst session archive <ses-id> --reason "Work complete" --json
tokst session restore <ses-id> --json

Cloud Sessions provide workspace access control, Agent identity, Dashboard governance, and shared audit history. Connected Runtime devices retain an internal encrypted queue for bridge delivery and sanitized recovery; it does not create a separate local memory product.

Automatic Session Capture

Automatic memory runs through a local service. It redacts API keys, tokens, passwords, cookies, and private keys before persistence. TokST Cloud stores sanitized user requests, final Agent replies, and meaningful tool results as Session evidence; it discards raw reasoning, token streams, and sensitive material. One ACP, WorkBuddy, OpenCode, Pi, Codex, or Claude Code session remains one audit container and can contain several automatic compilations. Each completed unit keeps its request and final result; the compiler extracts zero or more reusable durable memories from that material.

Every automatic Session records its source, native or ACP session ID, last event, compiler state, automatic-compilation versions, and linked durable memories. A session-boundary capture creates a draft only when it has both a valid user request and final result. Generic lifecycle events remain in the activity and diagnostic trail. The Sessions page separates work Sessions from diagnostics and lets a user create a formal task from a published compilation.

TokST asks the connected Agent to compile each completed task in a private ACP compiler session. The compiler keeps confirmed facts, table rows, numeric values, paths, commands, URLs, statuses, decisions, and next actions from that task. It removes duplicate prose, raw reasoning, token streams, HTTP or quota errors, and repetitive tool metadata. Session detail shows preserved evidence, automatic-compilation versions, and the durable memories extracted from each version. The linked memories remain reversible from Session detail.

# Start once, then point an ACP client at the TokST proxy command.
tokst start
tokst status

# The ACP client launches this command in place of its normal Agent command.
tokst acp proxy -- <acp-agent-command> [args]

# OpenCode has a native ACP server. Configure the ACP host to run this command.
tokst acp opencode

# Default: raw content is discarded after local redaction.
tokst auto privacy --retain-raw 0
# Optional local recovery window.
tokst auto privacy --retain-raw 24h

Native bridges and ACP

ACP-compatible clients connect through the local Runtime. Run tokst start to connect the device, then run tokst auto on --agent all to install and enable WorkBuddy, OpenCode, Pi, Codex, and Claude Code bridges. Restart the selected client once after installation. WorkBuddy observes its Harness lifecycle; OpenCode uses its global plugin in Terminal and the macOS App; Pi uses a global extension; Codex and Claude Code use managed Hook entries that coexist with user Hooks. Each enabled bridge keeps the native conversation as one Session audit trail, writes an automatic compilation for each completed unit, and extracts reusable durable memories when present. A resumed native session continues its audit trail; a configured ACP compiler performs the structured compilation.

OpenCode terminal and the macOS App load the global plugin from ~/.config/opencode/plugins/tokst-automatic-memory.ts. An external ACP Host uses the same pipeline through tokst acp opencode: the ACP host starts TokST, TokST starts opencode acp, and the original ACP request and response stream remains unchanged. Use tokst status --agent opencode to inspect both native and ACP readiness. tokst auto repair --agent opencode regenerates the global plugin with the current absolute TokST executable path.

tokst auto on --command <acp-agent-command>
tokst acp proxy -- <acp-agent-command> [args]
tokst acp opencode
tokst auto verify --agent all --json

Pi direct sessions use the global bridge. tokst acp pi --doctor reports whether an optional Pi ACP Host adapter is available. Codex and Claude Code compile through their authenticated local clients; Claude Desktop uses Cloud MCP for durable knowledge and does not observe the conversation lifecycle.

Enabling automatic memory installs and starts a user-level service. It uses launchd on macOS, systemd --user on Linux, and a login task on Windows. The service queues sanitized ACP and native bridge events during network interruptions and retries with stable event IDs. tokst status, tokst auto verify, tokst auto repair, and tokst auto logs return the same client status structure.

One native or ACP session maps to one stable TokST Session. Task units within that Session map to automatic-compilation versions and their optional durable memories. tokst status --agent workbuddy and tokst status --agent opencode show the local service, bridge status, route, queue state, and actionable repair guidance. The Dashboard and connected Runtime manage automatic-memory policy; event delivery remains inside the local service.

Connected Runtime

Sessions, Tasks, and Communication use the connected TokST Runtime through authenticated WSS delivery while keeping separate records. Automatic Memory is off by default and is enabled per supported client. Use the Dashboard to inspect, review, archive, and recover those records. Cloud MCP provides durable memory and context for the work.

Tasks

Sessions can provide verified source context to a user-created task. Read the Tasks guide for assignment, execution modes, results, recovery, and task permissions.

Communication records long-lived direct chats and Agent groups without creating Sessions or Tasks. Read Communication for contacts, delivery, streaming replies, and group behavior.

Review and Permissions

The dashboard page is Dashboard → Sessions. It follows the selected workspace and starts with a pending-candidate review queue that shows source Session, confidence, content, and promotion state. Members manage their own candidates; Owners and Admins manage the workspace queue. The Session view also shows status, task, creator, Agent, Atlas, checkpoints, last activity, and snapshot state. Realtime updates refresh the selected workspace only. Use tokst status when automatic memory has not appeared: it reports the local service, ACP connection, routing, and queued events.

Reliable Writes and Quality

• Pass --idempotency-key to session start when a client may retry the request. Repeating the same key returns the existing Session.
• Pass --source-event-id to session capture when a source event can be delivered more than once. Repeating it returns the existing candidate.
• Repeating finalize safely returns the completed result rather than creating competing summaries.
• Use confidence to describe evidence quality. Candidates below 0.6 appear in the low-confidence quality view for manager review.
• Write concrete, independently useful content. A checkpoint should state current progress, blockers, and the next action in a few sentences.

Read the CLI reference for connected Runtime commands. Use Cloud MCP for durable memory and context.