# 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"