# Memory and reference (/docs/agent-orchestrator/memory-and-reference)

## Long-term memory [#long-term-memory]

The board is working memory. Durable knowledge (decisions, results, notes,
questions, review handoffs, task outcomes, reopen feedback) is additionally
distilled into a per-project brain by a detached background worker. The brain
is powered by the AISquare `gbrain` CLI (a separate, optional tool, not the
unrelated `gbrain` package on public npm). It never runs on the hot path, and
when `gbrain` is not installed the layer simply stays off; nothing else
changes.

```sh
aisquare recall "what did we decide about auth?"   # search the brain
aisquare team distill                              # drain the pipe into it now
aisquare team distill --all                        # backfill from the beginning
aisquare doctor                                    # includes brain health + lag
```

`recall` drains any undistilled backlog before searching, so the first recall
on a busy project initialises the brain and takes a few seconds; after that it
is instant. Brains are created with embeddings off; set
`AISQUARE_BRAIN_EMBED=1` if you want distilled pages embedded (uses your
`OPENAI_API_KEY`, only at distill time).

## Environment knobs [#environment-knobs]

The orchestrator is configured per session through the environment, nothing
else:

| Variable                                                                | Effect                                                           |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `AISQUARE_ROLE`                                                         | role for this session; also activates orchestration for the repo |
| `AISQUARE_TEAM=0`                                                       | master off switch (hooks and commands no-op)                     |
| `AISQUARE_TEAM_HUB`                                                     | pin sessions from several repos onto one shared board            |
| `AISQUARE_TEAM_DELTA=0`                                                 | mute per-prompt teammate deltas for a heads-down session         |
| `AISQUARE_TEAM_LEASE_MIN`                                               | claim lease in minutes (default 120)                             |
| `AISQUARE_BRAIN=0`                                                      | disable the gbrain layer entirely                                |
| `AISQUARE_BRAIN_EMBED=1`                                                | allow embedding of distilled pages                               |
| `AISQUARE_SERVE_CLIENT` / `AISQUARE_SERVE_ROLE` / `AISQUARE_SERVE_PORT` | identity and port for `aisquare serve`                           |

## Command map [#command-map]

```
aisquare team    on · status · focus <text> · role <name> · log · distill [--all]
aisquare task    add · list · show · next · claim · review · reopen · done
                 block · drop · release          (all accept --as <session>)
aisquare note "<text>" [--task T] [--to ROLE] [--kind decision|question|result]
aisquare board [-w]  ·  aisquare recall "<query>"
aisquare serve [--stdio | --port N] [--show-token]
aisquare agents connect claude-code [--config-dir DIR]
```

Every command honours `--json` for scripting.

## Troubleshooting [#troubleshooting]

| Symptom                                      | Cause and fix                                                                                                                                                                                        |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Board says "quiet here"                      | You are in a different project than the sessions. Export `AISQUARE_TEAM_HUB` in this shell, or run from the repo the team was launched in.                                                           |
| Sessions never appear                        | Hooks load at Claude startup: relaunch sessions started before `agents connect`. `aisquare doctor` confirms hook health per config dir.                                                              |
| Doctor: "hooks are missing or outdated"      | An older install predates some lifecycle hooks. Re-run `aisquare agents connect claude-code` (per `--config-dir` if you use several).                                                                |
| A session shows stale                        | It has not heartbeat in 30+ minutes. Its claims self-release when the lease expires; the row disappears once it ends.                                                                                |
| An agent says done but the task is in review | Saying is not doing: a task closes only when `aisquare task done` actually runs. Check `aisquare team log`; if there is no `task_done` event, tell the agent to execute the command, not narrate it. |
| `recall` says the brain is unavailable       | `gbrain` is not on PATH, or another distill holds the brain briefly. Install gbrain, or retry in a few seconds.                                                                                      |