--- name: tokst-memory description: Use TokST to retrieve, store, govern, and hand off durable context across cloud workspaces or Local SQLite. version: 0.8.3 license: MIT --- # TokST Memory Skill Use TokST for durable memory across conversations. Cloud supports shared workspaces, trusted Agents, and collaboration. Local keeps memory, attachments, FTS5 search, and backups in a SQLite profile on the current device. ## Start here Read the [Quick Start](https://tokst.com/skill-readme.md) before this full guide when installing TokST for the first time. It covers install, authorization, verification, and the first memory command. Return here for Sessions, MCP, Local, team collaboration, and operational rules. ## Public references Use these stable public resources when a client needs installation guidance, API schemas, MCP discovery, or the complete machine-readable documentation: - [TokST documentation](https://tokst.com/docs) - [TokST Agent guide](https://tokst.com/llms.txt) - [TokST full Agent context](https://tokst.com/llms-full.txt) - [TokST OpenAPI contract](https://api.tokst.com/openapi.json) - [TokST MCP manifest](https://api.tokst.com/.well-known/mcp) ## Install once macOS and Linux: ```bash curl -fsSL https://tokst.com/install.sh | bash tokst setup tokst version --verbose tokst status tokst doctor ``` Windows PowerShell: ```powershell irm https://tokst.com/install.ps1 | iex tokst setup ``` The standalone installer supports macOS, Linux, and Windows. It requires curl or PowerShell and does not require Bun, Node.js, npm, or a package manager. `tokst atlas bind` is optional. Bind a directory when it permanently belongs to one Atlas; searches and context otherwise cover all accessible memory. ## Install this Skill Place this document as `SKILL.md` in the client Skill directory. The same workflow works with MCP-only clients even when they have no Skill directory. | Client | Skill directory | |---|---| | Claude Code | `~/.claude/skills/tokst-memory/` | | Codex | `~/.codex/skills/tokst-memory/` | | Cursor / Windsurf | `~/.cursor/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/` | | Generic | `~/.agents/skills/tokst-memory/` | For a repository-specific integration, generate the matching Agent guidance: ```bash tokst init --agents codex,claude,cursor,opencode,pi ``` ## Cloud and Local profiles ### Cloud Cloud operations use your TokST account and workspace permissions. ```bash tokst context --json tokst search "previous deployment decision" --json ``` Run `tokst setup` for browser authorization. CI and unattended environments can use a dedicated API key: ```bash tokst login --key tk_live_your_api_key ``` ### Local Local data stays on this device. Start with a default local workspace and Atlas. ```bash tokst setup --local tokst local remember "Private research note" --type note --tags private --json tokst local search "research" --json tokst local backup create --name before-change ``` Cloud sync is explicit. Bind one Local Atlas to one Cloud Atlas; content and metadata synchronize, attachments remain local, and concurrent changes remain separate memories. ```bash tokst local connect --cloud-atlas-id tokst local sync ``` ## Agent operating rules 1. Read context before substantial work. 2. Search before repeating decisions or recommendations. 3. Capture only confirmed long-term knowledge. 4. Keep secrets, credentials, raw reasoning, and temporary tool output outside TokST. 5. Archive superseded memories so history remains traceable. ```bash TOKST_AGENT=1 tokst context --limit 20 --json TOKST_AGENT=1 tokst search "authentication design" --json TOKST_AGENT=1 tokst remember "Use PKCE for OAuth authorization." \ --type decision --tags auth,oauth --source-type agent --source codex --json ``` Use `--json` for machine-readable output. `TOKST_AGENT=1` or `--agent` gives Agent subprocesses compact, bounded output. | Memory type | Use | |---|---| | `fact` | Stable facts | | `decision` | Approved choices and rationale | | `preference` | Durable preferences | | `task` | Open work | | `architecture` | System design | | `note` | Other durable context | Use the same compact structure across dashboard, CLI, MCP, and REST: facts use Conclusion / Source / Scope; decisions use Decision / Context / Rationale / Impact; tasks use Goal / checklist / Done when; architecture uses Goal / Components / Data flow / Constraints. Long CLI content can be supplied with `tokst remember --type decision --stdin < decision.md`. ## Reliability and recovery rules At the first Cloud operation in a new environment, verify the installation and saved authorization before attempting memory writes. ```bash tokst doctor --json tokst connection test --json tokst status --json ``` When a command fails, preserve the output and use the matching recovery path. Retry only an operation that is safe to repeat. | Failure | Agent action | |---|---| | `TIMEOUT`, a temporary network error, or a `5xx` response | Retry a read once. For a write with an unknown result, search or inspect the Session first to avoid a duplicate. | | `429` or a quota response | Read `Retry-After` when supplied; wait for that duration, then retry once. Use `tokst status --json` to inspect remaining quota. | | `UNAUTHORIZED` or expired browser approval | Run `tokst setup` in an interactive terminal, or replace the dedicated API key in the client configuration. | | Permission or plan rejection | Confirm the workspace, Atlas, role, and limits with `tokst status --json`. Escalate the required access change to a workspace Owner or Admin. | | Local profile or storage failure | Update the CLI, create a backup, then inspect Local status before another write. | Use `--json` for tool-driven calls. A JSON failure includes a machine-readable code and a `retryable` signal for timeout cases. Session starts accept `--idempotency-key`; Session captures accept `--source-event-id` for stable event de-duplication. For other interrupted writes, confirm the prior result before repeating the mutation. ## Session memory Use a Session for multi-step work or a handoff. A Session starts with scoped context, records confirmed candidates, saves checkpoints, and finalizes a snapshot. Finalize compiles candidates into formal memories unless `--no-compile` is supplied. ```bash TOKST_AGENT=1 tokst session start --atlas-id --task "Implement OAuth callback" --json TOKST_AGENT=1 tokst session capture --session \ "Use PKCE and validate the redirect URI." --kind decision --tags auth,oauth --json TOKST_AGENT=1 tokst session checkpoint --session "Callback validation is complete." --json TOKST_AGENT=1 tokst session finalize --session "OAuth callback implemented and verified." --json ``` Members can review their own pending candidates with `tokst session candidates --scope mine --status pending`. Owners and Admins can review managed Sessions: ```bash tokst session list --scope managed --json tokst session candidates --scope managed --status pending --json tokst session candidate --session --candidate --action compile --json ``` Local uses the same commands through `tokst local session ...`. ### Automatic Memory TokST Automatic Memory is an opt-in local service. `tokst auto on --agent all` detects WorkBuddy, OpenCode, Pi, Codex, and Claude Code, installs their native bridges, and starts the local service. OpenCode uses a global plugin in the terminal and macOS App; Pi uses a global extension; Codex and Claude Code use TokST-managed Hooks that retain user Hooks. ACP Hosts use `tokst acp proxy`, `tokst acp opencode`, or `tokst acp pi --doctor`. TokST removes sensitive content locally, keeps each native session as an audit trail, and creates one durable Markdown memory for each completed task. Follow-up work updates the matching task memory. Explicit Session capture remains available for important decisions. ```bash tokst auto on --agent all tokst acp proxy -- [args] tokst auto status tokst auto verify --agent all --json tokst auto privacy --retain-raw 0 ``` ### OpenCode Terminal, App, and ACP OpenCode Terminal and the macOS App load the generated global plugin from `~/.config/opencode/plugins/tokst-automatic-memory.ts`. A native OpenCode session, including one resumed with `opencode -s`, maps to the same TokST Session. Task units inside that Session each map to one automatic memory, and follow-up work updates the matching unit. An ACP Host can configure `command: "tokst"` and `args: ["acp", "opencode"]`. ```bash tokst auto on --agent opencode tokst acp opencode --doctor ``` Use `tokst auto repair --agent opencode` to regenerate the global plugin with the current absolute TokST executable path. `tokst acp opencode --repair` repairs ACP Host configuration. Restart the client after bridge installation. `tokst auto status --agent `, `tokst auto verify --agent `, `tokst auto repair --agent `, and `tokst auto logs --agent ` use the same status and diagnostic format for every bridge. Claude Desktop remains MCP-assisted and uses explicit Session tools. ACP clients launch through `tokst acp proxy -- [args]`. Automatic Memory installs a user-level service after enablement. The queue contains sanitized event material and retries safe delivery when the network returns. Raw content is discarded by default; `tokst auto privacy --retain-raw 24h` enables a short local recovery window. MCP and REST retain the explicit Session workflow for clients outside automatic capture. ## MCP setup TokST Cloud MCP exposes 51 tools across memory, files, workspaces, Sessions, automatic memory, trusted Agent identity, and messages. ### Browser-authorized MCP Use with clients that support an OAuth browser flow. ```json { "mcpServers": { "tokst": { "type": "streamable-http", "url": "https://api.tokst.com/mcp" } } } ``` ### Static API-key MCP Use with WorkBuddy, ZCode, Qoder, Kimi, CI, and any static Streamable HTTP MCP client. Create one dedicated key per client in Dashboard API Keys. ```json { "mcpServers": { "tokst": { "type": "streamable-http", "url": "https://api.tokst.com/mcp", "headers": { "Authorization": "Bearer tk_live_your_api_key" } } } } ``` Store API keys only in a protected client setting or environment variable. Never put one in source control, a URL, or a chat transcript. Revoke unused keys from Dashboard API Keys. ### Local stdio MCP ```json { "mcpServers": { "tokst-local": { "command": "tokst", "args": ["local", "mcp"] } } } ``` Run `tokst setup --local` before starting Local MCP. ## Trusted Agents and handoffs TokST assigns trusted calls a stable `agt_...` identity. The `source` field is a readable source label. Use realtime listening for long-running Agent work and durable inbox sync after restarts. Team workspace governance remains explicit. Recipients accept an invitation before membership becomes active. ```bash tokst workspace members --json tokst workspace invite member@example.com --role member --expires-in-days 7 --json tokst workspace invitations --json tokst workspace inbox --json tokst workspace respond --accept --json tokst workspace revoke --confirm --json tokst workspace leave --confirm --json tokst workspace role

--role admin --confirm --json tokst workspace remove

--confirm --json tokst workspace transfer-owner

--confirm --json ``` ```bash tokst agent list --json TOKST_AGENT=1 tokst agent listen --json TOKST_AGENT=1 tokst message inbox --json ``` ## Troubleshooting | Problem | Recovery | Verify | |---|---|---| | `tokst: command not found` | Open a new terminal after installation. | `tokst version --verbose` | | Older command remains after updating | Run `tokst update`, then inspect source and PATH. | `tokst doctor`; zsh/bash: `tokst doctor --fix-path` | | Browser authorization fails | Keep the initiating terminal open and rerun `tokst setup`; unattended clients use a dedicated key. | `tokst connection test` | | MCP tools do not appear | Restart the MCP client after authorization or configuration. | `https://api.tokst.com/mcp` | | Static MCP is unauthorized | Check the `Authorization: Bearer tk_live_...` header and key status. | `tokst login --key tk_live_your_api_key` | | Cloud write is rejected | Check workspace, role, plan, and quotas. | `tokst status` | | Local write fails | Update, make a backup, then collect profile status. | `tokst update && tokst local backup create --name before-repair && tokst local status --json` | | Agent listener reconnects | Read the durable inbox after recovery. | `tokst message inbox --json` | Cloud operations require access to `api.tokst.com`. Local mode remains usable on the current device and can synchronize later through an explicit Atlas binding. ## Common questions **Where should I start?** Read the Quick Start, run `tokst setup`, then verify with `tokst doctor` before giving an Agent memory instructions. **Does TokST store every conversation automatically?** Automatic memory is opt-in. An ACP-connected Agent compiles a completed session into one reversible formal memory after local redaction. Explicit Session capture records critical confirmed information for every MCP and REST client. **Which content belongs in memory?** Store confirmed facts, decisions, preferences, tasks, architecture changes, and handoffs. Keep credentials, private keys, raw reasoning, and temporary tool output outside TokST. **How do I repair a failed command?** Use the recovery table above, then consult the Help Center for a guided resolution. ## References - https://tokst.com/docs - https://tokst.com/help - https://tokst.com/docs/mcp - https://tokst.com/docs/sessions - https://tokst.com/docs/local