kv-storage

# KV Storage Namespaced key/value store inside the swarm SQLite DB. Auto-scoped to your calling context — same string used by `agent_tasks.contextKey`. > **Capability gate**: the `kv-*` MCP tools are only available when your > `CAPABILITIES` includes `kv` (default-on; check `my-agent-info`). The REST > endpoints under `/api/kv/*` are always present on the API server. ## When to use KV | You need… | Use this | Not this | |---|---|---| | Count something in this Slack thread / PR / Linear issue | **KV** (auto-scoped) | memory / agent-fs | | Save a cursor / last-seen state for a recurring schedule | **KV** | swarm_config | | Page-internal counter / vote / state across reloads | **KV** via `swarmSdk.kv` | memory | | Cross-task state in the same conversation | **KV** (auto-scoped to `task:slack:...`) | parentTaskId only | | Secrets, API tokens, OAuth creds | `swarm_config` (encrypted + masked) | **NOT KV** | | Cross-session knowledge for this agent ("how do I…") | `memory_search` / `memory-get` | **NOT KV** | | Files, binaries, long documents | `agent-fs` | **NOT KV** | | Workflow run state | workflow vars (own KV) | **NOT KV** | Rule of thumb: - If a future invocation should *find this without knowing the key* → memory. - If a future invocation will *know exactly which key to read* → KV. - If it has secrets in it → `swarm_config`. - If it's bytes (image, pdf, large doc) → agent-fs. ## Namespacing Namespace is just a string. It mirrors the `contextKey` schema (`src/tasks/con...