TokST Persistent memory for people and AI agents

Help Center

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.

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

Windows PowerShell uses:

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.

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.

tokst setup
tokst connection test

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

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.

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

Local mode and SQLite

Create private memory on this device

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 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.

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.

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.

I cannot see a team invitation

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

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

Team owners and admins manage invitations in 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.

{
  "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.

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.

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.

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 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.

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.

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:

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