CellCog Memory System & Context Trees Guide

CellCog uses a general-purpose memory system called Context Trees to give AI agents persistent knowledge across conversations. This guide explains how it works and how to use it effectively.

What Are Context Trees?

A Context Tree is a hierarchical document store — think of it as an organized knowledge base that both you and AI agents can read from and write to.

Context Trees are a core building block of CellCog. The same memory system is used in multiple places across the platform, and it's also exposed to external agents via the OpenClaw Python SDK.

Where Context Trees Are Used

Key point: All document stores — project, agent role, and organization — are two-way. Both humans and agents can read from and write to them. Humans manage documents through the UI; agents manage them through their built-in context tree tools.

How Agent Role Memory Works

This is the most powerful and often misunderstood feature. Here's exactly what happens:

What Is an Agent Role?

An agent role is a repeatable role assignment you create within a project. It has:

• Title: e.g., "Episode Producer," "Marketing Analyst," "Solution Architect"
• Description: What this agent does
• Instructions: Specific guidelines for how the agent should behave

Agent roles serve two purposes:

1. Save you from repeating instructions — Instead of pasting the same instructions every chat, you define them once as a role
2. Give the agent its own persistent memory — Each agent role gets its own private document store (context tree) that it maintains automatically

The Automatic Memory Process

When you start a chat linked to a project and an agent role, here's the lifecycle:

1. Chat starts — The agent loads its context tree memory from previous sessions, plus all project documents
2. You work together — The agent generates artifacts (reports, code, images, analysis, etc.)
3. Chat goes idle — After approximately 45 minutes of inactivity, a background process kicks in
4. Memory update — The agent reviews what happened in the session and stores relevant artifacts and learnings into its own context tree
5. Next session — When you start a new chat with the same agent role, it loads its updated memory and "remembers" previous work

This is the only place in CellCog where long-term memory is automatically maintained. Only chats with an assigned agent role trigger this background memory process. Regular chats (without an agent role) do not have this automatic memory.

You can also manually trigger a memory update at any time via the chat header menu (⋮ → Update Agent Memory).

What Goes Where: Project vs Agent Memory

Not everything should go into agent memory. The key distinction:

• Project documents → Core assets and deliverables that any agent in the project might need. Think: brand guidelines, product specs, datasets, character designs, completed deliverables.
• Agent role memory → Things specific to that agent's experience. Think: learnings from past sessions, process notes, mistakes to avoid, intermediate analysis, agent-specific templates.

Example: In a "Mini Pirates Series" project with an "Episode Producer" agent role:

• Project documents: Character designs, series bible, completed episode scripts, artwork assets — because a future "Marketing Agent" role would also need these
• Episode Producer memory: Production notes about pacing preferences you've given, continuity details the agent tracked across episodes, editorial decisions, lessons learned about what styles you prefer

Walkthrough: Episode Producer

Here's a concrete example of how agent role memory works in practice:

Chat 1 — Episode 1: You create a project "Mini Pirates Series" and an agent role "Episode Producer." You describe the series concept and ask the agent to produce Episode 1. It researches pirate themes, writes the script, generates character designs, and creates scene artwork. After the chat goes idle, the agent stores Episode 1's script and story notes into its memory, while the core character designs and finished episode go into project documents.

Chat 2 — Episode 2: You start a new chat with the same "Episode Producer" role. The agent loads its memory — it knows Episode 1's storyline, the characters, your feedback about pacing. You say "produce Episode 2." It picks up where it left off, maintaining continuity.

Chat 6 — Episode 6: By now, the agent has deep memory of the entire series arc: recurring characters, plot threads, your style preferences, what worked and what didn't. Each new episode builds naturally on everything before it.

Human Involvement in Memory

The automatic memory process works well in many cases, but it's not perfect. Every agent role may need different kinds of memories depending on the work:

• A research analyst might need to remember methodology decisions and source quality assessments
• A code architect might need to remember design patterns and technical debt notes
• A content creator might need to remember brand voice decisions and audience feedback

Sometimes the agent's automatic memory choices are exactly right. Other times, you may want to step in and curate what gets stored. You can do this by:

1. Uploading documents directly to the agent role's document store via the project's "Agent Documents" tab
2. Instructing the agent during the chat to store specific things: "Remember that we decided to use a dark color palette for all future episodes"
3. Reviewing agent memory in the project's Agent Documents tab and removing irrelevant items

Think of it like managing a team member's notes — sometimes they take great notes on their own, sometimes you need to guide what's important to remember.

Project Documents: Shared Knowledge

Project documents are the foundation of team knowledge in CellCog.

How They Work

1. Go to your project → Documents tab
2. Upload files (PDF, images, code, spreadsheets, audio, video, markdown, etc.)
3. Add optional context descriptions to help agents understand each file

Automatic Availability

When you start a chat linked to a project, all project documents are automatically available to the agents. You don't need to attach them to each chat — they're always there.

This is different from chat attachments, which only exist for that single chat.

Who Can Manage Project Documents

• Humans: Upload, delete, and organize via the project UI
• Agents: Can store deliverables and artifacts to project documents via their built-in tools (e.g., when an agent produces a final report, it can save it to the project)

Organization Documents: Company-Wide Knowledge

If you have an organization set up, you can upload company-wide documents that are available across all projects.

How They Differ from Project Documents

Management

Like project documents, organization documents are a two-way store — both humans (via UI) and agents (via tools) can manage them.

Choosing the Right Document Store

For OpenClaw Developers: Context Trees via SDK

The same context tree system that powers CellCog's internal agents is available to OpenClaw agents through the Python SDK.

The SDK includes full project, document, and context tree management. This means your OpenClaw agents can:

• Create and manage projects
• Upload and organize documents in project context trees
• Read from context trees to inform their work
• Use the same memory structures that power CellCog's internal agents

Install the project-management-cellcog ClawHub skill for full context tree management:

bash
clawhub install project-management-cellcog

See the OpenClaw Integration Guide for setup details and the project-management-cellcog skill documentation for the full API.

Frequently Asked Questions

Do I need to attach project documents to every chat?

No. When you start a chat linked to a project, all project documents are automatically available to agents. You only need to attach files for one-off references not in the project.

How do I see what an agent role has stored in its memory?

Go to your project → Agent Documents tab. You'll see files organized by agent role.

Can I delete things from an agent's memory?

Yes. Go to the project's Agent Documents tab, find the file, and delete it. You're in full control of what agents remember.

Does the agent always make good memory decisions?

Not always. The agent takes its best guess about what's important to remember, but different tasks require different memory strategies. You may need to guide the agent or curate its memory manually for best results.

What's the difference between agent role instructions and agent role memory?

Instructions are static guidelines you write (e.g., "always use formal tone"). Memory is a dynamic document store that grows over time as the agent works on tasks. Instructions tell the agent how to behave; memory gives the agent what to reference.

Can two different agent roles in the same project see each other's memory?

No. Each agent role has its own private context tree. However, all agent roles in a project can see the shared project documents. This is by design — project documents are the shared layer, agent memory is the private layer.

Is the memory system the same one used by the OpenClaw SDK?

Yes. Context Trees are a general-purpose memory system used across CellCog — for projects, agent roles, organizations, and the OpenClaw SDK. It's the same underlying system everywhere.

Related Guides

• Projects Guide — Creating projects and managing documents
• Chat Guide — Chat modes and features
• OpenClaw Integration Guide — Using CellCog with external agents
• Getting Started — Platform overview