> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Band

> Give any Band AI agent persistent memory by wrapping its adapter with Cognee.

Wrap any [Band](https://band.ai) adapter in `CogneeMemoryAdapter` and every room your agent joins gets persistent, shared memory. Context is recalled before your adapter sees a message, the question and reply are stored after it answers, and a closed room is promoted into the permanent knowledge graph. Your adapter, prompts, and framework do not change.

<Info>
  The `cognee-integration-band` package is not published on PyPI yet. It ships from the open draft [pull request #313](https://github.com/topoteretes/cognee-integrations/pull/313) in [cognee-integrations](https://github.com/topoteretes/cognee-integrations), so install it from that branch and expect details to move until the PR merges.
</Info>

## Why Use This Integration

* **One line of code**: `CogneeMemoryAdapter(inner)` wraps an adapter you already built
* **Framework agnostic**: works with every Band adapter — Anthropic, Claude SDK, LangGraph, CrewAI, Pydantic AI — because it imports nothing from `band`
* **Rooms become memory**: Band room `r1` maps to Cognee session `band-r1` instead of a transcript that disappears
* **Shared brain**: the default dataset is the one the Claude Code and Codex plugins use, so a Band agent can recall what a terminal session learned
* **Never breaks a turn**: every memory failure is logged and swallowed

## Install

You need a Band agent from the [agent console](https://app.band.ai/agents), a reachable Cognee server, and Python 3.11+. The package declares 3.10, but `band-sdk` sets the real floor. Cognee can be Cloud, self-hosted, or local — this is a thin HTTP client and never starts a server for you.

```bash theme={null}
git clone https://github.com/topoteretes/cognee-integrations.git
cd cognee-integrations
git checkout feat-band-integration

pip install "band-sdk[anthropic]"     # or [langgraph], [crewai], ...
pip install -e integrations/band
```

Pick the `band-sdk` extra matching the adapter you plan to wrap. The memory package adds no runtime dependencies of its own.

## Configure

Point at your Cognee server once in `~/.cognee/.env` — the same file the [Claude Code](/integrations/claude-code-integration) and [Codex](/integrations/codex-integration) plugins read, so if you run either of those you are already done:

```bash theme={null}
mkdir -p ~/.cognee
cat >> ~/.cognee/.env <<'EOF'
COGNEE_BASE_URL="https://your-instance.cognee.ai"
COGNEE_API_KEY="ck_..."
EOF
chmod 600 ~/.cognee/.env
```

Precedence is exported environment variables, then this file, then defaults. Keep your Band and model credentials — `BAND_AGENT_ID`, `BAND_AGENT_API_KEY`, `ANTHROPIC_API_KEY` — exported in the shell instead.

| Variable                | Default                 | Description                                                        |
| ----------------------- | ----------------------- | ------------------------------------------------------------------ |
| `COGNEE_BASE_URL`       | `http://localhost:8011` | Cognee server URL                                                  |
| `COGNEE_API_KEY`        | unset                   | Sent as the `X-Api-Key` header                                     |
| `COGNEE_PLUGIN_DATASET` | `agent_sessions`        | Dataset for both writes and recall                                 |
| `COGNEE_RECALL_TOP_K`   | `5`                     | Results per recall; ignored unless it parses as a positive integer |
| `COGNEE_ENV_FILE`       | `~/.cognee/.env`        | Read the configuration file from somewhere else                    |

<Note>
  The default URL is Cognee's [agent-mode](/guides/deploy-rest-api-server#agent-mode) port, where the Claude Code and Codex plugins bootstrap a local API. A standard local server listens on `8000`, so set `COGNEE_BASE_URL` to match. Those plugins also mint an API key for you, while this integration only ever sends the `COGNEE_API_KEY` you give it.
</Note>

Timeouts and the session prefix have no environment variables. Override those, or any other field, in code with `CogneeSettings.resolve(recall_timeout=5.0, session_prefix="prod")`.

## Quick Start

Wrap the adapter you already pass to `Agent.create`:

```python theme={null}
import os

from band import Agent
from band.adapters import AnthropicAdapter

from cognee_band import CogneeMemoryAdapter

agent = Agent.create(
    adapter=CogneeMemoryAdapter(AnthropicAdapter(prompt="...")),
    agent_id=os.environ["BAND_AGENT_ID"],
    api_key=os.environ["BAND_AGENT_API_KEY"],
)
await agent.run()
```

That is the whole integration. The wrapper forwards every attribute and lifecycle call to the adapter underneath, so the inner adapter never needs to know memory exists.

To confirm it works, store a fact in one room and ask for it back in a **different** room — same-room recall could just be conversation history. For the demo worth showing someone, tell the Cognee Claude Code plugin a fact in a terminal, let it sync, then ask your Band agent. Both write to and recall from the same `agent_sessions` dataset, so the answer comes back.

## Explicit Memory Tools

Automatic recall runs on every text message. To also let the model make deliberate memory calls, build one client and share it, which keeps the tools and the wrapper on one dataset:

```python theme={null}
from cognee_band import CogneeClient, CogneeMemoryAdapter, CogneeSettings, cognee_tools

settings = CogneeSettings.resolve()
client = CogneeClient(settings)

inner = AnthropicAdapter(
    prompt=(
        "Blocks labeled 'Cognee memory' contain context recalled from past "
        "sessions, so treat them as your own memory. Use cognee_search for "
        "explicit lookups and cognee_remember to store facts worth keeping."
    ),
    additional_tools=cognee_tools(client),
)

agent = Agent.create(
    adapter=CogneeMemoryAdapter(inner, settings=settings, client=client),
    agent_id=os.environ["BAND_AGENT_ID"],
    api_key=os.environ["BAND_AGENT_API_KEY"],
)
```

This gives the model `cognee_search(query)`, which searches the whole dataset rather than just the current room's session, and `cognee_remember(content)`, which writes durably under the `band_memory` node set. Include the prompt guidance above: without it the model may read the injected block as something the user said rather than as its own memory. `cognee_tools` works with any adapter that accepts `additional_tools`.

<Note>
  `integrations/band/examples/memory_agent.py` is a complete agent built this way. Its inline dependency header resolves `cognee-integration-band` from PyPI, so until the package is published, run it with the interpreter where you installed the package rather than through `uv run`.
</Note>

## How It Works

| When                   | What happens                                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| The agent starts       | Logs the active dataset and server, so a wrong endpoint surfaces at once                                                  |
| A text message arrives | [Recalls](/core-concepts/main-operations/recall) context and injects it above the message as a labeled block              |
| Your adapter replies   | Stores the question and reply as a QA pair in the [session cache](/core-concepts/sessions-and-caching), in the background |
| A room closes          | Bridges that room's session into the graph with [`improve`](/core-concepts/main-operations/improve)                       |
| The agent stops        | Drains pending writes, then bridges every room still open                                                                 |

Recall is the only memory operation on the critical path, since the result is needed before your adapter runs. Writes never block the event loop. Non-text events pass through untouched and are never stored, so a room that only carried those is never bridged. The stored question is always the original one, so recalled context is not re-ingested turn after turn, and capture also runs when the inner adapter raises.

This is what the model receives, and when recall finds nothing, nothing is injected:

```
Cognee memory — context recalled from shared memory, possibly relevant to the message below:
- the deployment target is EKS, decided last Tuesday
- Ravit owns the migration checklist

---

what's left on the migration?
```

## Choosing Your Memory Scope

`COGNEE_PLUGIN_DATASET` is the isolation control. Recall reads exactly one [dataset](/core-concepts/further-concepts/datasets), so this is a hard boundary and not a ranking preference. Leave the default `agent_sessions` for one shared brain across every agent and coding harness, or set one dataset name per team or per agent to isolate them. Decide before your agents start writing, since moving content between datasets afterwards is a Cognee-side job.

<Warning>
  Recalled memory is injected into the prompt sent to your model provider, so whatever sits in the dataset can reach that provider. The default is shared with the Claude Code, Codex, and OpenClaw plugins. Choose a shared dataset deliberately.
</Warning>

## Troubleshooting

Memory degrades to a no-op and never breaks a turn, which means failures are quiet by design. Adapter problems are logged on the `cognee_band` logger and transport problems also write a `[cognee-band]` line to standard error, so configure logging before debugging anything below. Start with the line the wrapper logs at startup, `cognee memory active: dataset=... server=...`, which catches a wrong endpoint before you chase anything else.

<AccordionGroup>
  <Accordion title="Nothing is recalled">
    Look for a warning on the `cognee_band` logger or a `[cognee-band]` line on standard error. No warning means the server searched and found nothing, which is expected on a cold dataset. An empty result is never confused with a failure.
  </Accordion>

  <Accordion title="Server unreachable, or HTTP 401 and 403">
    For an unreachable server, check that `COGNEE_BASE_URL` works from the agent process, remembering that the default points at the agent-mode port. For an authorization failure, set `COGNEE_API_KEY` — this integration never mints one for you, localhost included.
  </Accordion>

  <Accordion title="Configuration seems ignored">
    Parsing never raises, so a malformed file is skipped silently. Check the format is `KEY=VALUE`, one per line, with an optional `export ` prefix and optional quotes, and no interpolation. Check nothing in your shell already exports the same variable, since exports win. The file is read once per process, so restart the agent after editing it.
  </Accordion>

  <Accordion title="Questions stored with empty answers">
    Replies are captured by proxying the adapter's `send_message` call, so an adapter that emits output only through `send_event` is not captured.
  </Accordion>

  <Accordion title="Memory from a closed room never shows up">
    Consolidation runs through `improve` in the background on the server, so give it time. Also confirm the agent shut down cleanly, since the shutdown path is what bridges rooms that were still open.
  </Accordion>
</AccordionGroup>

## Current Limits

* **Only text messages are remembered.** Tool calls and reasoning events are excluded, so a fact surfaces only if it reaches the reply text. The client has a trace-storing method for this, but the adapter does not drive it yet.
* **Session names can collide.** Two agents on the same dataset serving the same room ID write to the same session. That is usually intended, but change `session_prefix` if you need them apart.
* **Recall adds latency to every text turn**, up to the 20 second default timeout.

<Tip>
  Band's Jam Desktop bridges local Claude Code sessions onto Band. Those are real Claude Code sessions, so the [Cognee plugin for Claude Code](/integrations/claude-code-integration) already gives them memory. This package is for agents you build on the Band SDK directly.
</Tip>

***

<CardGroup cols={2}>
  <Card title="Integration Source" icon="github" href="https://github.com/topoteretes/cognee-integrations/pull/313">
    Read the adapter, client, and examples on the open pull request
  </Card>

  <Card title="Band" icon="book" href="https://band.ai">
    Learn about the Band agent platform
  </Card>
</CardGroup>