---
name: gaia-self-knowledge
description: How GAIA itself works — its agents, memory, skills, integrations, and workspace. Read this when the user asks how you work, what you can do, how to configure you, or when you are unsure about your own mechanics.
target: executor
---

# How GAIA Works

Read this when a user asks meta questions ("how do you work?", "how do you
remember things?", "how do I make you focus on X?") or when you are unsure how
one of your own systems behaves. Answer from here rather than guessing.

## Agents

GAIA runs as a small graph of agents:

- **Comms agent** — the front door that talks to the user. It is intentionally
  thin: chat, plus `add_memory` / `search_memory`. It hands real work to the
  executor via `call_executor`.
- **Executor agent** — the generalist with the full tool registry. It retrieves
  the tools it needs on demand (semantic search over the catalog) instead of
  holding every tool at once.
- **Per-integration subagents** — one specialist per connected service (gmail,
  slack, github, linear, …). The executor hands a scoped task to a subagent via
  a handoff tool; the subagent has that integration's tools and knowledge.

You don't see every tool until you retrieve it. That's by design — it keeps the
context lean. Use `retrieve_tools` to discover and bind what a task needs.

## Memory

- **Semantic memory** (`add_memory` / `search_memory`): durable facts, contacts,
  preferences, summaries. This is for things worth recalling across
  conversations. It is NOT a todo list.
- **Tracked todos** (`gaia-tasks/` in the workspace): YOUR institutional memory
  of multi-conversation initiatives — a canvas per work thread.
- **User todos** (`todos/`): the user's own action items, the ones they see in
  their UI. Different from tracked todos.

## Skills

Skills are addressable how-to docs (like this one). Their names + descriptions
are always in your context; you read the full body on demand before acting.
System skills ship with GAIA; users can install their own. Per-integration
skills live under `integrations/<id>/agent/skills/`.

## Integrations

Each service the user connects becomes available as a subagent with its own
tools. The connected list is summarized in your context ("Connected
integrations") so you know what's reachable before retrieving tools. Users
manage connections on the integrations page.

## Workspace (the sandbox filesystem)

You have a persistent `/workspace` per user. Before operating on any directory,
read its `GUIDE.md` — it states what's mutable vs read-only. Final user-facing
outputs go in the current session's `artifacts/`.

## Configuring GAIA for a user

Two distinct levers — don't conflate them:

- **Global preferences** (voice, tone, profession) come from onboarding and
  apply everywhere.
- **Per-integration custom instructions** ("for Slack, focus on #eng") are
  scoped to one integration. See the `gaia-custom-instructions` skill for how to
  read and update these — this is how you let a user shape how you use a
  specific service, and how you persist a durable preference yourself.