
Cognee Memory for BAND Agents
BAND is where agents and humans work together: agents you run yourself connect to BAND and share rooms with people and other agents. You build them with the BAND Python SDK by giving an Agent an adapter that holds your LLM logic (Anthropic, LangGraph, CrewAI, Pydantic AI, and others). For BAND’s own take on why agents need to remember, read Agents that talk now remember.
On their own, BAND agents keep nothing between rooms or restarts. cognee-integration-band fixes that with a single wrapper, CogneeMemoryAdapter, which connects your adapter to a cognee knowledge graph, which it can share with the cognee plugins for Claude Code and Codex.
- Package:
cognee-integration-band(imports ascognee_band) - Repository: topoteretes/cognee-integrations, path
integrations/band/ - Requires: Python 3.11 or later,
band-sdk6.0.1 or later, a reachable cognee server
What you get
- Auto-recall. Relevant memory is added below each room message before your adapter sees it.
- Auto-capture. Each question and the reply your adapter sent are stored, in the background.
- Consolidation. When a room closes or the agent stops, the room’s session is turned into graph memory by cognee’s
improvepipeline. - Explicit tools. Optionally, the model gets
cognee_searchandcognee_remember. - Fails safe. If cognee is down, your agent answers exactly as it would without memory.
Before you start
You need three things:
- A BAND agent. Create one at app.band.ai/agents. Keep its agent id and API key.
- A cognee server. cognee Cloud, self-hosted, or local. The integration is a thin client and does not start one for you.
- A model provider key for the adapter you use, for example
ANTHROPIC_API_KEY.
Item 3 is not covered by cognee: the model key belongs to your BAND adapter. For item 2, the integration needs COGNEE_BASE_URL and COGNEE_API_KEY (see Configure).
Install
Pick the band-sdk extra matching the adapter you plan to wrap. The memory package depends only on band-sdk, and its cognee client uses the standard library.
Working from a clone of the repo instead:
Configure
Point at your cognee server once, in ~/.cognee/.env:
This is the same file the Claude Code and Codex plugins read, but check that both values are set. A plugin running in local mode keeps its API key outside this file, and recent cognee versions require a key even on localhost. To get a key for a local server, create one with the server’s API-key endpoint (POST /api/v1/auth/api-keys), authenticated as your user, then add it here. If the server is local and no key is set, the agent logs a warning at startup and runs without memory.
Precedence is exported env vars, then ~/.cognee/.env, then defaults. A shell export always wins, which is what you want in CI and containers.
Settings
| Variable | Default | Effect |
|---|---|---|
COGNEE_BASE_URL | http://localhost:8011 | cognee server URL |
COGNEE_API_KEY | unset | sent as the X-Api-Key header |
COGNEE_BAND_DATASET | band_sessions | dataset to read and write. The plugins’ COGNEE_PLUGIN_DATASET is ignored |
COGNEE_RECALL_TOP_K | 5 | results per recall (at most 10) |
COGNEE_ENV_FILE | ~/.cognee/.env | override the config file location |
Running cognee locally on the default port needs no configuration at all.
BAND credentials
Keep these in your shell, not in the cognee env file:
Wrap your adapter
One line:
CogneeMemoryAdapter(inner) with no other arguments resolves settings from the environment.
Your adapter, prompts, and framework do not change. The wrapper accepts any band-sdk adapter built on SimpleAdapter, which covers every built-in adapter. It composes your adapter the same way band-sdk’s own SlackAdapter does: your adapter keeps its features, model selection, control handling, and resource cleanup, and the BAND runtime starts and stops it exactly as it would unwrapped.
With explicit memory tools
To let the model also make deliberate memory calls, build one client and share it:
Sharing one settings object and one client keeps the tools and the wrapper on the same dataset.
The prompt section is optional. The injected block already says it was not written by the sender, and the section only tells the model how to use it. cognee_tools works with any adapter that accepts additional_tools, including Anthropic, Claude Agent SDK, LangGraph, Pydantic AI, CrewAI, Gemini, Google ADK, and Strands.
Run the example
examples/memory_agent.py is a full working agent with memory and tools. Its docstring lists every credential it needs, and its inline script metadata installs band-sdk and this package for you.
Verify it works
Check startup. With logging on you should see:
A wrong server shows up here, not three turns later.
Check the round trip.
- In a room: “Remember that the staging database migration is owned by Ravit.”
- Close that room, or wait a minute for cognee to finish building the graph in the background.
- In a new room: “Who owns the staging migration?”
Use a new room. Same-room recall could just be conversation history.
Check the cross-harness path. Tell the cognee Claude Code plugin a fact in a terminal session, let it sync, then ask your BAND agent in a room. The plugin writes to agent_sessions by default, so start the agent with COGNEE_BAND_DATASET=agent_sessions and the answer comes back. This is the demo worth showing someone.
What happens on every turn
| When | What happens |
|---|---|
| Agent starts | your adapter starts as usual, then the active dataset and server are logged |
| A text message arrives | recalls context and adds it below the message as a delimited <cognee_memory> block |
| Your adapter replies | stores the sender’s question and the reply as a QA pair, in the background |
| A room closes | waits for that room’s pending writes, then bridges its session into the graph via cognee’s improve pipeline |
| The agent stops | your adapter shuts down, pending writes drain, then every still-open room is bridged |
Each BAND room maps to one cognee session named band-<room id>. Room ids are UUIDs, so in cognee you will see sessions like band-3f1c2a9e-…. A room becomes durable memory instead of a transcript that disappears.
Graph building runs in the background on the cognee server, so a fact becomes recallable from other rooms shortly after the room is bridged, not instantly.
Some messages pass through untouched and are never stored:
- non-text events (
tool_call,thought, and others) - slash commands such as
@bot /model gpt-5, so the adapter still parses them - BAND’s own system notices, such as contact requests
A turn that ends without a reply (for example band_no_reply, or an adapter error) is not stored either.
Turns that wait on an approval (Codex, Claude Agent SDK, Cursor, OpenCode) are stored once the reply is sent, not when the turn is parked. Codex and Claude Agent SDK report when the turn ends. Cursor and OpenCode do not, so their turn is stored at the room’s next message or when the room closes, with whatever reply was sent by then.
Recall reads the knowledge graph only, not the room’s own session, which your adapter already has in its history. Each result is cut down to the retrieved context, and the whole block is capped at about 8,000 characters (CogneeSettings.max_memory_chars).
What the model sees
Your adapter attributes the whole text to the sender (for example [alice]: what's left…), so the block says who did write it. The block also stays in your adapter’s conversation history for the life of the room.
When recall finds nothing, nothing is injected and the model sees only the original message.
Choosing your memory scope
COGNEE_BAND_DATASET is the isolation control. Recall reads exactly one dataset, so it is a hard boundary.
| You want | Set |
|---|---|
| One shared brain across all BAND agents | leave the default band_sessions |
| One shared brain with the Claude Code and Codex plugins | agent_sessions, the plugins’ default |
| Isolation per team or product | one dataset name per team |
| Full isolation per agent | one dataset name per agent |
Decide before agents start writing. Moving content between datasets afterwards is a cognee-side job, not something the integration does.
Recalled memory goes into the model prompt. Whatever is in the dataset can reach your model provider, so pick a shared dataset deliberately.
Troubleshooting
TypeError: CogneeMemoryAdapter wraps a band-sdk SimpleAdapter
You passed something other than a band-sdk adapter instance, or an adapter from band-sdk older than 6.0.1. Upgrade with pip install -U "band-sdk>=6.0.1".
Nothing is recalled
Check for a warning on the cognee_band logger or a [cognee-band] line on stderr. The integration is quiet in normal operation and loud on failure. No warning means the server searched and found nothing, which is expected on a cold dataset or right after a room was bridged.
server unreachable at ...
Transport failure. Check that COGNEE_BASE_URL is reachable from the agent process. Your agent keeps working without memory meanwhile.
unauthorized (HTTP 401) or (HTTP 403)
Set or fix COGNEE_API_KEY. Recent cognee versions enforce auth even on localhost, so a local server may still need a key.
Configuration seems ignored
Env file 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. Check nothing in your shell already exports the same variable, since exports win. Check COGNEE_ENV_FILE is not pointing somewhere unexpected.
TLS or certificate errors
Usually a macOS Python install missing root CAs. Run pip install certifi in the agent environment. The client picks it up automatically.
Turns missing from memory
Turns without a reply are not stored. Replies are captured from both ways an adapter can post one: a direct tools.send_message call, and a band_send_message tool call (the path LLM adapters such as Anthropic, Agno, and Gemini use). An adapter that emits output only through send_event is not captured. Check how your inner adapter sends output.
Memory from a closed room never shows up later
Consolidation runs through cognee’s improve pipeline when the room closes or the agent stops, in the background server-side. Give it time. Also confirm the agent shut down cleanly, since that is what bridges rooms that were still open.
Slower first response
Recall runs before your adapter sees the message and is the only memory operation on the critical path. The default timeout is 20 seconds. Lower it if you would rather drop memory than wait:
Advanced
Override settings in code
Any field on CogneeSettings can be overridden. Explicit overrides beat both the environment and the config file.
Run tests
The tests run against the real band-sdk types and runtime startup and disposal functions, so a band-sdk change that affects the wrapper fails here first.
For Claude Code users
BAND’s Jam Desktop bridges local Claude Code sessions onto BAND. Those are real Claude Code sessions, so the existing cognee Claude Code plugin already gives them memory. This package is for agents you build on the BAND SDK directly.
FAQ
Answers to the most common questions from this guide.
Does this work with my framework?
Yes, if your adapter is a band-sdk adapter built on SimpleAdapter, which every built-in adapter is. The wrapper composes it the way band-sdk’s own SlackAdapter does, so the BAND runtime runs your adapter’s full startup and cleanup.
What if cognee goes down?
Your agent answers exactly as it would without the wrapper. Every memory failure is logged and swallowed.
Does memory slow the agent down?
Writes do not. They run in the background, off the event loop. Recall does add latency before the turn starts, since the result is needed before your adapter runs.
Is my content sent anywhere new?
Question and reply text goes to your cognee server, and recalled memory goes into the prompt sent to your model provider. With both BAND and cognee self-hosted, nothing leaves your network except the model provider call your adapter was already making.
Are tool calls remembered?
Not currently. Only text messages get memory treatment. The client has a store_trace method for this, but the adapter does not drive it yet.
Links
Related reading



Cognee is the fastest way to start building reliable Al agent memory.



