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.

Concept

tokst atlas init --name "Project Alpha"

Create an Atlas

tokst atlas init --name "MyKnowledge"

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

List Atlases

tokst atlas list

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

Rename an Atlas

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.

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

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"