Session Memory

Session Memory gives a long-running Agent task a durable, reviewable lifecycle. A session starts with workspace and Atlas context, accumulates confirmed candidate knowledge and checkpoints, then ends with a compact snapshot. The resulting record lets another person or Agent resume the work with its decisions, progress, and next action intact.

TokST stores only content explicitly sent through the Session tools. Keep credentials, private keys, personal data without a clear purpose, raw chain-of-thought, and transient tool output in the active runtime.

When to Use It

Create a Session for work that spans several actions, has a handoff point, or produces decisions worth reviewing later. Typical examples include implementing a feature, investigating an incident, preparing a release, reviewing a contract, or coordinating several Agents.

Use a regular memory for a single durable fact. Use Session Memory when the path to that fact, the current progress, and the review history matter as well.

Lifecycle

Stage	What is recorded	Why it exists
Start	Task, workspace/Atlas scope, and returned context	Establishes the working boundary and avoids rebuilding context manually
Capture	A candidate fact, decision, preference, task, architecture note, or note	Keeps confirmed long-term information separate from raw working material
Checkpoint	A concise progress summary and next action	Makes a handoff or interruption recoverable
Finalize	A final summary and immutable session snapshot	Closes the task with a compact record of what happened
Review	Candidate compilation, dismissal, or rollback	Gives workspace managers control over formal memories
Archive	The session remains searchable for audit but leaves default views	Keeps active workspaces focused without deleting history

finalize compiles pending candidates into formal memories by default. Use --no-compile when a manager should review candidates first. Reverting a compiled candidate archives its linked formal memory and preserves the complete audit chain.

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

The Local runtime uses the same lifecycle with tokst local session ...; it writes Sessions, candidates, checkpoints, snapshots, and compiled memories to the local SQLite database. Cloud sessions add workspace access control, Agent identity, dashboard governance, and shared audit history.

Automatic Session Capture

Mode	Capture source	Suitable for
Assisted	The Agent follows Session tools in its Skill or MCP instructions	Every MCP and REST client
Automatic memory	TokST collects a connected ACP session or a native client bridge	ACP clients, WorkBuddy, OpenCode, Pi, Codex, and Claude Code

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 task memories. Each completed task produces one formal Markdown memory; follow-up work on the same task updates its existing memory.

Every automatic Session records its source, native or ACP session ID, last event, compiler state, and formal-memory link. The Sessions page separates work Sessions from diagnostics and supports archiving the linked memory through the existing reversal flow.

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, errors, decisions, and next actions from that task. It removes duplicate prose, raw reasoning, token streams, and repetitive tool metadata. Session detail shows the preserved event evidence and all task-memory links, while each formal memory remains structured for retrieval. Automatic memories save immediately and remain reversible from the Session detail page.

# Enable once, then point an ACP client at the TokST proxy command.
tokst auto on
tokst auto 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 proxy. tokst auto on --agent all detects and installs WorkBuddy, OpenCode, Pi, Codex, and Claude Code bridges, then starts the user-level service. Restart the 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 bridge keeps the native conversation as one Session audit trail and creates a reversible Markdown memory for each completed task. A resumed native session continues its audit trail; a follow-up updates the matching task memory. 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 auto 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 exposes MCP-assisted Session tools and remains labeled assisted because its desktop extension 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 auto 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 their formal memories. tokst auto status --agent workbuddy and tokst auto status --agent opencode show the local service, bridge status, route, queue state, and actionable repair guidance. The Auto API stores user and workspace policy; event delivery remains inside the local service.

MCP Workflow

Cloud MCP and stdio MCP expose the following Session operations. Local MCP keeps the same deliberate lifecycle and candidate governance; ACP-only resume and automatic-memory reversal stay on the Cloud surface because their audit chain and formal memory live in the shared service.

Tool	Use
`tokst_session_start`	Start a scoped task and retrieve context
`tokst_session_capture`	Add a confirmed candidate with kind, tags, title, confidence, and source event ID
`tokst_session_checkpoint`	Save progress and the next action
`tokst_session_finalize`	Create the final snapshot and optionally compile candidates
`tokst_session_status`	Inspect session state and the resume context
`tokst_session_list`	List personal or managed workspace sessions
`tokst_session_moderate_candidate`	Compile, dismiss, or revert a candidate
`tokst_session_archive`	Archive or restore a session
`tokst_session_reopen`	Cloud/stdio MCP: resume an ACP Session while retaining its automatic memory identity
`tokst_session_revert_automatic_memory`	Cloud/stdio MCP: archive an ACP Session's automatic memory and retain audit history
`tokst_auto_status`	Read automatic-memory policy and local connection state
`tokst_auto_configure`	Enable, pause, or route automatic memory for a workspace or Atlas

Add this operating rule to an Agent's project instructions: start a Session before substantial work, capture only confirmed long-term content, checkpoint before handoff, finalize on completion, and keep secrets and raw reasoning outside TokST. tokst agent listen can receive a workspace handoff in real time; the receiving Agent should resume the supplied Session or create a new Session, then checkpoint after it acknowledges the handoff.

Review and Permissions

Role	Session access
Member	Starts, reads, captures, finalizes, and archives personal Sessions in accessible workspaces
Admin	Reads the managed workspace view and governs all candidate records in that workspace
Owner	Has the same governance access as Admin, including complete workspace audit visibility
System administrator	Uses the separate administrator console for read-only cross-workspace audit

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 auto 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, MCP reference, and REST API reference for interface-specific details.