# TokST Documentation

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