# TokST full public documentation

# TokST Documentation

Source: https://tokst.com/docs

TokST is a **shared memory and state layer for AI agents**. It gives people, agents, and applications one durable place to record facts, decisions, preferences, tasks, architecture notes, and supporting files.

An agent can retrieve the right project context at the start of a session, add new knowledge while it works, and hand a structured history to the next agent. The same data remains available through the CLI, web dashboard, MCP, and REST API.

## Session Memory

Session Memory keeps a multi-step Agent task recoverable and reviewable. Start a session with scoped Atlas context, capture confirmed long-term knowledge as candidates, checkpoint progress before a handoff, and finalize a compact snapshot when work ends. Owners and Admins can compile, dismiss, or revert candidates from the Sessions console; reverting archives the linked formal memory while retaining the audit trail.

TokST records only the structured information supplied through these calls. Credentials, private data, raw reasoning, and short-lived tool output remain in the active Agent runtime.

Read the complete [Session Memory guide](/docs/sessions) for lifecycle rules, CLI and MCP flows, review permissions, reliable retries, Local behavior, and dashboard governance.

## Why TokST Exists

AI sessions are temporary, while projects continue for weeks or years. Important context often lives across chat histories, local notes, repositories, and individual tools. TokST turns that context into a managed knowledge layer with stable ownership, explicit scope, searchable records, and a reviewable lifecycle.

TokST is designed for workflows such as:

- preserving product and architecture decisions with their rationale
- carrying coding conventions and user preferences across agents
- preparing a focused context snapshot before an agent starts work
- handing completed work, open tasks, and known risks to another agent
- keeping reference documents and files next to the memories they support
- separating personal, project, and team knowledge with clear boundaries

## How Data Is Organized

TokST uses a simple hierarchy so every memory has a clear home.

| Level | Purpose | Example |
|---|---|---|
| **Workspace** | Ownership and access boundary for a person or team | `Platform Team` |
| **Atlas** | Knowledge base for a project, subject, or workflow | `Production Operations` |
| **Memory** | Searchable unit of knowledge with type, tags, source, and lifecycle state | `Friday releases require approval` |
| **Attachment** | File connected to a memory | `architecture-brief.pdf` |

A workspace can contain multiple atlases. Each atlas can define routing keywords, allowing TokST to place new memories in the most relevant knowledge base when an explicit atlas is not supplied.

## What You Can Remember

Every memory has one of six types. Types make context snapshots and filtered searches easier to understand.

| Type | Use it for |
|---|---|
| `fact` | Verified information and stable reference data |
| `decision` | A choice, its rationale, and its consequences |
| `preference` | Personal, team, or project conventions |
| `task` | Open work, follow-ups, and action items |
| `architecture` | System boundaries, components, and technical design |
| `note` | General context that fits outside the other types |

Memories can also include a title, tags, source metadata, timestamps, and attachments. Files uploaded through the web dashboard can be up to 500 MB; remote MCP uploads can be up to 50 MB per file.

## The Memory Workflow

1. **Authenticate** with browser setup, the dashboard, or a `tk_live_...` API key for automation.
2. **Select a workspace and atlas** to define ownership and subject scope.
3. **Remember** a fact, decision, preference, task, architecture record, or note.
4. **Retrieve** relevant knowledge with search or a grouped context snapshot.
5. **Maintain** the record by updating, appending, archiving, restoring, or deleting it.
6. **Continue** in another agent or tool through the same shared state.

The basic CLI loop is intentionally small:

```bash
tokst login
tokst remember "Production releases require approval" --type decision --tags release,policy
tokst search "release approval"
tokst context
```

For an agent, the same loop becomes MCP tools such as `tokst_remember`, `tokst_search`, and `tokst_context`.

## Search and Context

TokST uses **keyword-first search with semantic fallback**. Direct text matches return immediately. When the configured embedding service is available and keywords do not produce a result, TokST searches 1536-dimensional vectors within the authenticated user's accessible scope.

Use search for a specific question. Use a context snapshot to give an agent a compact, grouped view of recent facts, decisions, preferences, tasks, architecture records, and notes before work begins.

## Choose an Interface

All interfaces operate on the same workspaces, atlases, memories, and access rules.

| Interface | Best for | Entry point |
|---|---|---|
| **Web dashboard** | Browsing, editing, account management, and large file uploads | [Open dashboard](https://tokst.com/dashboard) |
| **CLI** | Terminal workflows, scripts, imports, and local agent sessions | `curl -fsSL https://tokst.com/install.sh \| bash` |
| **Remote MCP** | ChatGPT and remote agents that support Streamable HTTP | `https://api.tokst.com/mcp` — 51 tools; set `TOKST_MCP_TOOLSET=core` for 11 core tools |
| **Local MCP** | Desktop clients and local stdio integrations | `bun x -y @tokst/mcp-server` — 51 tools after the installer |
| **REST API** | Product integrations and custom automation | `https://api.tokst.com/v1` — 49 authenticated endpoints |
| **Agent skill** | Teaching an agent the TokST workflow from one public document | `https://tokst.com/skill.md` |

## Security and Data Boundaries

- API keys inherit the account and workspace access available to their owner.
- Memory searches and resource lookups stay within the authenticated user's accessible workspaces.
- API keys should live in environment variables, secret managers, or client configuration.
- Signed attachment download links expire after 15 minutes.
- Archiving keeps a memory recoverable; deletion permanently removes the record and its stored attachment objects.

## Start Here

| Goal | Guide |
|---|---|
| Store your first memory | [Getting Started](/docs/getting-started) |
| Give an AI agent persistent memory | [Agent Setup](/docs/agent-setup) |
| Run and govern durable Agent tasks | [Session Memory guide](/docs/sessions) |
| Understand Agent identity, nicknames, and handoffs | [Agent Identity](/docs/agent-identity) |
| Let an agent self-install via one link | [Skill Guide](/docs/skill) |
| Use TokST from a terminal | [CLI Reference](/docs/cli) |
| Connect ChatGPT, Claude Desktop, Cursor, or Codex | [MCP Server](/docs/mcp) |
| Integrate TokST into an application | [REST API](/docs/rest-api) |
| Understand types, search, and lifecycle | [Memory Management](/docs/memories) |
| Organize knowledge boundaries | [Workspaces](/docs/workspaces) and [Atlases](/docs/atlases) |
| Add supporting files | [File Attachments](/docs/attachments) |
| Manage credentials and quotas | [API Keys](/docs/api-keys) |
| Invite a new user and manage Pro benefits | [Referrals & Benefits](/docs/referrals) |
| Resolve installation, connection, Local, or Agent issues | [Help Center](/help) |
| Review released capabilities | [Version History](/docs/changelog) |

---

# Getting Started

Source: https://tokst.com/docs/getting-started

Get up and running with TokST in under one minute. This guide walks you through installation, authentication, creating your first atlas, and storing a memory.

## Agent Setup (one link — fastest way)

Copy this message and paste it into your AI agent's chat:

```
Read https://tokst.com/skill.md and install TokST memory skill step by step.
Start with: curl -fsSL https://tokst.com/install.sh | bash

The installer keeps an existing TokST connection during CLI upgrades. Browser approval opens only for a first connection or an expired credential.
```

The agent reads the guide, installs the standalone CLI, then follows the matching Skill and MCP configuration. Browser-capable clients complete OAuth authorization; static MCP clients use a dedicated API key. Works with Claude Code, Cursor, Codex, ZCode, and any MCP-compatible agent.

See the full [Agent Setup guide](/docs/agent-setup) for details.

## One-Click Install

The fastest way to install TokST and all prerequisites:

```bash
curl -fsSL https://tokst.com/install.sh | bash
```

This downloads a checksum-verified standalone TokST CLI, opens browser authorization, and leaves the machine ready for `tokst` commands. macOS and Linux installation requires only a Unix terminal and `curl`; Windows uses PowerShell. Supported targets are macOS Apple Silicon, macOS Intel, Linux x64, Linux ARM64, Windows x64, and Windows ARM64. It does not require Bun, Node.js, npm, or a package manager.

Windows PowerShell:

```powershell
irm https://tokst.com/install.ps1 | iex
```

Git Bash on Windows also supports `curl -fsSL https://tokst.com/install.sh | bash`; it detects Windows and hands off to the same PowerShell installer.

Upgrade through the current install channel at any time. Standalone installations download a verified binary; npm and Bun installations update their global package:

```bash
tokst update
tokst version
```

## Browser Authorization

The installer opens TokST in the browser and stores a verified local credential. Verify it at any time:

```bash
tokst doctor
tokst status
```

API keys are intended for CI, servers, and unattended automation. Create and manage them in the [dashboard](https://tokst.com/dashboard/api-keys).

## Connect a Repository and Your Agents

Run this from any directory. TokST writes local instructions for selected agents without overwriting existing files. Atlas creation and directory binding use separate commands.

```bash
tokst init --agents codex,claude,cursor,opencode,pi
tokst doctor
```

Use `tokst init --force` when you intentionally want to refresh generated integration files. `tokst init` works without Git or cloud access. `tokst doctor` checks authentication, optional Git and Atlas binding, and generated agent files.

## Create Your First Atlas

An **Atlas** is a named knowledge base that holds related memories. Create one:

```bash
tokst atlas init --name "MyKnowledge"
tokst atlas bind --atlas-id <id>
```

You can list your atlases to confirm:

```bash
tokst atlas list
```

## Store Your First Memory

Memories are the core unit of information in TokST. Store one:

```bash
tokst remember "Hello TokST!" --type note
```

You can categorize memories by type: `fact`, `decision`, `preference`, `task`, `architecture`, or `note`.

Attach files or images to enrich your memories:

```bash
tokst remember "Meeting notes with diagram" --file diagram.png
```

### Batch Import

Import an entire folder of files as memories — text files are auto-extracted:

```bash
tokst import ./my-docs --dry-run               # preview first
tokst import ./my-docs --type note --tags imported  # import with tags
```

## Search Your Memories

Find memories with keyword or semantic search:

```bash
tokst search "hello"
```

For richer results, use additional filters:

```bash
tokst search "deployment" --type decision --tags production --limit 10
```

## Check Status

View your account and usage details at any time:

```bash
tokst status
```

For machine-readable output (useful for scripting):

```bash
tokst status --json
```

## MCP Server Setup

To connect TokST with AI agents that support the Model Context Protocol (Claude Desktop, Cursor, Codex CLI), add this to your MCP config:

```json
{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp"
    }
  }
}
```

The MCP client opens TokST to complete OAuth authorization and needs no local runtime. See the [MCP Server Reference](/docs/mcp) for configuration details for specific clients.

## Download Attachments

If a memory has file attachments, pull them to your local machine:

```bash
tokst memory download mem_xxxxx                    # all attachments → ~/Downloads
tokst memory download mem_xxxxx --out ./files      # specify output directory
tokst memory download mem_xxxxx --json             # machine-readable output
```

## What's Next?

- Browse the [CLI Reference](/docs/cli) for all available commands
- Learn about [Memory Types](/docs/memories) and when to use each one
- Set up [File Attachments](/docs/attachments) to enrich memories with documents
- Organize your knowledge with [Workspaces](/docs/workspaces) and [Atlases](/docs/atlases)
- Give your AI agent persistent memory via [Agent Setup](#agent-setup-one-link--fastest-way)

---

# CLI Reference

Source: https://tokst.com/docs/cli

The `tokst` CLI is the primary interface for interacting with the TokST memory system. All commands are grouped below by function.

> Many commands accept `--atlas` as shorthand for `--atlas-id`. Pass `--json` to any command for machine-readable output.

For Claude, Pi, Codex, and other command-executing agents, set
`TOKST_AGENT=1` or pass `--agent`. This additive mode uses compact bounded JSON,
hard network deadlines, deterministic stream flushing, and skips interactive
version checks. Add `--full` to receive the complete existing JSON response and
`--stdin` for delayed input pipes.

---

## Authentication

| Command | Description |
|---|---|
| `tokst version [--verbose]` or `tokst --version` | Show the installed version; `--verbose` also shows the active installation channel and executable. |
| `curl -fsSL https://tokst.com/install.sh \| bash` | Install or upgrade the checksum-verified standalone CLI. Existing authorization stays in place. |
| `irm https://tokst.com/install.ps1 \| iex` | Install or upgrade the checksum-verified standalone CLI on Windows PowerShell. |
| `tokst update` | Update through the current install channel: verified standalone binary, npm, or Bun. |
| `tokst login --key <key>` | Authenticate with an API key (`tk_live_xxxx`). Credentials are saved to `~/.tokst/config.json`. |
| `tokst logout` | Clear the stored session credentials. |
| `tokst doctor [--fix-path]` | Check authentication, optional repository and Atlas binding, Agent integration files, and command priority. `--fix-path` prioritizes a standalone CLI in zsh or bash. |

```bash
curl -fsSL https://tokst.com/install.sh | bash
# Windows PowerShell
irm https://tokst.com/install.ps1 | iex
tokst version
tokst update
tokst doctor
tokst login --key tk_live_abc123def456
tokst logout
```

The installer supports macOS Apple Silicon, macOS Intel, Linux x64, Linux ARM64, Windows x64, Windows ARM64, and WSL. It requires only `curl` on macOS/Linux or PowerShell on Windows, verifies SHA-256 before activation, and retains an existing local connection. The Unix executable lives in `~/.local/bin`; Windows uses `%LOCALAPPDATA%\\TokST\\bin`. `tokst update` keeps the active install channel: standalone installations download a verified binary, npm installations run `npm update -g @tokst/cli`, and Bun installations run `bun add -g @tokst/cli@latest`. `setup` is the recommended interactive flow. It opens `tokst.com`, confirms the signed-in account, then returns a one-time credential directly to the waiting CLI. It never selects a workspace or Atlas: choose scope explicitly per command, use `tokst workspace switch` when a terminal needs an active workspace, or bind an Atlas only for a directory that belongs to one project. API-key login remains available for CI, servers, and unattended scripts.

## Help

`tokst --help` shows the daily workflow. Use `tokst memory --help`, `tokst atlas --help`, `tokst workspace --help`, or `tokst agent --help` for a complete command group. `tokst help <group>` provides the same grouped reference.

## Local Agent Setup

Generate local instructions for the agents that work in this directory.

```bash
tokst init --agents codex,claude,cursor,opencode,pi
tokst doctor
```

`tokst init` only writes local Agent instructions and works in any directory. Existing instruction files are preserved; use `--force` to refresh them intentionally. Create an Atlas with `tokst atlas init`, then bind a directory with `tokst atlas bind --atlas-id <id>` when project routing is needed. `tokst doctor` reports authentication, optional repository and Atlas binding, and integration-file checks.

---

## Atlas Management

Atlases are named knowledge bases that hold related memories.

| Command | Description |
|---|---|
| `tokst atlas init --name <name>` | Create a new atlas |
| `tokst atlas bind --atlas-id <id> [--path <path>]` | Bind an existing Atlas to a directory; Git metadata is optional |
| `tokst atlas list` | List all atlases in the active workspace |
| `tokst atlas rename --atlas-id <id> --name <new>` | Rename an atlas |
| `tokst atlas profile --atlas-id <id> --keywords a,b,c` | Set keyword profile for auto-routing |
| `tokst atlas delete --atlas-id <id>` | Delete an atlas and all its memories |

```bash
tokst atlas init --name "Project Alpha"
tokst atlas bind --atlas-id <id>
tokst atlas list
tokst atlas profile --atlas-id <id> --keywords architecture,backend,api
tokst atlas rename --atlas-id <id> --name "Project Alpha v2"
tokst atlas delete --atlas-id <id>
```

---

## Workspace Management

Workspaces group atlases together for organizational separation (e.g., personal vs. team).

| Command | Description |
|---|---|
| `tokst workspace create --name <name>` | Create a new workspace |
| `tokst workspace list` | List all workspaces you belong to |
| `tokst workspace switch <workspace-id>` | Switch the active workspace |
| `tokst workspace members <workspace-id>` | List workspace members and roles |
| `tokst workspace invite <team-workspace-id> <email[,email,...]>` | Invite up to 100 people to a Team workspace; supports `--role` and `--expires-in-days` |

Cloud Team workspace creation uses the account's available Team workspace quota. Request or purchase quota in the dashboard before running `tokst workspace create --name <name> --type team`. Local mode keeps its independent local workspace model.
| `tokst workspace invitations <workspace-id>` | List invitations sent by a workspace |
| `tokst workspace inbox` | List your pending invitations |
| `tokst workspace respond <invitation-id> --accept\|--decline` | Accept or decline an invitation |
| `tokst workspace revoke <invitation-id> --confirm` | Revoke a pending invitation |
| `tokst workspace leave <workspace-id> --confirm` | Leave a workspace |
| `tokst workspace role <workspace-id> <user-id> --role admin\|member --confirm` | Change a member role |
| `tokst workspace remove <workspace-id> <user-id> --confirm` | Remove a member |
| `tokst workspace transfer-owner <workspace-id> <user-id> --confirm` | Transfer workspace ownership |

```bash
tokst workspace create --name "Team Engineering"
tokst workspace list
tokst workspace switch <workspace-id>
tokst workspace invite <workspace-id> alice@example.com,bob@example.com --expires-in-days 7
tokst workspace inbox
```

`tokst workspace list` marks the saved active workspace and prints pending invitations with their accept and decline commands. `tokst workspace switch` saves the selection; subsequent `tokst atlas init` commands create the Atlas in that workspace. Accept an invitation first, then switch to the newly joined workspace.

## Agent Identity and Handoffs

`TOKST_AGENT=1` or `--agent` uses the trusted Agent identity bound to the current API Key. TokST creates a stable `agt_...` code on the first trusted call. `--source` remains a display label.

| Command | Description |
|---|---|
| `tokst agent list [workspace-id]` | List trusted Agents in a workspace |
| `tokst agent listen [--workspace <id>] [--json]` | Keep a real-time Agent event stream open; emits JSON Lines for Agent runtimes |
| `tokst message send "text" --to agt_...` | Send to one or more Agents |
| `tokst message send "text" --broadcast` | Fan out to active workspace Agents |
| `tokst message inbox [--workspace <id>]` | Read all Agent inbox messages, or filter to one workspace |
| `tokst message acknowledge <message-id>` | Acknowledge a message |
| `tokst message close <message-id>` | Close a message |

Direct messages are visible to the sender, recipients, and workspace Owner/Admin. Broadcast messages are visible to workspace members and their Agent recipients.

Run `TOKST_AGENT=1 tokst agent listen --json` as a small sidecar beside a long-running Agent. It reconnects automatically and emits an initial unread-message snapshot after each connection. Call `tokst message acknowledge` only after the Agent accepts the work, then call `tokst message close` after completion.

---

## Memory Operations

The core of TokST — storing, retrieving, and managing memories.

### Remember

Store a new memory. This is the most frequently used command.

```bash
tokst remember "Your content here" --type note
```

Short facts can remain plain text. Use Markdown for decisions, architecture,
meeting notes, and tasks. For long content, pass a Markdown file through stdin:

```bash
tokst remember --type decision --tags api,auth --stdin < decision.md
```

Use headings, lists, task checkboxes, links, tables, and code blocks when they
make a memory easier to review. Keep credentials, private keys, raw reasoning,
and transient tool output outside TokST.

| Option | Description |
|---|---|
| `--type` | Memory type: `fact`, `decision`, `preference`, `task`, `architecture`, `note` (default: `note`) |
| `--tags` | Comma-separated tags for filtering (e.g., `--tags deploy,production`) |
| `--source-type` | Source type: `human`, `agent`, `import`, `system` (default: `human`) |
| `--source` | Source name, such as `codex` or `import` |
| `--atlas` | Target atlas ID (shorthand for `--atlas-id`) |
| `--title` | Optional title for the memory |
| `--file` | Attach one or more files (repeatable: `--file a.png --file b.pdf`) |
| `--evidence` | Evidence URL or source file path |
| `--confidence` | Confidence from `0` to `1` |
| `--valid-until` | ISO expiry date-time for time-bound information |

### List, Get, Update, Append

```bash
tokst memory list                   # List recent memories
tokst memory update <id> --content "Updated content"
tokst memory append <id> --content "Additional information"
```

### Archive, Restore, Delete

Memories follow a lifecycle: active -> archived -> deleted.

```bash
tokst memory archive <id>           # Archive (soft-hide)
tokst memory restore <id>           # Restore from archive
tokst memory delete <id>            # Permanent deletion
```

### Verify and Supersede

Mark a record as verified with its supporting evidence, confidence, and optional expiry. When new information replaces an existing record, preserve the relationship instead of losing the previous decision trail.

```bash
tokst memory verify <id> --evidence https://example.com/source --confidence 0.95
tokst memory verify <id> --valid-until 2027-01-01T00:00:00Z
tokst memory supersede <older-id> <replacement-id>
```

### File Attachments

```bash
tokst memory attach <id> --file document.pdf
tokst memory download <id>                       # Download all attachments to ~/Downloads
tokst memory download <id> --out ./files         # Specify output directory
tokst memory download <id> --attachment-id <aid> # Download a specific attachment
```

---

## Search & Context

```bash
tokst search "keyword query"        # Adaptive auto mode (default)
tokst search "query" --search-mode keyword
tokst search "query" --search-mode semantic
tokst search "query" --search-mode hybrid
tokst search "query" --type fact    # Filter by type
tokst search "query" --tags api     # Filter by tag
tokst search "query" --limit 20     # Limit results (default: 10)
tokst search "query" --json         # Machine-readable output

tokst context                       # Snapshot of active atlas context
tokst context --atlas <id>          # Context for a specific atlas
tokst context --limit 50            # Include up to 50 recent memories
```

`tokst context` returns a formatted summary of recent memories in the active atlas — useful for providing conversation context to AI agents.

`--json` includes `meta.requestedMode`, `meta.resolvedMode`, embedding cache level, and keyword/embedding/vector/total timing. Set `SEARCH_DEFAULT_MODE=keyword` for an immediate keyword-only rollback.

---

## Batch Import

Import files from a folder (or a single file) as memories. Text files are extracted automatically; binary files are uploaded as attachments with the filename as content.

```bash
tokst import ./docs                          # Import all files in a folder
tokst import report.pdf                      # Import a single file
tokst import ./code --type architecture      # Set default memory type
tokst import ./docs --tags imported,docs     # Add tags to all imported memories
tokst import ./large-dir --max 50            # Limit to 50 files
tokst import ./docs --dry-run                # Preview without importing
tokst import ./docs --no-attach              # Text only, skip file uploads
```

**Supported text formats** (auto-extracted): txt, md, json, csv, yaml, xml, html, css, js, ts, tsx, py, go, rs, java, sql, sh, and 15+ more.

**Binary formats** (uploaded as attachment): pdf, png, jpg, docx, xlsx, and all others.

| Option | Description |
|--------|-------------|
| `--type` | Default memory type for all imports (default: `note`) |
| `--tags` | Comma-separated tags added to all imports |
| `--atlas-id` | Target atlas (default: auto-route or first atlas) |
| `--source` | Source name (default: `import`) |
| `--dry-run` | Scan and preview without importing |
| `--max` | Maximum number of files to import |
| `--no-attach` | Create text memories only, skip uploading original files |

---

## Utilities

| Command | Description |
|---|---|
| `tokst status` | Display plan, usage, storage, personal workspace and Atlas quotas, Team workspace quota, and memory stats |
| `tokst status --json` | Same, in JSON format for scripting |
| `tokst migrate` | Migrate data between schemas (admin use) |
| `tokst sync` | Force sync local state with the server |

```bash
tokst status
```

Example output (cloud mode):

```
Mode:     Cloud (Supabase)
Endpoint: https://pdjpdivokmcevxdrvtfb.supabase.co

Plan:        pro    206 / 10,000 calls this month   (2% used, resets Jul 1)
Storage:     673 KB / 10.00 GB   7 files   (0% used)

Quotas:
  Personal workspaces:  2 / 10       8 available
  Personal Atlases:     7 / 200      193 available   (20 per workspace)
  Team workspaces:      3 / 5        2 available to create

Summary:
  Workspaces:  2
  Atlases:     7
  Memories:    248 active

Workspaces:
  kueen
  personal

Atlases:
  TokST             in kueen          43 mem  (fact=13, architecture=18, decision=9, note=3)
  ...
```

The `Plan:`, `Storage:`, and `Quotas:` lines appear only in cloud mode. `--json` adds an `account` block with `plan`, `monthlyLimit`, `periodResetAt`, `usage`, `storage`, and `quota` fields. A quota with no limit is shown as `unlimited`.

---

## Common Options

| Option | Description |
|---|---|
| `--json` | Output results as JSON instead of formatted text |
| `--atlas` | Alias for `--atlas-id`, specifies target atlas |
| `--help` | Show help for any command |
| `--version` | Show CLI version |

All commands support `--help` for detailed usage:

```bash
tokst remember --help
```

## Session Memory

Use Session Memory for a task that spans multiple tool calls or needs a durable handoff.

| Command | Description |
|---|---|
| `tokst session start` | Create a session and return scoped context |
| `tokst session capture` | Save a durable candidate memory |
| `tokst session checkpoint` | Save a compact progress checkpoint |
| `tokst session finalize` | Create a snapshot and compile candidates |
| `tokst session status` | Read session state, candidates, checkpoints, and context |
| `tokst session list` | List your sessions, or the managed workspace view for Owner/Admin |
| `tokst session candidates` | List the workspace candidate review queue |
| `tokst session candidate` | Compile, dismiss, or revert one candidate memory |
| `tokst session archive` | Archive a session while retaining its history |
| `tokst auto on\|off\|status` | Enable, disable, or inspect automatic memory bridges on this device |
| `tokst auto repair --agent <workbuddy\|opencode>` | Repair the selected native bridge and refresh its absolute TokST command path |
| `tokst auto privacy --retain-raw 0\|24h` | Choose immediate local deletion or a 24-hour local recovery window |
| `tokst acp proxy -- <agent-command>` | Transparently connect an ACP Agent through TokST automatic memory |

```bash
TOKST_AGENT=1 tokst session start --atlas-id <atlas-id> --task "Implement session memory" --json
TOKST_AGENT=1 tokst session capture --session <ses-id> "Use idempotency keys" --kind decision --tags api,reliability --json
TOKST_AGENT=1 tokst session checkpoint --session <ses-id> "Server routes complete" --json
TOKST_AGENT=1 tokst session finalize --session <ses-id> "Completed the server routes and contract." --json
```

`session finalize` compiles candidates by default. Add `--no-compile` to retain candidates for review.
Owner and Admin can use `session list --scope managed`, then compile, dismiss, or revert candidates. Reverting archives the formal memory and preserves the audit trail.

### Automatic memory

Automatic memory remains off until enabled once on the device. `tokst auto on` detects WorkBuddy, OpenCode, Pi, Codex, and Claude Code, installs their native bridges, and starts the local service. The OpenCode global plugin loads in both the terminal and macOS App; Pi uses a global extension; Codex and Claude Code use managed Hook entries that preserve existing user Hooks. The ACP Host entrypoint remains available for external ACP clients. TokST removes sensitive data locally and creates one structured memory in a private compiler session.

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

For OpenCode terminal and macOS App, install the global plugin once, then restart OpenCode. The same native session updates one automatic memory when resumed with `opencode -s`:

```bash
tokst auto on --agent opencode
tokst acp opencode --doctor
# OpenCode starts normally; the global plugin is loaded automatically.
# An external ACP Host can use: command=tokst, args=["acp", "opencode"]
```

Use `tokst auto repair --agent <name>` to refresh an installed bridge, `tokst auto off --agent <name>` to remove only that bridge, and `tokst auto logs --agent <name>` for local diagnostics. `tokst acp opencode --repair` retains the ACP Host repair workflow. `tokst acp pi --doctor` reports the direct Pi bridge and optional ACP Host adapter state.

TokST installs its local automatic-memory service after enablement. It queues sanitized events during network interruptions and retries using stable ACP event IDs. Raw content is discarded by default; use `tokst auto privacy --retain-raw 24h` when a short local recovery window is required.

`tokst session list` excludes diagnostics by default. Each completed native or ACP session writes one reversible formal memory only when it contains durable confirmed material. Claude Desktop remains an MCP-assisted integration and uses explicit Session tools.


Read the [Session Memory guide](/docs/sessions) for the complete lifecycle, retry keys, Local workflow, dashboard governance, and MCP mapping.

---

# TokST Local

Source: https://tokst.com/docs/local

TokST Local keeps private memory on the current device with SQLite and FTS5. It runs on macOS, Linux, and Windows through the same CLI, MCP package, npm package, and binary release system used by TokST Cloud.

```sh
tokst setup --local
tokst local remember "Keep this on this Mac" --tags private
tokst local search "private"
tokst local context
```

The installer chooses the platform binary. npm users can keep using `@tokst/cli` and `@tokst/mcp-server`.

Data is stored in the platform application-data directory:

```text
tokst.sqlite
attachments/
backups/
local-profile.json
```

## Files, backups, and MCP

```sh
tokst local remember "Contract" --file ./contract.pdf
tokst local backup create --name before-upgrade
tokst local mcp
```

Configure a local stdio MCP client with:

```json
{
  "mcpServers": {
    "tokst-local": {
      "command": "tokst",
      "args": ["local", "mcp"]
    }
  }
}
```

## Optional cloud sync

Cloud sync remains opt-in and binds one local Atlas to one cloud Atlas:

```sh
tokst login --key tk_live_xxxx
tokst local connect --cloud-atlas-id <cloud-atlas-id>
tokst local sync
```

Sync transfers memory content, metadata, status, and tags. Attachments remain on the current device in this release. Concurrent local and cloud edits are retained as separate conflict memories, so neither edit is overwritten.

---

# TokST Editions

Source: https://tokst.com/docs/editions

TokST runs through one CLI, one MCP package, and one cross-platform release system. Choose Local or a cloud plan based on where memory is stored and how workspaces are shared.

| Edition | Monthly price | Workspaces and Atlases | Monthly calls | Storage |
|---|---:|---|---:|---:|
| Local | Free | One default workspace and Atlas on setup; additional local spaces are unlimited | Local | Local disk |
| Cloud Free | Free | 1 personal workspace, 1 Atlas total | 1,000 | 500 MB |
| Starter | $3.9 | 3 personal workspaces, 5 Atlases per workspace, 15 total | 2,000 | 2 GB |
| Pro | $9.9 | 10 personal workspaces, 20 Atlases per workspace, 200 total | 10,000 | 10 GB |
| Max | $29.9 | Unlimited personal workspaces and Atlases | 50,000 | 100 GB |
| Team | $19 / workspace | 1 subscribed team workspace, 50 Atlases, 3 seats | 20,000 shared | 20 GB shared |
| Enterprise | Contract | Contract capacity | Contract | Contract |

## Local

Local is free on macOS, Linux, and Windows. `tokst setup --local` creates a SQLite profile with a default workspace and Atlas. The same `@tokst/cli` and `@tokst/mcp-server` packages support local mode. Memory, attachments, search indexes, and backups remain on the current device.

## Personal cloud plans

Free, Starter, Pro, and Max manage personal workspaces only. They can join any paid Team workspace through an invitation. Activity in a Team workspace uses that workspace subscription, seat, calls, and storage.

## Team workspace subscriptions

Each Team workspace carries an independent subscription and Billing Owner. A user may belong to any number of Team workspaces. Team starts at $19/month for 3 seats, 20,000 shared calls, 20 GB shared storage, and 50 Atlases. Add-ons are $4/month per seat, $5/month per 50,000 calls, and $5/month per 100 GB.

Team provides Owner, Admin, and Member governance, trusted Agent identity, direct and broadcast Agent messages, and workspace audit. Team setup is assigned by an administrator in the current release; checkout and recurring billing follow in a later billing release.

## Enterprise

Enterprise is annual contract only. It provides custom capacity, organization management, SSO, audit retention, SLA, deployment options, and migration support. Contact sales to provision it.

## Calls and migration

A call is an authenticated CLI, MCP, or REST memory operation, search, context request, attachment upload initialization, Agent message, or workspace write. Login, OAuth, dashboard browsing, and download links are excluded. Calls and files use the target Atlas workspace: personal workspaces consume account quotas and Team workspaces consume shared quotas.

Former user-level Team accounts remain Legacy. Existing Team workspaces retain their 200,000 calls and 500 GB entitlement. Existing resources remain available; new resources follow the current plan limits.

## Local-to-cloud sync

A Local Atlas can be explicitly bound and manually synchronized to a cloud Atlas. Sync transfers memory content, metadata, status, and tags. Attachments stay local, and conflicts preserve both records.

See the [product overview](/pricing).

---

# Memory Management Guide

Source: https://tokst.com/docs/memories

Memories are the fundamental unit of information in TokST. Memories are tagged for filtering, organized within an atlas, and embedded into a 1536-dimensional vector space when the configured embedding provider is available.

## Memory Types

Choose the type that best describes the information you're storing.

| Type | Use Case | Example |
|---|---|---|
| `fact` | Verifiable, objective information | "The API gateway URL is https://api.tokst.com" |
| `decision` | A choice made, with rationale | "Chose Supabase over Firebase for Postgres-native tooling" |
| `preference` | Subjective preference | "Prefer REST over GraphQL for simple CRUD endpoints" |
| `task` | A task, TODO, or action item | "Migrate legacy users to new auth flow by Friday" |
| `architecture` | System design or architectural notes | "Auth flow uses JWT with 1h expiry and auto-refresh" |
| `note` | General information (default) | "Met with the team, discussed Q3 roadmap priorities" |

```bash
tokst remember "The database runs on Supabase Postgres" --type fact
tokst remember "Use Turborepo for monorepo management" --type decision --tags architecture,infra
```

## Write structured Markdown

Plain text works well for short facts. Use Markdown for decisions, architecture,
meeting notes, and tasks so each memory remains easy to scan in the dashboard.

| Type | Suggested sections |
|---|---|
| `fact` | Conclusion, Source, Scope |
| `decision` | Decision, Context, Rationale, Impact |
| `preference` | Preference, When it applies, Avoid |
| `task` | Goal, task checklist, Done when |
| `architecture` | Goal, Components, Data flow, Constraints |
| `note` | Summary, Notes, Next actions |

The dashboard editor offers these templates and Markdown formatting controls.
For long CLI input, keep the content in a Markdown file:

```bash
tokst remember --type decision --tags api,auth --stdin < decision.md
```

Agents capture confirmed durable information in the same structure. Keep
credentials, private keys, raw reasoning, and transient tool output outside
memory records.

## Kind

Every memory includes a `kind` field that describes its derivation:

| Kind | Description |
|---|---|
| `raw` | Directly recorded, original information |
| `summary` | A distilled or condensed version of information |
| `snapshot` | A point-in-time capture of context |

The kind is assigned automatically but can be overridden.

## Source Types

Track where a memory originated:

| Source | Description |
|---|---|
| `human` | Recorded by a person via CLI or dashboard |
| `agent` | Created by an AI agent via MCP |
| `import` | Imported from an external system |
| `system` | Generated by TokST internals (e.g., auto-routing) |

```bash
tokst remember "Auto-scaling group configured for 2-10 instances" --source-type agent --source codex
```

## Tags

Tags are comma-separated labels used for filtering and discovery. Unlike types (which are mutually exclusive), tags are additive — a memory can have many tags.

```bash
tokst remember "Deploy process documented in Notion" --tags deploy,documentation,notion
```

Tags power filtered searches:

```bash
tokst search "deploy" --tags production
tokst search "architecture" --type decision
```

## Search

TokST uses a **keyword-first, semantic-fallback** search pipeline:

1. **Keyword matching** — Traditional text search on memory content
2. **Semantic vector search** — Embedding similarity in 1536-dimensional space

Direct keyword matches return immediately and avoid an embedding round trip. When no keyword result exists, TokST generates a query embedding and runs a 1536-dimensional vector search constrained to the authenticated user and accessible workspaces.

```bash
tokst search "database connection issues"       # Semantic
tokst search "Supabase connection string"       # Keyword match
tokst search "auth" --type architecture         # Filtered
tokst search "api" --limit 20 --json            # With options
```

## Context Snapshots

The `context` command generates a formatted snapshot of recent memories in the active atlas. This is particularly useful for providing conversation context to AI agents.

```bash
tokst context                         # Active atlas
tokst context --atlas <id>            # Specific atlas
tokst context --limit 50              # More memories
```

The output includes memory content, type, tags, and timestamps in a readable format designed to be consumed by both humans and agents.

## Memory Lifecycle

Memories progress through three states:

```
Active  -->  Archived  -->  Deleted
```

| State | Description | Visible in search? | Recoverable? |
|---|---|---|---|
| **Active** | Normal, searchable | Yes | — |
| **Archived** | Soft-hidden, out of default results | No | Yes (`restore`) |
| **Deleted** | Permanently removed | No | No |

```bash
tokst memory archive <id>     # Soft-hide
tokst memory restore <id>     # Bring back
tokst memory delete <id>      # Permanent
```

## Trusted Memory Lifecycle

Use trusted metadata for facts, decisions, and policies that need a clear source or review trail.

| Field | Purpose |
|---|---|
| `evidence` | URL or file path supporting the memory |
| `confidence` | Confidence score from `0` to `1` |
| `validUntil` | Optional ISO date-time after which the record needs review |
| `reviewStatus` | `unreviewed`, `verified`, `needs_review`, or `superseded` |

```bash
tokst memory verify mem_xxx --evidence https://example.com/policy --confidence 0.95
tokst memory verify mem_xxx --valid-until 2027-01-01T00:00:00Z
tokst memory supersede mem_old mem_new
```

Verification preserves the memory and marks it as reviewed. Superseding links an older memory to its replacement and marks the earlier record as `superseded`, keeping historical context available.

## Embedding

When a memory is stored or its content changes, TokST requests an embedding vector. The embedding process:

- Produces a **1536-dimensional vector** when the provider is configured and available
- Runs on the server at write time
- Is transparent — you never interact with vectors directly
- Powers semantic fallback queries

Memory writes remain available when the embedding provider is not configured; keyword search continues to work and semantic fallback becomes available after embeddings are generated.

## File Attachments

Memories can have files attached via the `--file` flag. See the [File Attachments Guide](attachments) for details.

```bash
tokst remember "Sprint planning notes" --file sprint-planning.pdf
tokst memory attach <id> --file diagram.png
```

## Batch Import

Import an entire folder of files as memories. Text files (md, code, json, csv, etc.) are auto-extracted; binary files are uploaded as attachments.

```bash
tokst import ./docs --dry-run                  # preview
tokst import ./docs --type note --tags imported # import
```

See the [CLI Reference](cli#batch-import) for all flags.

## Best Practices

- **Use types consistently** — This makes filtered searches more reliable
- **Tag liberally** — Tags are the primary mechanism for cross-cutting organization
- **Archive, don't delete** — Archived memories can be restored if needed
- **Take context snapshots** — Run `tokst context` before agent sessions to provide background
- **Append to existing memories** — Use `append` instead of creating duplicates when adding related information

---

# Workspaces

Source: https://tokst.com/docs/workspaces

A **Workspace** is a top-level container for atlases. Workspaces provide organizational boundaries — you can have a personal workspace, a team workspace, and separate workspaces for different clients or projects.

## Concept

| Property | Description |
|---|---|
| **Name** | Human-readable label (e.g., "Personal", "Engineering Team") |
| **Type** | Personal (single-user) or Team (multi-user) |
| **Atlases** | All atlases within this workspace |
| **Members** | Users with access (team workspaces only) |

```bash
tokst workspace create --name "Engineering Team"
```

## Default Workspace

When you sign up, TokST creates a **default workspace** named "Personal" (or your account name). This is your active workspace until you create or switch to another.

## Create a Personal Workspace

```bash
tokst workspace create --name "Client Research"
```

The command creates a personal workspace by default. Its workspace limit follows your personal plan.

## Team Workspaces

A Team workspace is provisioned together with its Team subscription. Team members join through an invitation and use the Team workspace's shared seats, calls, storage, and Atlas limit. Workspace type remains fixed after provisioning.

## List Workspaces

```bash
tokst workspace list
```

Shows all workspaces you have access to, with the saved active workspace marked. Pending team invitations also appear here with the exact accept and decline commands; `tokst workspace inbox` shows the same inbox directly.

## Switch Workspace

```bash
tokst workspace switch <workspace-id>
```

Switching workspaces changes which atlases are available. The selection is saved locally, and the next `tokst atlas init` creates an Atlas in that workspace. Accept a pending invitation before switching to its workspace.

## Agent Collaboration

Open **Agents** from the dashboard sidebar. The page always follows the current workspace from the sidebar and shows only that workspace's trusted Agents and persistent handoffs. Each API Key creates a stable `agt_...` identity on its first trusted Agent request.

Use the page to copy an identity code, inspect API Key status and last activity, send a directed handoff to one or more Agents, or broadcast to all active Agents. The inbox updates in real time; acknowledgements and closures remain visible to authorized workspace members.

## Delete a Workspace

Workspace deletion is available through the REST API and remote MCP server:

```bash
curl -X DELETE https://api.tokst.com/v1/workspaces/<workspace-id> \
  -H "Authorization: Bearer $TOKST_API_KEY"
```

Remote MCP clients can call `tokst_workspace_delete` with `workspaceId`. A workspace must be empty before deletion; remove its atlases first. The API returns `409 Conflict` while atlases remain. The CLI does not currently expose workspace deletion.

## Personal vs. Team Workspaces

| Aspect | Personal | Team |
|---|---|---|
| **Members** | Single user | Multiple users |
| **Atlases** | User-created | Shared among members |
| **Visibility** | Private to you | Visible to all members |
| **Use case** | Personal notes, experiments | Project knowledge, team docs |

Team workspaces use role-based access. Read the [Team Collaboration guide](/docs/team-collaboration) before inviting members.

## Best Practices

- **Use workspaces for separation** — Personal experiments belong in a personal workspace, team knowledge in a team workspace
- **Name workspaces clearly** — "Personal", "Team Engineering", "Client A" are self-explanatory
- **One team workspace per team** — Don't create overlapping workspaces for the same group

---

# Team Collaboration

Source: https://tokst.com/docs/team-collaboration

Team workspaces let people and agents use the same long-term memory within a project. Every atlas and memory belongs to one workspace, and the active workspace controls the dashboard scope.

## Create and Switch

Open **Teams** from the dashboard sidebar to request Team workspace quota. Enter the number of independent Team workspaces needed and a short purpose statement. A TokST system administrator reviews the quota request. Approval adds available Team workspace capacity to the account; it does not create a workspace automatically. The request list retains pending, approved, rejected, and cancelled results.

The **Owned teams** section shows total, used, and available workspace quota. Select **Create Team workspace** whenever quota is available. Creation assigns the requester as Owner and Billing Owner, then starts an independent Team subscription. Select the Team workspace from the dashboard workspace switcher for its memories and Atlases. The global Teams page lists every Team the user owns or manages, independent of the currently selected workspace.

## Team management

Each Team workspace has an independent subscription, shared calls, storage, seats, and Atlas limit. The Teams page groups **Owned teams** and **Managed teams** so one account can manage multiple product, engineering, or client Teams from one place. Every Team row shows shared usage, active and archived memories, Atlas count, active Agent count, and its latest audit activity. Owners can open the complete audit record in the Team center. Owners manage billing and plan changes; Admins manage members, invitations, roles, and collaboration from the target Workspace page. Members can create and manage their own memories under the workspace permission rules.

## Roles

| Role | Workspace and members | Memories and atlases |
|---|---|---|
| **Owner** | Edits the workspace, invites members and admins, changes roles, removes members, and transfers ownership | Creates, edits, archives, restores, and deletes all workspace content |
| **Admin** | Invites and removes members; manages ordinary members | Creates, edits, archives, restores, and deletes all workspace content |
| **Member** | Can leave the workspace | Creates content and manages only content they own |

Each atlas inherits its workspace access rules. TokST does not use separate atlas roles in this release.

## Invite Members

Open the current workspace's management page. In **Pending invitations**, enter one or more email addresses separated by commas or new lines, select a role, and choose an expiry period of 1 day, 1 week, or 1 month.

TokST creates one invitation for each email address. The pending list shows the recipient, assigned role, expiry date, and controls to copy or revoke an invitation link. A pending invitation grants no workspace access.

## Accept or Decline

Signed-in recipients see their pending invitations at the top of Workspace management. Selecting **Accept** adds the recipient to the workspace with the assigned role. Selecting **Decline** closes the invitation. Expired, declined, revoked, and accepted invitations no longer grant access.

## Ownership and Departure

An owner can transfer ownership to another member after confirmation. The previous owner becomes an admin. Owners remain in the workspace until ownership has moved to someone else.

Members and admins can leave a workspace. Owners and admins can remove eligible members after confirmation. Removing a member ends their access to shared memories, atlases, and files in that workspace.

## Agent Inbox

Open **Agents** in the dashboard while the target workspace is selected. It contains the workspace-scoped list of trusted `agt_...` identities and its persistent message inbox. Members and Agents can send handoffs; Owner and Admin can view and manage all authorized workspace messages. Direct messages remain visible to their sender, recipients, and Owner/Admin. Broadcast messages fan out to active Agents in that workspace and are visible to workspace members.

The page has **Agent management** and **Communication** sheets. Management shows each stable identity, source-based nickname, API Key state, and activity time; Owner and Admin can correct a nickname for an earlier identity without an associated source record. Communication separates group broadcasts from direct messages and records the sender and recipients on every entry.

## Recommended Workflow

1. Create one team workspace for each product or client.
2. Create atlases for durable domains such as architecture, contracts, operations, or product decisions.
3. Invite people and agents with the smallest role that supports their work.
4. Keep sensitive project facts in the appropriate workspace so switching workspaces keeps context isolated.

---

# Atlases

Source: https://tokst.com/docs/atlases

An **Atlas** is a named knowledge base that holds a collection of related memories. Think of it as a folder or a database for a specific domain. Atlases are grouped within [Workspaces](workspaces).

## Concept

| Property | Description |
|---|---|
| **Name** | Human-readable label (e.g., "Project Alpha", "Personal Notes") |
| **Keywords** | Comma-separated terms used for auto-routing |
| **Workspace** | Parent workspace that contains the atlas |
| **Memories** | All memories stored within this atlas |

```bash
tokst atlas init --name "Project Alpha"
```

## Create an Atlas

```bash
tokst atlas init --name "MyKnowledge"
```

Every atlas starts empty. The newly created atlas becomes your active atlas.

## List Atlases

```bash
tokst atlas list
```

Shows all atlases in the active workspace, with their memory counts and keyword profiles.

## Rename an Atlas

```bash
tokst atlas rename --atlas-id <id> --name "New Atlas Name"
```

Renames the specified atlas.

## Set Keywords for Auto-Routing

Keywords enable **auto-routing** — when you store a memory without specifying an atlas, TokST checks if the memory's content matches any atlas keywords and routes it automatically.

```bash
tokst atlas profile --atlas-id <id> --keywords architecture,backend,api,typescript
```

When you run `tokst remember "The API uses TypeScript with Express"`, TokST matches the content against atlas keywords and routes it to the best-matching atlas.

## Delete an Atlas

```bash
tokst atlas delete --atlas-id <id>
```

**Warning:** This permanently deletes the atlas, all memories within it, and their R2 file objects before database cleanup. This action cannot be undone.

## Auto-Routing in Detail

Auto-routing helps you store memories without manually specifying an atlas every time. Here's how it works:

1. You run `tokst remember "Some content"` (no `--atlas` flag)
2. TokST evaluates the content against keyword profiles of all atlases in the active workspace
3. The atlas with the highest keyword match score receives the memory
4. If no atlas matches above the threshold, the memory goes to the active atlas

This is especially useful for agent-driven workflows where the agent doesn't know which atlas to use — it just remembers, and TokST figures out the placement.

## Best Practices

- **Create one atlas per domain** — Don't mix personal notes with project architecture
- **Set keyword profiles** — They make auto-routing work reliably
- **Name atlases descriptively** — Names like "Frontend" or "Backend" are clearer than "Atlas 1"

---

# MCP Server Reference

Source: https://tokst.com/docs/mcp

The TokST MCP (Model Context Protocol) server lets AI agents interact with your memory system directly. Claude Code, Codex, Pi, WorkBuddy, ZCode, Qoder, Kimi, and other MCP clients can store, search, and manage memories through natural language.

For durable decisions, architecture, meeting notes, and tasks, send structured Markdown in `content`. Use headings, lists, task checkboxes, links, tables, and code blocks when they improve review. Short facts can remain plain text; keep credentials, private keys, raw reasoning, and transient tool output outside memory records.

## Trusted Agent Identity and Messages

Every local or remote MCP request resolves the API Key to a stable `agt_...` identity and refreshes its last active time. `source` on `tokst_remember` remains a human-readable source label. The full toolset includes `tokst_agent_list`, `tokst_message_send`, `tokst_message_inbox`, `tokst_message_acknowledge`, and `tokst_message_close`. Broadcast messages create a receipt for every active Agent in the target workspace.

## Automatic Memory

Automatic memory uses `tokst_auto_status` and `tokst_auto_configure` across remote MCP, stdio MCP, and the local CLI. Native bridges identify their source as `workbuddy`, `opencode`, `pi`, `codex`, or `claude`; ACP uses `acp`. Claude Desktop uses these same MCP Session tools in assisted mode. The local service performs redaction and compiles one revocable memory when a durable task ends.

## Connection Modes

| Mode | Transport | Use Case |
|---|---|---|
| **Remote (Streamable HTTP, 51 tools)** | `https://api.tokst.com/mcp` | ChatGPT, web-based agents, memory and workspace workflows |
| **Remote (SSE compatibility, 51 tools)** | `https://api.tokst.com/sse` | MCP directories and clients that only accept SSE or stdio |
| **Local (stdio, 51 tools)** | `tokst local mcp` | Desktop agents using the standalone installer |

## Local SQLite mode

Run `tokst setup --local` once, then set `TOKST_MODE=local` for `@tokst/mcp-server`. The package delegates to the same local CLI runtime and uses the same tool names and SQLite profile.

```json
{ "mcpServers": { "tokst-local": { "command": "tokst-mcp", "env": { "TOKST_MODE": "local" } } } }
```

## Remote Setup (for ChatGPT & remote agents)

The public MCP manifest is available at [`https://api.tokst.com/.well-known/mcp`](https://api.tokst.com/.well-known/mcp). It advertises the Streamable HTTP endpoint, OAuth metadata, and the API-key path for static clients.

Configure a remote MCP client with the endpoint below. On first connection, the client opens TokST sign-in and approval in the browser. TokST uses OAuth 2.1 authorization-code flow with PKCE and creates a stable trusted Agent identity for the approved client.

```json
{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp"
    }
  }
}
```

The remote endpoint is stateless Streamable HTTP: every request carries authentication and can be served by any healthy instance. It returns JSON tool responses and does not require a persistent MCP session ID.

The authorization server advertises OAuth metadata at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`. Clients that support Dynamic Client Registration can register automatically.

### API Key remote setup

WorkBuddy, ZCode, Qoder, Kimi, CI, and other clients with static MCP settings can connect with a dedicated API key. Create it in [Dashboard API Keys](https://tokst.com/dashboard/api-keys), then use this configuration:

```json
{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp",
      "headers": {
        "Authorization": "Bearer tk_live_your_api_key"
      }
    }
  }
}
```

Create a separate key for each client. Store it in the client's protected environment-variable store, keep it out of source code and version control, and revoke keys that are no longer used.

### SSE compatibility setup

Some MCP directories only offer **SSE** and **stdio**. Select SSE and configure the endpoint below. Add `TOKST_API_KEY` as a private environment variable in the directory; its value is a dedicated `tk_live_...` API key.

```json
{
  "mcpServers": {
    "tokst": {
      "type": "sse",
      "url": "https://api.tokst.com/sse?api_key=${TOKST_API_KEY}"
    }
  }
}
```

TokST validates the opening SSE connection with the API key, then returns a short-lived session endpoint for MCP requests. Use Streamable HTTP for clients that support it.

## Local Setup (for desktop agents)

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tokst": {
      "command": "bun",
      "args": ["x", "-y", "@tokst/mcp-server"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "tokst": {
      "command": "bun",
      "args": ["x", "-y", "@tokst/mcp-server"]
    }
  }
}
```

### Codex CLI

```toml
# ~/.codex/config.toml
[mcp_servers.tokst]
command = "bun"
args = ["x", "-y", "@tokst/mcp-server"]
```

The Cloud MCP endpoint uses browser authorization or a dedicated API key. Local MCP uses the private Local SQLite profile created by `tokst setup --local`. Both expose the complete 57-tool surface, including automatic-memory Session control and normalized event reporting; Cloud also provides workspace governance, Agent collaboration, attachments, and account operations. Set `TOKST_MCP_TOOLSET=core` on a remote deployment only for the focused 11-tool memory surface.

## Tool Reference

Remote and local MCP both expose administrative, team, and attachment tools by default. `TOKST_MCP_TOOLSET=core` limits a remote service to the 11 core memory tools.

### Workspace Governance Tools

These tools use the same role checks as the dashboard. `confirm: true` is required for accepting or declining invitations, revoking invitations, leaving, changing roles, removing members, and transferring ownership.

| Tool | Purpose |
|---|---|
| `tokst_workspace_members` | List members and roles |
| `tokst_workspace_invitations` | List invitations sent from a workspace |
| `tokst_workspace_invite` | Send one or more invitations with role and expiry |
| `tokst_workspace_invitation_inbox` | List invitations for the current user |
| `tokst_workspace_invitation_respond` | Accept or decline an invitation |
| `tokst_workspace_invitation_revoke` | Revoke a pending invitation |
| `tokst_workspace_leave` | Leave a workspace |
| `tokst_workspace_member_role` | Set a member to `admin` or `member` |
| `tokst_workspace_member_remove` | Remove a member |
| `tokst_workspace_owner_transfer` | Transfer Owner to an existing member |

### Memory Operations

#### `tokst_remember`

Store a new memory with auto-routing and embedding generation.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `content` | string | yes | The memory content |
| `type` | string | no | `fact`, `decision`, `preference`, `task`, `architecture`, `note` (default: `note`) |
| `tags` | string | no | Comma-separated tags |
| `source` | string | no | Source name (default: `mcp`) |
| `evidence` | string | no | Evidence URL or source file path |
| `confidence` | number | no | Confidence from 0 to 1 |
| `validUntil` | string | no | ISO expiry date-time |
| `atlasId` | string | no | Target atlas (auto-routes by keyword if omitted) |
| `title` | string | no | Optional title |

#### `tokst_search`

Adaptive scoped search shared with CLI and REST.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Search query |
| `type` | string | no | Filter by type |
| `tags` | string | no | Comma-separated tag filter |
| `atlasId` | string | no | Scope to a specific atlas |
| `mode` | string | no | `auto`, `keyword`, `semantic`, or `hybrid` (default: `auto`) |
| `limit` | number | no | Max results (default: 20) |

The tool result includes the same ordered memories and `meta` timing/cache fields as REST.

#### `tokst_context`

Get a structured context snapshot grouped by memory type.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `atlasId` | string | no | Atlas ID (all if omitted) |
| `limit` | number | no | Max items per type (default: 10) |

#### `tokst_memory_list`

List recent memories.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `type` | string | no | Filter by type |
| `atlasId` | string | no | Scope to atlas |
| `limit` | number | no | Max results (default: 20) |

#### `tokst_memory_get`

Get a single memory with full details and attachments.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID |

#### `tokst_memory_update`

Replace a memory's content.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID |
| `content` | string | yes | New content |

#### `tokst_memory_append`

Append content to an existing memory (adds `\n\n` separator).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID |
| `content` | string | yes | Content to append |

#### `tokst_memory_verify`

Verify a memory with supporting evidence, confidence, and an optional expiry date.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID to verify |
| `evidence` | string | no | Evidence URL or source file path |
| `confidence` | number | no | Confidence from `0` to `1` |
| `validUntil` | string | no | ISO expiry date-time |

#### `tokst_memory_supersede`

Mark an older memory as superseded by a newer record in the same Atlas.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory being superseded |
| `replacementMemoryId` | string | yes | Newer replacement memory |

#### `tokst_memory_archive`

Soft-archive a memory (restorable).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID |

#### `tokst_memory_restore`

Restore an archived memory to active status.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID |

#### `tokst_memory_delete`

Permanently delete a memory.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID |

#### `tokst_attach_file`

Attach one ChatGPT-uploaded file or remote URL to an existing memory. The remote server downloads it and uploads it to R2.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `memoryId` | string | yes | Memory ID |
| `files` | array | no | File supplied by ChatGPT (`openai/fileParams`) |
| `fileUrl` | string | no | Downloadable URL for generic MCP clients |
| `filename` | string | no | Override filename |

Provide either `files` or `fileUrl`. Remote MCP uploads are limited to 50 MB per file.

#### `tokst_download_file`

Get secure download links for one or all attachments on a memory. Links expire after 15 minutes and are also returned as MCP `resource_link` content.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `memoryId` | string | yes | Memory ID |
| `attachmentId` | string | no | Specific attachment; omit for all attachments |

### Atlas Operations

#### `tokst_atlas_list`

List all atlases. No parameters.

#### `tokst_atlas_init`

Create a new atlas (knowledge base).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Atlas name |
| `workspaceId` | string | no | Workspace (uses default if omitted) |
| `keywords` | string | no | Comma-separated keywords for auto-routing |

#### `tokst_atlas_rename`

Rename an atlas.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `atlasId` | string | yes | Atlas ID |
| `name` | string | yes | New name |

#### `tokst_atlas_profile`

Set auto-routing keywords for an atlas.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `atlasId` | string | yes | Atlas ID |
| `keywords` | string | yes | Comma-separated keywords |

#### `tokst_atlas_delete`

Delete an atlas and all its memories.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `atlasId` | string | yes | Atlas ID |

### Workspace Operations

#### `tokst_workspace_list`

List all workspaces. No parameters.

#### `tokst_workspace_create`

Create a new workspace.

Cloud Team workspace creation uses the account's available Team workspace quota. Local MCP continues to use the local workspace model.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Workspace name |

#### `tokst_workspace_delete`

Delete an empty workspace.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | yes | Workspace ID |

### Account

#### `tokst_status`

Get account overview: plan, usage, storage, workspace/atlas counts. No parameters.

## Authentication

- **Remote**: API Key in `Authorization: Bearer tk_live_xxx` header
- **Local**: reads `~/.tokst/config.json` (created by `tokst login --key <key>`)

## Session Memory Protocol

Use Session tools for work that spans multiple actions or needs a durable handoff.

```text
`tokst_session_start` — atlasId, task
`tokst_session_capture` — sessionId, kind, content, tags
`tokst_session_checkpoint` — sessionId, summary
`tokst_session_finalize` — sessionId, summary
`tokst_session_reopen` — sessionId (cloud/stdio ACP only; keeps the same automatic memory)
`tokst_session_revert_automatic_memory` — sessionId, reason (cloud/stdio only; archives the automatic memory and retains audit history)
`tokst_session_status` — sessionId
`tokst_session_list` — workspaceId, scope, atlasId, status
`tokst_session_list_candidates` — workspaceId, scope, atlasId, status
`tokst_session_moderate_candidate` — sessionId, candidateId, action
`tokst_session_archive` — sessionId, archived
```

Session start returns scoped context. Capture stores durable candidates. Finalize writes a snapshot and compiles candidates into formal memories by default.
Workspace owners and admins can review the managed Session view, compile or dismiss candidates, revert compiled candidates, and archive completed work without losing the audit trail.

Read the [Session Memory guide](/docs/sessions) for a full Agent operating flow, handoff rules, review permissions, Local parity, and retry behavior.

---

# REST API Reference

Source: https://tokst.com/docs/rest-api

## Automatic Memory API

| Method | Route | Purpose |
|---|---|---|
| `GET` | `/v1/auto` | Read automatic-memory policy for the selected scope |
| `PUT` | `/v1/auto` | Enable, pause, or route ACP automatic memory |
| `POST` | `/v1/auto/redaction-audits` | Record redaction metadata without source content |
| `POST` | `/v1/sessions/:id/events` | Local ACP and native-bridge event delivery |
| `POST` | `/v1/sessions/:id/compile` | Local ACP service compilation record |

The Auto API stores user and workspace policy. The local ACP service owns event delivery and compilation; application integrations use explicit Session lifecycle endpoints for deliberate task records.

TokST exposes its authenticated REST API at `https://api.tokst.com/v1` plus an unauthenticated health check. The production API uses the same per-user and workspace access rules as the dashboard and remote MCP server.

The machine-readable OpenAPI 3.1 document is available at [`https://api.tokst.com/openapi.json`](https://api.tokst.com/openapi.json). It describes authentication, typed operations, request parameters, and response shapes for programmatic clients.

TokST Local is a private CLI and stdio MCP profile. Local memory stays in SQLite on the current device and does not expose a network REST listener. Use the cloud API for cloud workspaces and Atlases.

Send structured Markdown in a memory `content` field for decisions, architecture,
meeting notes, and tasks. Short facts can remain plain text. Keep credentials,
private keys, raw reasoning, and transient tool output outside memory records.

## Agent Identity and Messages

Send `X-TokST-Actor: agent` with an API Key to use a trusted Agent identity. The server creates or resolves the API-Key-bound `agt_...` identity; client-provided Agent IDs are rejected. `sourceName` remains a source label.

| Endpoint | Description |
|---|---|
| `GET /v1/agents?workspace_id=<uuid>` | List workspace Agents |
| `POST /v1/agent-messages` | Send a direct or broadcast message |
| `GET /v1/agent-messages/inbox` | Read the current Agent inbox |
| `GET /v1/agent-messages/events` | Open the current Agent real-time event stream |
| `POST /v1/agent-messages/:id/acknowledge` | Acknowledge a receipt |
| `POST /v1/agent-messages/:id/close` | Close a receipt |

## Authentication

Send your TokST API key in the `Authorization` header:

```bash
curl https://api.tokst.com/v1/status \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxx"
```

Keep API keys in a secret manager or environment variable. URL query authentication exists only for legacy MCP session compatibility and should not be used for REST requests.

## Referrals and Benefits

| Method | Path | Description |
|---|---|---|
| `GET` | `/v1/referrals/me` | Read the referral code, counts, and masked invitee records |
| `GET` | `/v1/benefits/me` | Read Pro benefit entries with base and effective plans |
| `POST` | `/v1/benefits/:id/activate` | Activate one available Pro benefit |

New account attribution is set only during registration through a referral link. A qualifying memory created through this API, the dashboard, CLI, or MCP activates a verified referral automatically.

## OAuth for Remote MCP

Remote MCP clients use OAuth 2.1 authorization code flow with PKCE. Connect the client to `https://api.tokst.com/mcp`; it discovers `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, opens TokST for account and workspace approval, then stores refreshable bearer credentials. REST automations continue to use an API key.

## Endpoint Inventory

### Health and Account

| Method | Path | Auth | Description |
|---|---|---|---|
| `GET` | `/health` | No | Service health check |
| `GET` | `/v1/status` | Yes | Plan, monthly usage, storage, personal workspace and Atlas quotas, Team workspace quota, and totals |

### Agents and Messages

| Method | Path | Description |
|---|---|---|
| `GET` | `/v1/agents` | List trusted Agents in a workspace; requires `workspace_id` |
| `POST` | `/v1/agent-messages` | Send a direct or broadcast message as the trusted Agent |
| `GET` | `/v1/agent-messages/inbox` | Read the trusted Agent inbox; optionally filter by `workspace_id` |
| `GET` | `/v1/agent-messages/events` | Open the trusted Agent SSE stream; optionally filter the initial unread snapshot by `workspace_id` |
| `POST` | `/v1/agent-messages/:id/acknowledge` | Acknowledge a message receipt |
| `POST` | `/v1/agent-messages/:id/close` | Close a message receipt |

The SSE stream requires `Authorization: Bearer $TOKST_API_KEY` and `X-TokST-Actor: agent`. It sends `ready`, `message.created`, `heartbeat`, and `auth.revoked` events. The CLI manages reconnects and unread-message recovery through `tokst agent listen`.

### Memories

| Method | Path | Description |
|---|---|---|
| `POST` | `/v1/memories` | Create a memory and generate its embedding |
| `GET` | `/v1/memories` | List active memories |
| `GET` | `/v1/memories/context` | Build a grouped context snapshot |
| `POST` | `/v1/memories/search` | Keyword-first search with scoped semantic fallback |
| `GET` | `/v1/memories/:id` | Get one memory, including attachment metadata |
| `PATCH` | `/v1/memories/:id` | Update content, title, type, or tags |
| `POST` | `/v1/memories/:id/verify` | Verify a memory with evidence, confidence, or expiry |
| `POST` | `/v1/memories/:id/supersede` | Mark a memory as replaced by a newer record |
| `POST` | `/v1/memories/:id/archive` | Archive a memory |
| `POST` | `/v1/memories/:id/append` | Append content and regenerate the embedding |
| `POST` | `/v1/memories/:id/restore` | Restore an archived memory |
| `DELETE` | `/v1/memories/:id` | Delete a memory and its R2 objects |

### Atlases

| Method | Path | Description |
|---|---|---|
| `GET` | `/v1/atlases` | List accessible atlases |
| `GET` | `/v1/atlases/:id` | Get one atlas |
| `POST` | `/v1/atlases` | Create an atlas |
| `PATCH` | `/v1/atlases/:id` | Rename an atlas or replace routing keywords |
| `DELETE` | `/v1/atlases/:id` | Delete an atlas, its memories, and their R2 objects |

### Workspaces

| Method | Path | Description |
|---|---|---|
| `GET` | `/v1/workspaces` | List accessible workspaces |
| `GET` | `/v1/workspaces/:id` | Get one workspace |
| `POST` | `/v1/workspaces` | Create a workspace |
| `DELETE` | `/v1/workspaces/:id` | Delete an empty workspace; returns `409` when atlases remain |
| `GET` | `/v1/workspaces/:id/members` | List workspace members and roles |
| `GET` | `/v1/workspaces/:id/invitations` | List sent invitations |
| `POST` | `/v1/workspaces/:id/invitations` | Create one or more invitations; `emails`, `role`, and `expiresInDays` |
| `PATCH` | `/v1/workspaces/:id/members/:userId` | Change a member between `admin` and `member`; body requires `confirm: true` |
| `DELETE` | `/v1/workspaces/:id/members/:userId?confirm=true` | Remove a member |
| `POST` | `/v1/workspaces/:id/leave` | Leave a workspace; body requires `confirm: true` |
| `POST` | `/v1/workspaces/:id/owner-transfer` | Transfer ownership to an existing member; body requires `userId` and `confirm: true` |
| `GET` | `/v1/workspace-invitations` | List the caller's pending invitations |
| `POST` | `/v1/workspace-invitations/:id/respond` | Accept or decline an invitation; body requires `accept` and `confirm: true` |
| `DELETE` | `/v1/workspace-invitations/:id` | Revoke a pending invitation; send `?confirm=true` |

## Memory Requests

### Create

```bash
curl -X POST https://api.tokst.com/v1/memories \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Production deploys require approval on Fridays.",
    "type": "decision",
    "title": "Release policy",
    "tags": ["deploy", "policy"],
    "atlasId": "00000000-0000-0000-0000-000000000000"
  }'
```

`content` is required. `type` defaults to `note`. Supported types are `fact`, `decision`, `preference`, `task`, `architecture`, and `note`. When `workspaceId` is supplied it must match the selected atlas.

### List and Context

```bash
# type accepts one value or a comma-separated list; limit is 1-100
curl "https://api.tokst.com/v1/memories?atlas_id=$ATLAS_ID&type=decision,note&limit=20" \
  -H "Authorization: Bearer $TOKST_API_KEY"

curl "https://api.tokst.com/v1/memories/context?atlas_id=$ATLAS_ID&limit=10" \
  -H "Authorization: Bearer $TOKST_API_KEY"
```

### Search

```bash
curl -X POST https://api.tokst.com/v1/memories/search \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"release approval rules","atlas_id":"'$ATLAS_ID'","mode":"auto","limit":10}'
```

`mode` accepts `auto`, `keyword`, `semantic`, or `hybrid` and defaults to `auto`. The response includes `mode` plus `meta` with the requested/resolved mode, cache level, strong-keyword decision, and stage timings.

- `keyword` returns ranked title/content keyword matches.
- `semantic` returns vector results only.
- `hybrid` always fuses both lists with RRF.
- `keyword_fallback` records a bounded embedding failure while preserving keyword results.

### Update and Append

```bash
curl -X PATCH https://api.tokst.com/v1/memories/mem_xxx \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Updated policy","type":"decision","tags":[]}'

curl -X POST https://api.tokst.com/v1/memories/mem_xxx/append \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Approved by the release manager."}'
```

Sending an empty `tags` array clears existing tags. Content updates and appends regenerate the semantic embedding.

### Verify and Supersede

```bash
curl -X POST https://api.tokst.com/v1/memories/mem_xxx/verify \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"evidence":"https://example.com/policy","confidence":0.95,"validUntil":"2027-01-01T00:00:00Z"}'

curl -X POST https://api.tokst.com/v1/memories/mem_old/supersede \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"replacementMemoryId":"mem_new"}'
```

Verification marks a record as reviewed and stores its supporting metadata. Superseding marks the earlier record as `superseded` and preserves a link to the replacement.

## Atlas and Workspace Requests

```bash
curl -X POST https://api.tokst.com/v1/workspaces \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Platform Team"}'

curl -X POST https://api.tokst.com/v1/atlases \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production","workspaceId":"'$WORKSPACE_ID'","keywords":["deploy","release"]}'
```

Atlas deletion is cascading and also removes attachment objects. Workspace deletion is intentionally non-cascading: delete its atlases first, then delete the empty workspace.

### Team Membership

```bash
# Invite multiple people for seven days.
curl -X POST "https://api.tokst.com/v1/workspaces/$WORKSPACE_ID/invitations" \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["a@example.com","b@example.com"],"role":"member","expiresInDays":7}'

# The recipient accepts an invitation from their own inbox.
curl -X POST "https://api.tokst.com/v1/workspace-invitations/$INVITATION_ID/respond" \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accept":true,"confirm":true}'
```

The database enforces workspace roles for every membership RPC. Owner manages all membership changes and ownership transfer. Admin manages ordinary members. Member can leave and can manage only their own memories.

## File Workflow

File transfers use the unified Supabase Edge Function at `/functions/v1/tokst`. These routes accept the short-lived user JWT returned by `POST /auth/exchange`, while normal REST routes accept `tk_live_...` API keys.

| Method | Edge path | Purpose |
|---|---|---|
| `POST` | `/auth/exchange` | Exchange an API key for a user JWT |
| `POST` | `/storage/upload-url` | Validate ownership and quota, create a pending attachment, return a signed PUT URL |
| `POST` | `/storage/confirm-upload` | Verify the R2 object exists, record actual size and MIME, activate the attachment |
| `GET` | `/storage/download-url` | Return a 15-minute signed download URL |
| `POST` | `/storage/delete-objects` | Server-managed, ownership-checked object cleanup |

The CLI, web dashboard, and MCP tools implement this workflow. See [File Attachments](/docs/attachments) for complete examples.

## Response and Error Model

Successful responses return a typed JSON object documented in the OpenAPI 3.1
contract. Errors use one stable shape:

```json
{
  "error": "quota_exceeded",
  "code": "quota_exceeded",
  "message": "The current monthly quota has been reached. Retry after the reported reset time or upgrade capacity."
}
```

`error` remains available for existing clients. `code` is the canonical
machine-readable value. `message` provides recovery guidance and must not be
parsed for program control.

| Status | Meaning | Common codes |
|---|---|---|
| `400` | Invalid body, query, or resource relationship | `invalid_query`, `atlas_workspace_mismatch` |
| `401` | Missing or invalid API key | `missing_api_key`, `invalid_key` |
| `403` | Revoked key or forbidden object access | `revoked`, `forbidden` |
| `404` | Route or accessible resource was not found | `not_found` |
| `409` | Resource state prevents the operation | `workspace_not_empty`, upload object missing |
| `429` | Monthly quota or rolling rate limit reached | `quota_exceeded`, `rate_limited` |
| `500` | Server-side failure | `internal_error` |

Resource lookups are scoped to the authenticated owner and workspace memberships. A resource outside that scope resolves as unavailable.

## Rate Limit Headers

Authenticated REST responses expose the monthly quota window using standard
headers:

| Header | Meaning |
|---|---|
| `RateLimit-Limit` | Total operations allowed in the current quota window |
| `RateLimit-Remaining` | Operations remaining in the current quota window |
| `RateLimit-Reset` | Seconds until the quota window resets |
| `Retry-After` | Seconds to wait before retrying; returned with HTTP `429` |

Clients should slow or pause work when `RateLimit-Remaining` approaches zero.
After `429`, wait for `Retry-After` before retrying. TokST currently exposes
pull-based REST, MCP, and Session event interfaces; public outbound webhooks
are not available.

## Versioning and Deprecation

TokST keeps stable cloud REST routes under `/v1`. Additive fields, endpoints,
and optional request parameters can ship within `/v1`. A change that removes a
field, changes its meaning, or changes authorization behavior receives a new
major API path.

TokST announces a planned endpoint or field retirement in this reference and
the release history at least 90 days before removal. During the announced
period, affected HTTP responses include `Deprecation: true` and a `Sunset`
date where the route can provide those headers. Clients should treat unknown
response fields as forward-compatible and use `error` codes rather than parsed
error text for recovery logic.

## MCP Endpoint

The same host serves the complete 46-tool MCP Streamable HTTP surface at `https://api.tokst.com/mcp`. See the [MCP reference](/docs/mcp); deployments can set `TOKST_MCP_TOOLSET=core` for the focused 11-tool memory surface.

## Session Memory API

Session Memory creates a durable record for an Agent task. Agent clients send `X-TokST-Actor: agent`; TokST injects the trusted `agt_...` identity.

| Method | Endpoint | Purpose |
|---|---|---|
| `POST` | `/v1/sessions` | Start a session and return scoped context |
| `GET` | `/v1/sessions` | List sessions by workspace, Atlas, status, scope, and cursor offset |
| `POST` | `/v1/sessions/bulk` | Archive, restore, or delete up to 100 selected sessions |
| `GET` | `/v1/sessions/candidates` | List reviewable candidates by workspace, Atlas, status, and scope |
| `GET` | `/v1/sessions/:id` | Read session state, candidates, checkpoints, and context |
| `POST` | `/v1/sessions/:id/units` | Create or resume a durable task unit inside an automatic session |
| `POST` | `/v1/sessions/:id/candidates` | Capture durable candidate memory |
| `POST` | `/v1/sessions/:id/units/:unitId/finalize` | Save one task unit to its linked formal memory while the session remains active |
| `POST` | `/v1/sessions/:id/complete` | Close an automatic session after its final task unit is stored |
| `POST` | `/v1/sessions/:id/checkpoints` | Save progress summary |
| `POST` | `/v1/sessions/:id/finalize` | Write snapshot and compile candidates |
| `POST` | `/v1/sessions/:id/reopen` | Resume an ACP Session and update its linked automatic memory |
| `POST` | `/v1/sessions/:id/automatic-memory/revert` | Archive the linked automatic memory and retain Session audit history |
| `POST` | `/v1/sessions/:id/candidates/:candidateId/moderate` | Compile, dismiss, or revert a candidate |
| `POST` | `/v1/sessions/:id/archive` | Archive or restore a session |

```bash
curl -X POST https://api.tokst.com/v1/sessions \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "X-TokST-Actor: agent" \
  -H "Content-Type: application/json" \
  -d '{"atlasId":"<atlas-id>","task":"Implement the API"}'
```

Candidate writes accept `sourceEventId`. Automatic bridges use task units: an independent task creates one formal memory, and a follow-up updates the matching unit. The event `adapter` enum supports `acp`, `workbuddy`, `opencode`, `pi`, `codex`, and `claude`; Claude Desktop remains MCP-assisted. Repeating a session and event ID returns the existing candidate.
Members manage their own sessions. Workspace Owners and Admins may request `scope=managed` and govern candidate promotion. Reverting a compiled candidate archives its linked formal memory.

The [Session Memory guide](/docs/sessions) covers lifecycle expectations, idempotency, Agent handoffs, review permissions, Local behavior, and dashboard governance.

---

# Agent Setup

Source: https://tokst.com/docs/agent-setup

Give any AI agent persistent TokST memory in under a minute.

## Browser Setup (recommended)

For a local CLI or desktop Agent, run one command. It downloads the standalone TokST CLI, then opens browser authorization:

```bash
curl -fsSL https://tokst.com/install.sh | bash
```

Windows PowerShell uses:

```powershell
irm https://tokst.com/install.ps1 | iex
```

TokST opens a browser, confirms the signed-in account, saves the credential locally, then verifies the connection. Workspace and Atlas selection remain explicit in each command, MCP tool call, or optional directory binding. This flow keeps the API key out of chat messages and copied configuration.

## One-Link Setup

Copy this message and paste it into your agent's chat:

```
Read https://tokst.com/skill.md and install TokST memory skill step by step.
Start with: curl -fsSL https://tokst.com/install.sh | bash
```

The agent will read the linked guide and follow the matching setup steps:
1. Run `curl -fsSL https://tokst.com/install.sh | bash`
2. Approve the browser connection
3. Run `tokst init --agents <agent>` in any directory to write agent instructions; create and bind an Atlas separately when project routing is needed
4. Place the `tokst-memory` Skill in the client directory when the client supports Skills
5. Start with context and structured Markdown memories

If your agent can't access links directly, download the guide first:

```bash
curl -fsSL https://tokst.com/skill.md -o SKILL.md
```

Then tell your agent: `Read SKILL.md and follow the setup steps.`

**Version checking is built in** — re-reading the link updates the skill to the latest version automatically.

> The skill files are stateless. All your memories live in the TokST cloud, not in these files. Updating the skill never affects your data.

---

## Which Agents Are Supported?

Place `skill.md` as `SKILL.md` in the directory used by your agent:

| Agent | Skill directory |
|-------|----------------|
| Claude Code | `~/.claude/skills/tokst-memory/` |
| Codex | `~/.codex/skills/tokst-memory/` |
| Pi | `~/.pi/skills/tokst-memory/` |
| WorkBuddy | `~/.workbuddy/skills/tokst-memory/` |
| ZCode | `~/.zcode/skills/tokst-memory/` |
| Qoder | `~/.qoder/skills/tokst-memory/` |
| Kimi Code | `~/.kimi-code/skills/tokst-memory/` |
| Cursor / Windsurf | `~/.cursor/skills/tokst-memory/` |
| Any MCP-compatible agent | `~/.agents/skills/tokst-memory/` |

---

## Manual Setup

The installer is the supported starting point for a fresh computer. It requires a Unix shell and `curl`; macOS, Linux, and WSL include both in their standard environments.

```bash
# Install the standalone CLI, then authorize in the browser
curl -fsSL https://tokst.com/install.sh | bash
tokst doctor

# Verify
tokst status
```

### Step 2: Install the skill files

The easiest way is to paste the one-link setup into your agent's chat — it handles installation automatically. See [One-Link Setup](#one-link-setup-recommended) above.

To install manually, use the one-link setup script instead of downloading individual files:

### Step 3: Add MCP (optional)

TokST supports Claude Code, Codex, Pi, WorkBuddy, ZCode, Qoder, Kimi, and other MCP clients. OAuth-capable clients can connect to the cloud endpoint directly. The MCP client opens TokST for approval and needs no local runtime. Set `TOKST_MCP_TOOLSET=core` on a remote service only when a focused 11-tool memory surface is required:

```json
{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp"
    }
  }
}
```

WorkBuddy, ZCode, Qoder, Kimi, and other clients that use a static configuration can authenticate with a dedicated API key. Create one in [Dashboard API Keys](https://tokst.com/dashboard/api-keys), then use this Streamable HTTP configuration:

```json
{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp",
      "headers": {
        "Authorization": "Bearer tk_live_your_api_key"
      }
    }
  }
}
```

Use a dedicated key for each client and revoke it from the dashboard when that client no longer needs access.

Local stdio MCP remains available after the installer for clients that require a local process.

---

## Dashboard Shortcut

When you create an API key in the [dashboard](https://tokst.com/dashboard/api-keys), the creation modal shows:
- A ready-to-copy **SKILL.md** (with your key embedded)
- A **Quick Start script** (one paste into terminal)
- An **MCP config** JSON
- A per-row **Copy for Agent** button on each key

You can also just share `https://tokst.com/skill.md` — the agent handles the rest.

---

## Verify It Works

```bash
# Check CLI is connected
tokst status

# Check skill files are installed (adjust path for your agent)
head -5 ~/.claude/skills/tokst-memory/SKILL.md
# Should show: --- name: tokst-memory ... version: 0.8.3 ---

# Store a test memory
TOKST_AGENT=1 tokst remember "Agent setup complete" --type note --json

# Search for it
TOKST_AGENT=1 tokst search "agent setup" --json

# Optional: enable automatic memory bridges once
tokst auto on --agent all
tokst acp proxy -- <acp-agent-command> [args]
tokst auto status
```

### OpenCode Terminal, App, and ACP

OpenCode Terminal and the macOS App load the TokST global plugin after one restart. Sessions started with `opencode` or resumed with `opencode -s` map to one TokST Session and update the same automatic memory. An ACP-compatible editor or IDE can also launch OpenCode through TokST.

```bash
tokst auto on --agent opencode
tokst acp opencode --doctor
```

Use this Agent command in an ACP-compatible editor or IDE:

```json
{
  "command": "tokst",
  "args": ["acp", "opencode"]
}
```

`tokst auto repair --agent opencode` regenerates the global plugin with the current absolute TokST executable path. `tokst acp opencode --repair` retains the ACP Host repair workflow.

### Pi, Codex, Claude Code, and Claude Desktop

Enable all detected native clients once, then restart the client you use. Pi receives a global extension. Codex and Claude Code receive TokST-managed Hook entries while every existing Hook remains in place. Each entrypoint maps a native session to one TokST Session and updates its matching automatic memory when the conversation resumes.

```bash
tokst auto on --agent pi,codex,claude
tokst auto verify --agent pi,codex,claude --json
tokst acp pi --doctor
```

Claude Desktop uses the TokST MCP extension for assisted memory capture, search, Session lifecycle, and reversal. Its desktop integration remains `assisted`; it does not claim automatic conversation observation.

## Troubleshooting

| Problem | Fix |
|---------|-----|
| Agent doesn't see the skill | Verify the skill directory path matches your agent (`~/.claude/skills/`, `~/.cursor/skills/`, etc.) |
| `tokst: command not found` | Run `curl -fsSL https://tokst.com/install.sh \| bash`, then open a new terminal. |
| `Not logged in` | `tokst login --key tk_live_xxxx` |
| MCP tools not showing | Run `tokst login` on the same machine as the MCP server |
| Skill is outdated | Re-read `tokst.com/skill.md` or re-download the files |
| Automatic memory has not appeared | Run `tokst auto status --agent opencode` or `tokst auto status --agent workbuddy`; restart the corresponding client after bridge installation. |
| `tokst acp opencode` reports a legacy config | Run `tokst acp opencode --repair`, then restart the ACP host. |
| Automatic memory blocked a session | Run `tokst auto status`; keys, passwords, cookies, and private keys are intentionally removed or blocked before upload. |

Full CLI reference: [CLI Commands](/docs/cli)

---

# Agent Identity

Source: https://tokst.com/docs/agent-identity

TokST gives every trusted Agent a stable identity code such as `agt_...`. The identity belongs to one API Key and remains stable across CLI, local MCP, remote MCP, REST API, and dashboard sessions.

## Identity Model

| Field | Meaning |
|---|---|
| `agt_...` | Stable Agent identity code used for messages and audit records |
| Connection credential | An API Key or approved OAuth client credential bound to exactly one trusted Agent identity |
| Nickname | Human-readable Agent name, synchronized from the Agent memory `source` label |
| Source | A descriptive label such as `Codex`, `MacOS Pi`, or `ICON Pi`; it does not authorize requests |
| Status | `active` while the API Key is valid; `inactive` after key revocation |

TokST creates the identity lazily on the first trusted Agent request. Clients never submit an Agent ID to claim an identity. Send `X-TokST-Actor: agent` for REST requests; local and remote MCP requests identify as Agents automatically. OAuth refresh and API-key revocation both preserve the same `agt_...` identity history.

## Nicknames

When an Agent stores a memory with a source label, TokST uses that label as the Agent nickname:

```bash
TOKST_AGENT=1 tokst remember "Deployment completed" \
  --source "MacOS Pi" --source-type agent --json
```

In **Dashboard → Agents → Agent management**, Owner and Admin can correct a nickname for early identities that do not have an associated source record. The stable `agt_...` code remains unchanged.

## Find the Current Identity

Use the active workspace ID to list trusted Agents:

```bash
tokst agent list <workspace-id> --json
```

The result includes `displayName`, `lastSeenAt`, and `isCurrent`. `isCurrent: true` marks the identity bound to the API Key used by this CLI or MCP session.

Remote MCP exposes the same information through `tokst_agent_list`.

## Communication

The dashboard separates **Group** broadcasts from **Direct messages**. Every entry records a sender and recipient set:

- Agent-originated messages show the Agent nickname and identity.
- Dashboard-originated messages show `You (dashboard)` because a human operator does not impersonate an Agent.
- Direct messages are visible to the sender, recipients, and workspace Owner/Admin.
- Broadcasts create a receipt for each active Agent in the workspace and are visible to workspace members.

Use the CLI for Agent-to-Agent messages:

```bash
tokst message send "Please review the deployment" \
  --workspace <workspace-id> --to agt_abc,agt_def --kind handoff

tokst message send "Release is live" \
  --workspace <workspace-id> --broadcast --kind update

tokst message inbox --json
tokst message acknowledge <message-id>
```

`tokst message inbox` reads all workspaces by default. Add `--workspace <id>` to restrict the result.

## Message Management

In **Dashboard → Agents → Communication**, workspace Owner and Admin can select one or more messages, then archive, restore, or permanently delete them. Archived messages and their delivery receipts remain available in the Archived view. Permanent deletion removes the message and its recipient receipts.

The administrator dashboard provides the same bulk lifecycle controls across workspaces for operational cleanup and audit management.

## Real-Time Delivery

Run this command as a small sidecar beside a long-running Agent runtime:

```bash
TOKST_AGENT=1 tokst agent listen --json
```

The listener opens an authenticated Server-Sent Events connection, emits JSON Lines for `ready`, `message.created`, `heartbeat`, and `auth.revoked`, and reconnects automatically. Every new connection first returns the durable unread-message snapshot, so messages sent while an Agent is offline remain available. A received event keeps its `unread` receipt until the Agent explicitly acknowledges or closes it.

The sidecar delivers events to the local Agent runtime. Codex, Claude Code, Pi, and OpenCode runners forward those JSON events into their own task loops; MCP continues to provide explicit inbox and receipt tools.

## REST API

```bash
curl "https://api.tokst.com/v1/agents?workspace_id=$WORKSPACE_ID" \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "X-TokST-Actor: agent"
```

The response returns both snake-case database fields and camel-case client fields for compatibility, including `display_name` and `displayName`.

---

# Session Memory

Source: https://tokst.com/docs/sessions

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.

```bash
# 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:

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

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

```bash
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](/docs/cli#session-memory), [MCP reference](/docs/mcp#session-memory-protocol), and [REST API reference](/docs/rest-api#session-memory-api) for interface-specific details.

---

# Skill Guide

Source: https://tokst.com/docs/skill

The TokST skill file (`skill.md`) is a self-contained document that AI agents can read to install and use TokST memory. This page documents how to use it.

## What is skill.md?

`skill.md` is a single Markdown file hosted at `https://tokst.com/skill.md`. It contains the operational rules an AI agent needs to:

1. Install the TokST CLI
2. Complete browser authorization or use an API key for automation
3. Place the Skill in its client directory when that client supports Skills
4. Read, search, store, and govern durable memories
5. Run Cloud or Local Sessions and exchange scoped Agent handoffs

Agents can read it via URL fetch or users can paste its content directly into a chat.

## One-Link Setup

Share this link with any AI agent so it can read the current setup and operating rules:

```
https://tokst.com/skill.md
```

### How to use it

Copy this message and paste it into your agent's chat:

```
Read https://tokst.com/skill.md. Install TokST, configure the matching MCP mode, and follow the Session memory workflow.
```

The installer opens browser authorization and retains the local connection during upgrades. The same `skill.md` works with WorkBuddy, ZCode, Qoder, Kimi, and other clients that support Skills or MCP.

## Version Checking

The skill file includes a version marker (`<!-- skill-version: 0.8.3 -->`). Agents can compare their locally installed version against the remote to detect updates:

```bash
# Installed version
grep "^version:" ~/.claude/skills/tokst-memory/SKILL.md

# Latest version
curl -fsSL https://tokst.com/skill.md | grep "skill-version:"
```

## Supported Agents

Place `skill.md` as `SKILL.md` in the directory used by the target client:

| Agent | Skill directory |
|-------|----------------|
| Claude Code | `~/.claude/skills/tokst-memory/` |
| ZCode | `~/.zcode/skills/tokst-memory/` |
| Cursor / Windsurf | `~/.cursor/skills/tokst-memory/` |
| Codex CLI | `~/.codex/skills/tokst-memory/` |
| Pi | `~/.pi/skills/tokst-memory/` |
| WorkBuddy | `~/.workbuddy/skills/tokst-memory/` |
| Qoder | `~/.qoder/skills/tokst-memory/` |
| Kimi Code | `~/.kimi-code/skills/tokst-memory/` |
| Generic MCP | `~/.agents/skills/tokst-memory/` |

## Connection modes

Browser-capable MCP clients can connect to `https://api.tokst.com/mcp` and approve OAuth in TokST. Static MCP clients use a dedicated API key in the `Authorization` header. Local MCP runs through `tokst local mcp` after `tokst setup --local` and keeps data in the device SQLite profile.

TokST Cloud MCP exposes 51 tools for memories, workspaces, files, Sessions, automatic memory, trusted Agent identity, and messages. The public Skill includes a concise recovery path for PATH conflicts, browser approval, static MCP authorization, quota failures, Local SQLite repair, automatic-memory diagnostics, and Agent listener reconnection.

## Dashboard Integration

When you create an API key for automation in the [dashboard](https://tokst.com/dashboard/api-keys), the creation modal provides:
- A ready-to-copy **SKILL.md** with your key embedded
- A **Quick Start script** for terminal paste
- An **MCP config** JSON
- A per-key **Copy for Agent** button

Browser sign-in and remote MCP approval do not create an API key. Use the [Agents](/dashboard/agents) page to review trusted `agt_...` identities and workspace handoffs.

WorkBuddy, ZCode, Qoder, and Kimi Code can also import `https://tokst.com/skill.md` from their Skills or Agent Skills settings.

## Related

- [Agent Setup Guide](/docs/agent-setup) — Full setup walkthrough
- [CLI Reference](/docs/cli) — Complete command documentation
- [MCP Server](/docs/mcp) — MCP configuration details

---

# File Attachments Guide

Source: https://tokst.com/docs/attachments

TokST enables you to attach files to memories, providing rich context alongside text. Files are stored in Cloudflare R2 with metadata indexed in Supabase.

## Overview

When you attach a file to a memory, TokST:

1. Uploads the file to Cloudflare R2 object storage
2. Stores metadata (filename, size, MIME type, URL) in Supabase
3. Associates the attachment with the memory
4. Generates a **presigned upload URL** (valid for 1 hour) and **presigned download URLs** (valid for 15 minutes)

This means files are never stored in the database directly — they live in R2, keeping your database lean and fast.

## CLI Usage

### Attach During Creation

Use the `--file` flag when storing a new memory. The flag is repeatable for multiple files.

```bash
# Single file
tokst remember "Sprint retrospective notes" --file retro-notes.md

# Multiple files
tokst remember "Q3 planning documents" --file roadmap.pdf --file budget.xlsx --file timeline.png
```

The CLI accepts local files. For a remote URL, use the remote MCP `fileUrl` input or download the file locally before passing `--file`.

### Attach to an Existing Memory

Use the `attach` subcommand:

```bash
tokst memory attach <memory-id> --file document.pdf
```

### Download Attachments

Pull a memory's files back to your local machine with the `download` subcommand. Files are streamed from R2 via a presigned GET URL and saved with their original filenames.

```bash
# Download all attachments to ~/Downloads
tokst memory download <memory-id>

# Specify an output directory (auto-created if missing, ~ expands to $HOME)
tokst memory download <memory-id> --out ./files

# Download a single attachment by ID
tokst memory download <memory-id> --attachment-id <attachment-id>

# Machine-readable output
tokst memory download <memory-id> --json
```

> Download is cloud-only. Local SQLite mode throws — run `tokst login --key <api-key>` first.

## MCP Usage

When using the MCP server, pass file parameters in the tool call:

```json
{
  "content": "Meeting notes with attached diagram",
  "filePath": "/home/user/diagram.png"
}
```

Or with a remote URL:

```json
{
  "content": "Reference architecture",
  "fileUrl": "https://example.com/architecture.png"
}
```

To attach a file to an existing memory via MCP, use `tokst_attach_file`:

```json
{
  "memoryId": "mem_abc123",
  "fileUrl": "https://example.com/report.pdf",
  "filename": "report.pdf"
}
```

ChatGPT uploads are bound automatically through the tool's `openai/fileParams` metadata. To download the file again, call `tokst_download_file`:

```json
{
  "memoryId": "mem_abc123",
  "attachmentId": "attachment-uuid"
}
```

The remote MCP server returns a 15-minute signed URL as both JSON and MCP `resource_link` content. Remote MCP uploads have a 50 MB per-file limit.

## Upload Confirmation

An attachment stays `pending` until confirmation. The confirmation route performs an R2 `HEAD` request, rejects missing or empty objects with `409`, and records the actual object size and MIME type before changing the attachment to `active`. Pending or failed uploads older than two hours are cleaned up automatically.

## Web Dashboard

The web dashboard provides a drag-and-drop interface for file uploads with real-time progress indicators. Navigate to any memory and use the attachment panel to upload files.

## Storage Quotas

Plans have the following storage limits for file attachments:

| Plan | Storage Quota |
|---|---|
| **Free** | 500 MB |
| **Starter** | 2 GB |
| **Pro** | 10 GB |
| **Team workspace** | 20 GB shared |
| **Legacy Max / Team** | Existing entitlement |

| Upload Channel | Per-file Behavior |
|---|---|
| Web dashboard | 500 MB client-side maximum |
| Remote MCP | 50 MB maximum |
| CLI | Limited by the account's remaining storage quota |

Storage usage is tracked in real time and visible through `tokst status`.

## R2 Path Structure

Files are stored in Cloudflare R2 using the following path convention:

```
{workspace_id}/{atlas_id}/{memory_id}/{attachment_id}-{filename}
```

For example:

```
ws_abc123/atlas_def456/mem_789abc/att_xyz789-report.pdf
```

This structure ensures:

- **Isolation** — Files from different workspaces never collide
- **Discoverability** — You can reconstruct paths from database metadata
- **Cleanup** — Deleting a memory or atlas removes the matching R2 objects before database cleanup

## Security

File access is secured with **presigned URLs**:

| Action | URL Validity |
|---|---|
| Upload | 1 hour |
| Download | 15 minutes |

Presigned URLs are generated server-side and require valid authentication. Direct R2 bucket access is blocked. This ensures that only authenticated users with appropriate permissions can upload or download files.

Object deletion accepts only an exact internal service credential or a user token with matching attachment ownership. User-provided file keys outside the authenticated scope are rejected.

## Best Practices

- **Use meaningful filenames** — The filename becomes part of the R2 path and is displayed in the dashboard
- **Keep files under 100 MB** for faster uploads
- **Use remote MCP `fileUrl`** when an agent needs to attach a public remote asset
- **Monitor your quota** with `tokst status` to avoid hitting storage limits

---

# API Keys & Authentication

Source: https://tokst.com/docs/api-keys

API keys authenticate CI, servers, and unattended REST or MCP automation. Human CLI and remote MCP setup use browser authorization by default.

## Creating API Keys

API keys are created from the [TokST Web Dashboard](https://tokst.com/dashboard).

1. Log in to the dashboard
2. Navigate to **API Keys** in the sidebar
3. Click **Create Key**
4. Give the key a descriptive name (e.g., "Development", "CI Pipeline", "Agent Claude")
5. Copy the key immediately — it is shown only once

### Key Format

```
tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

The prefix `tk_live_` identifies it as a production key. All keys follow this format regardless of the plan.

## Key Storage

When you create a key, TokST stores a **SHA-256 hash** of it server-side. The raw key is never stored — if you lose it, you must revoke and create a new one.

Locally, the CLI stores credentials in `~/.tokst/config.json`:

```json
{
  "apiKey": "tk_live_xxxx",
  "accessToken": "eyJhbGci...",
  "anonKey": "sb_publishable_xxxx",
  "tokenExpiresAt": "2026-07-09T10:57:47.306Z",
  "supabaseUrl": "https://pdjpdivokmcevxdrvtfb.supabase.co",
  "apiKeyId": "c699987e-..."
}
```

The MCP server reads this same file for authentication.

## Authentication Flow

### Browser setup for people and local agents

```bash
curl -fsSL https://tokst.com/install.sh | bash
```

The script downloads a checksum-verified standalone TokST CLI, then opens TokST for authorization. It requires only a Unix terminal and `curl`.

### API key login for automation

```bash
tokst login --key tk_live_xxxx
```

What happens:

1. The CLI sends the API key to the TokST API
2. The server verifies the SHA-256 hash against stored keys
3. On success, the server returns a **JWT access token** (valid for 1 hour)
4. The CLI stores both the API key and the JWT in `~/.tokst/config.json`
5. Subsequent API calls use the JWT, which auto-refreshes before expiry

### Token Lifecycle

| Token | Duration | Refresh |
|---|---|---|
| JWT Access Token | 1 hour | Auto-refreshed by CLI and MCP server |

You generally don't need to worry about token expiry — the CLI and MCP server handle refresh automatically.

## Rate Limiting

Edge service routes apply rolling per-user limits:

| Limit | Value |
|---|---|
| Authentication exchange | 10 requests per minute |
| Usage tracking | 60 requests per minute |
| Embedding generation | 30 requests per minute |
| Upload URL requests | 30 requests per minute |

Exceeding these limits returns HTTP 429 (Too Many Requests). Rate limits reset on a rolling 60-second window.

## Monthly Quotas

Usage is tracked per user against monthly quotas, which vary by plan. The counter increments atomically, so concurrent agent calls cannot overwrite one another:

| Plan | Monthly Operations | Storage |
|---|---|---|
| **Free** | 1,000 | 500 MB |
| **Starter** | 2,000 | 2 GB |
| **Pro** | 10,000 | 10 GB |
| **Team workspace** | 20,000 shared | 20 GB shared |
| **Legacy Max / Team** | Existing entitlement | Existing entitlement |

Check your usage anytime:

```bash
tokst status
tokst status --json    # For programmatic consumption
```

## Revoking vs. Deleting Keys

| Action | Effect |
|---|---|
| **Revoke** | Key is immediately deactivated. Cannot be re-enabled. Existing tokens issued by this key remain valid until expiry. |
| **Delete** | Key is permanently removed. All associated tokens are invalidated immediately. |

In the dashboard, use **Revoke** for immediate permanent deactivation while retaining the audit record. Use **Delete** to remove the key record.

## Usage and Per-Key Audit Logs

Personal quota counters belong to the user. A Team workspace uses its shared subscription counter. API key logs identify which key performed each action. The dashboard shows:

- Total operations this month
- Operations by day (chart)
- Last used timestamp
- Key name and creation date

This separates quota enforcement from per-key audit attribution.

## MCP Server Auto-Auth

The MCP server authenticates automatically by reading `~/.tokst/config.json`. No environment variables or manual configuration steps are needed — it picks up credentials from the same file that `tokst login` creates.

To override for a non-interactive process, set the `TOKST_API_KEY` environment variable:

```bash
TOKST_API_KEY=tk_live_xxxx bun x -y @tokst/mcp-server
```

## Security Best Practices

- **Use descriptive key names** so you can identify their purpose in the dashboard
- **Create separate keys** for development, production, and each agent/integration
- **Rotate keys periodically** by creating a new key, updating your integrations, then revoking the old one
- **Never commit keys** to version control — use environment variables or secret managers
- **Check usage regularly** via the dashboard to detect unexpected activity
- **Revoke compromised keys immediately** from the dashboard

## Agent Quick Setup

To give an AI agent (Claude Code, Cursor, Codex, ZCode, etc.) access to TokST, share this one link:

```
https://tokst.com/skill.md
```

The agent reads the document, installs the CLI, and follows the matching Skill and MCP setup. Place the document in the client Skill directory when that client supports Skills; use the displayed MCP configuration for tool access.

You can also copy a ready-made setup script or SKILL.md directly from the **API Keys** page in the dashboard (click **Copy for Agent** on any key).

---

# Referrals and Benefits

Source: https://tokst.com/docs/referrals

TokST referrals reward product benefits, not cash. Every account has one referral code and a shareable link in **Dashboard → Settings → My referrals**.

## How a Referral Qualifies

1. A new account registers through `https://tokst.com/ref/<code>`.
2. The account confirms its email address.
3. Within seven days of registration, the account creates one valid active memory through the dashboard, CLI, MCP, or REST API.

The inviter and the new account each receive one month of Pro benefits. Rewards have no monthly cap. Existing accounts cannot add or change a referral code, and self-referrals are excluded.

## My Benefits

Referral rewards appear in **Dashboard → Settings → My benefits** as available Pro benefits.

- Free and Starter accounts can activate one available benefit at a time. It starts immediately, or is scheduled after an already active Pro benefit.
- Pro and Max accounts retain their current subscription. Activated rewards become renewal credit for a later paid renewal cycle.
- One Pro month is 30 days. Available benefits do not expire. Active and scheduled benefits show their start and end dates.

The dashboard always displays both the base plan and the currently effective plan. When an active Pro benefit expires, the account returns to its base plan.

## Public Beta Membership

The referral-and-benefits migration grants every cloud account that already exists when it runs a public beta membership:

- Free, Starter, and Pro accounts receive active Pro access for 365 days from the migration date.
- Max accounts retain Max and receive 12 months of Pro renewal credit.

## REST API

Authenticated clients can read the same account data through the cloud API:

| Method | Endpoint | Purpose |
|---|---|---|
| `GET` | `/v1/referrals/me` | Referral code, statistics, and referral records |
| `GET` | `/v1/benefits/me` | Benefit ledger, base plan, and effective plan |
| `POST` | `/v1/benefits/:id/activate` | Activate one available Pro benefit |

CLI and MCP do not require referral commands. Their valid memory writes participate in activation automatically.

---

# Help Center

Source: https://tokst.com/docs/help

Use this page to diagnose common TokST setup and daily-use issues. Each section includes the fastest recovery path and a command to verify the result.

## Installation and updates

### `tokst: command not found`

Install the standalone CLI, then open a new terminal so the updated PATH is loaded.

```sh
curl -fsSL https://tokst.com/install.sh | bash
tokst version
```

Windows PowerShell uses:

```powershell
irm https://tokst.com/install.ps1 | iex
tokst version
```

Windows Git Bash supports the Unix command and opens the PowerShell installer automatically.

### The installed version looks older after an update

`tokst update` upgrades the channel that launched the command: standalone uses the verified binary release, npm runs its global npm update, and Bun runs its global Bun update. Inspect the active channel and repair shell priority when a standalone binary should lead PATH.

```sh
tokst update
tokst version --verbose
tokst doctor
tokst doctor --fix-path
```

Open a new terminal after a standalone installation or PATH repair. The installer keeps npm and Bun installations intact, records its own binary location, and retains cloud authorization.

## Sign in and cloud connection

### Browser authorization does not return to the terminal

Keep the terminal process open while confirming the browser page. Start a fresh flow when the browser says the connection request is unavailable.

```sh
tokst setup
tokst connection test
```

Use an API key for CI, servers, and other unattended environments:

```sh
tokst login --key tk_live_xxxx
tokst connection test
```

### `tokst doctor` shows an Atlas as optional

An Atlas binding only supplies project-directory routing. Your account, workspaces, search, and memories remain available without one. Bind an Atlas when a directory permanently belongs to a project.

```sh
tokst atlas list
tokst atlas bind --atlas-id <atlas-id>
```

## Local mode and SQLite

### Create private memory on this device

```sh
tokst setup --local
tokst local remember "Private note" --type note
tokst local search "Private"
```

Local memory, attachments, search index, and backups stay in the platform application-data directory. See [TokST Local](/docs/local) for backup and explicit cloud sync.

### `CHECK constraint failed` or `SQL logic error`

Update to the latest standalone CLI, create a backup, then inspect the local profile.

```sh
tokst update
tokst local backup create --name before-repair
tokst local status --json
```

Include the full error, `tokst version`, and `tokst local status --json` when reporting a reproducible issue. Keep the generated backup until the write succeeds.

## Workspaces and Atlases

### I cannot create a workspace or Atlas

Workspace and Atlas creation follow the current plan limits. Review account usage in the dashboard, switch to the intended workspace, and retry.

```sh
tokst status
tokst workspace list
tokst atlas list
```

Cloud Free includes one personal workspace and one Atlas. Team workspaces use their own Team subscription and shared quota. See [Product Editions](/docs/editions).

### I cannot see a team invitation

The invitee can review every pending invitation and accept or decline it from the dashboard or CLI.

```sh
tokst workspace inbox
tokst workspace respond <invitation-id> --accept
```

Team owners and admins manage invitations in [Team Collaboration](/docs/team-collaboration).

## MCP and Agent setup

### WorkBuddy, ZCode, Qoder, or Kimi cannot open browser authorization

Create a dedicated API key in Dashboard → API Keys. Configure the client as Streamable HTTP and send the key in every request through the Authorization header. Revoke the key when the client is no longer used.

```json
{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp",
      "headers": {
        "Authorization": "Bearer tk_live_your_api_key"
      }
    }
  }
}
```

### MCP tools do not appear

Complete authorization on the same machine that runs the local MCP process, then restart the MCP client.

```sh
tokst connection test
tokst init --agents codex,claude,cursor,opencode,pi --force
```

For remote MCP, reconnect the client to `https://api.tokst.com/mcp` and complete its OAuth approval. See [MCP Overview](/docs/mcp).

### Agent messages are missing

Each Agent reads its own persistent inbox. Start the listener beside a long-running Agent for immediate delivery, and use the inbox to synchronize messages after restarts.

```sh
TOKST_AGENT=1 tokst agent listen --json
TOKST_AGENT=1 tokst message inbox --json
```

Review the active Agent identity with `tokst agent list`. See [Agent Identity](/docs/agent-identity) for permissions, messages, and status.

## Files, usage, and security

### A file is visible but its memory is gone

Open **Files** in the dashboard and review the recycle bin. Restoring the memory restores the normal association; the repair tools identify orphaned attachments for review.

### Upload, usage, or permission requests fail

Confirm the target workspace, available shared or personal quota, and your workspace role. Owners manage billing and audit access; admins manage team content; members manage their own memories.

```sh
tokst status
tokst workspace list
```

API keys inherit the permissions of their owner. Revoke unused keys from the dashboard and create keys only for trusted automation. See [API Keys](/docs/api-keys).

## Still need help?

Gather the command, complete error message, installed version, operating system, and whether the flow used Local, CLI, local MCP, remote MCP, dashboard, or REST API. This makes support and issue triage reproducible.

Useful checks:

```sh
tokst version
tokst doctor
tokst connection test
tokst status --json
```

---

# Version History

Source: https://tokst.com/docs/changelog

This page records released TokST capabilities. Each entry describes the public product surface available in that version.

## 0.8.3 - Unreleased

- Public pages, documentation, developer resources, help, trust pages, and language variants now ship as crawlable static HTML with canonical URLs, hreflang, structured data, Markdown mirrors, sitemap coverage, and Agent discovery links.
- Added `llms-full.txt`, Markdown document endpoints, an Atom feed, a security contact file, and optional post-deploy IndexNow submission for search and Agent discovery.
- Unified automatic memory under `tokst auto on|off|status|repair|verify|logs` with one state model for WorkBuddy, OpenCode, Pi, Codex, Claude Code, and Claude Desktop.
- Added managed Pi extension plus safe Codex and Claude Code Hook installation. Existing third-party Hooks remain intact and `auto off` removes only TokST-managed entries.
- Preserved OpenCode Terminal/App/ACP and WorkBuddy integrations. Native and ACP sources now share stable session mapping, local redaction, queue delivery, compiler output, automatic-memory reversal, and source filtering.
- Added `tokst acp pi --doctor`; Claude Desktop remains an MCP-assisted integration with explicit Session tools.

## 0.6.6

- Added Skills and `tokst init --agents` support for WorkBuddy, ZCode, Qoder, and Kimi Code.
- Added API Key Streamable HTTP MCP guidance for clients that use static MCP configuration, including WorkBuddy, ZCode, Qoder, and Kimi.

## 0.6.5

- `tokst update` now detects standalone, npm, and Bun installations and upgrades through the active channel.
- Added `tokst version --verbose` for installation-channel diagnostics and `tokst doctor --fix-path` for standalone PATH repair in zsh and bash.
- Updated the macOS/Linux and Windows installers to retain package-manager installs, record the standalone binary location, preserve authorization, and prioritize the standard standalone directory.

## 0.6.4

- `tokst status` now reports personal workspace and Atlas capacity, plus the Team workspace creation quota. JSON, REST status, local MCP, remote MCP, and the setup skill expose the same account quota data.
- Corrected the Starter CLI monthly-call display to 2,000.

## 0.6.3

- Extended Local SQLite scope compatibility to legacy constraints written with either single or double quoted values.

## 0.6.2

- Fixed Local `remember` for existing SQLite profiles created before the `project` to `atlas` scope rename. Legacy files now store the compatible value and consistently return `atlas` to the CLI and MCP.
- Added Windows Git Bash support to `install.sh`; it hands off to the checksum-verified PowerShell installer.

## 0.6.1

- Added account referral links, masked referral progress, manual Pro-benefit activation, and an administrator audit ledger.
- A verified new account qualifies after one active memory created within seven days through the dashboard, CLI, MCP, or REST API. Both accounts receive one available month of Pro with no monthly referral cap.
- Existing cloud Free, Starter, and Pro accounts receive 365 days of Pro public beta membership from migration day. Existing Max accounts retain Max and receive 12 months of Pro renewal credit.
- Added authenticated referral and benefit REST endpoints and unified personal quota resolution around the effective plan.

## 0.6.0

- Added TokST Local for macOS, Linux, and Windows: a separate SQLite profile, FTS5 search, local files, recoverable backups, and `tokst local mcp`.
- Added explicit local-Atlas to cloud-Atlas synchronization. Concurrent edits are kept as separate conflict memories; local attachments remain local in this release.
- Defined Local, Cloud Free, Starter, Pro, Team, and Enterprise boundaries. Free includes 1,000 calls and 500 MB; Starter includes 2,000 calls and 2 GB. Team is workspace-scoped with 3 seats, 20,000 shared calls, 20 GB, and 50 Atlases at the $19/month starting tier.
- Moved Team member governance into Team Management: invitations, roles, member removal, and Owner transfer are managed per Team workspace; workspace settings focus on workspace metadata.
- Released matching `@tokst/cli@0.6.0` and `@tokst/mcp-server@0.6.0` packages.

## 0.5.7

- Reworked `tokst --help` into an everyday workflow and added complete grouped references through `tokst memory --help`, `tokst atlas --help`, `tokst workspace --help`, and `tokst agent --help`.
- Fixed standalone update notices to compare versions correctly, refresh stale release metadata, and avoid a duplicate update check immediately after `tokst update`.
- Synced the CLI and local MCP package releases to `0.5.7`.

## 0.5.6

- Added standalone CLI binaries for Linux ARM64, Windows x64, and Windows ARM64. TokST now supports six primary desktop and server targets.
- Added a checksum-verified PowerShell installer at `https://tokst.com/install.ps1` and Windows-safe self-update replacement.

## 0.5.5

- The CLI introduced checksum-verified standalone binaries for macOS Apple Silicon, macOS Intel, and Linux x64. New users need only `curl`; Bun, Node.js, npm, and a package manager are no longer prerequisites.
- Added `tokst update` for atomic, checksum-verified standalone CLI upgrades. Existing local authorization remains in place.
- Added a release workflow that creates the three binary assets, checksums, version manifest, GitHub Release, and optional R2 public-download upload in one release.

## 0.5.4

- Added `tokst version` and `tokst --version` to show the installed CLI release.
- Synced `@tokst/cli` and `@tokst/mcp-server` to `0.5.4`; local MCP now reports the same protocol version.
- CLI upgrades retain an existing authorized connection and update stale `tokst` commands already present in PATH.

## 0.5.3

- Fixed the published CLI command set so `tokst connection test` is available after browser setup.
- The installer now prioritizes `~/.bun/bin` in zsh and bash profiles, preventing an older globally installed CLI from taking precedence.
- CLI browser authorization reuses a stable local connection credential and its existing `agt_...` identity.
- OAuth credentials stay internal to the connection flow; the user API Key page lists manually created automation keys only.
- `tokst agent listen` immediately receives local events and synchronizes the durable inbox every second for cross-instance and dashboard-originated messages.

## 0.5.2 - Current

- Added zero-prerequisite setup: `curl -fsSL https://tokst.com/install.sh | bash` installs Bun and the CLI when needed, then opens browser authorization.
- Browser setup now authorizes only the TokST account. It never implicitly selects or persists a workspace or Atlas.
- `tokst doctor` marks an unbound Atlas as `SKIP`, keeping optional project routing separate from account connectivity.
- Remote MCP OAuth connects directly to `https://api.tokst.com/mcp` without placing API keys in client configuration.
- `tokst workspace list` and `tokst workspace inbox` surface pending invitations with direct response commands.
- `tokst init` writes local instructions for Codex, Claude, Cursor, OpenCode, and Pi without creating cloud data.
- Memories support evidence, confidence, expiry, verification, and explicit supersession relationships.
- Remote Streamable HTTP MCP exposes the full 46-tool surface without a persistent session; `TOKST_MCP_TOOLSET=core` selects the focused 11-tool surface.
- `tokst agent listen` delivers trusted Agent handoffs through SSE, reconnects automatically, and recovers durable unread messages.

## 0.5.1

- Added browser-mediated setup with CLI Device Code authorization: `bunx @tokst/cli@0.5.1 setup` opens TokST once, saves the approved connection locally, and verifies it with `tokst connection test`.
- Added OAuth 2.1 + PKCE for remote MCP, including protected-resource metadata, dynamic client registration, token refresh, revocation, and browser workspace/Atlas selection.
- Added the Dashboard → Agents → Connect page with client-specific Codex, Claude Code, Cursor, OpenCode, and Pi setup plus a remote server check.
- Updated CLI, local MCP, remote MCP, Agent setup, and three-language connection documentation for the browser authorization flow.

## 0.5.0

- Added `tokst agent listen`: a persistent SSE sidecar for trusted Agent identities. It streams real-time handoffs, reconnects automatically, and resynchronizes durable unread messages.
- Added the authenticated `GET /v1/agent-messages/events` interface. Event delivery remains scoped to the API-Key-bound `agt_...` identity, while the persistent inbox remains the delivery source of record.
- Updated CLI, local MCP, remote MCP, REST, Skill, and three-language documentation contracts for Agent coordination.

## 0.4.9

- Fixed CLI workspace selection: `tokst workspace switch` persists the selected workspace, and `tokst atlas init` creates Atlases in that workspace.
- Made pending invitations visible in `tokst workspace list` and `tokst workspace inbox`, including direct accept and decline commands.
- Added platform-admin audit visibility for pending team workspace invitations.
- Release checks now compare local and remote MCP tool sets and verify workspace invitation coverage across every delivery surface.
- Trusted Agent identities and persistent workspace handoffs: API Keys lazily create stable `agt_...` identities, memory records preserve the creating Agent, and CLI, local MCP, remote MCP, REST, and the workspace dashboard share Agent inbox, broadcast, acknowledgement, and close flows.
- Moved Agent collaboration to a workspace-scoped dashboard page. Workspaces now focus on members, invitations, roles, and ownership without Agent Realtime refreshes resetting the management view.
- `tokst message inbox` now reads all workspaces by default. Pass `--workspace <id>` for a scoped inbox, so a stale local workspace selection cannot hide a pending handoff.

## 0.4.5

- Shared workspace governance across the dashboard, CLI, local MCP, remote MCP, and REST API: invitations, acceptance, role changes, member removal, leaving, and owner transfer.
- Trusted memory lifecycle: evidence, confidence, expiry, verification, supersession links, archive, restore, and deletion.
- Full interface alignment: local MCP and remote MCP full mode expose 33 matching tools; REST exposes 38 authenticated routes.
- Workspace types are preserved as `personal` or `team` through Core, SQLite, Supabase, CLI, REST, and MCP.
- Dashboard improvements for shared-memory ownership, workspace-scoped Atlas selection, archived-memory restore, files, and attachments.
- `tokst init` writes local Agent instructions only. Atlas creation and directory binding are separate commands: `tokst atlas init` and `tokst atlas bind`.

## 0.4.4

- Restored JWT-backed semantic recall for cloud memory search.
- Stabilized the published CLI and MCP package baseline.

## 0.4.3

- Preserved semantic retrieval when keyword search has no strong result.
- Improved adaptive search reliability for cold vector retrieval.

## 0.4.0

- Unified the public Agent skill document with the product workflow.
- Refined the dashboard and aligned the displayed product version.

## 0.3

- Added CLI import workflows, attachment visibility, storage usage, API-key setup, and broader Agent support including Codex and Pi.
- Established the cloud-first CLI and MCP distribution path.

## 0.2

- Added R2-backed file attachments and storage quota handling.
- Introduced cloud authentication, API keys, workspace and Atlas ownership, and early RLS isolation fixes.

## Source of Record

Release history is maintained with the repository's Git tags, release commits, package versions, and the published capability contracts in this documentation.