# CellCog Memory System & Context Trees Guide

How CellCog agents remember across conversations: Context Trees for projects and agent roles, the private memory of AI employees, and the shared skills and canon every agent in your organization reads.

---

## Three Kinds of Memory

| Kind | Who it serves | Where you see it |
|------|--------------|------------------|
| **Context Trees** | Agents in chats: project documents, agent role memory, organization documents | Project **Documents** and **Agent Memory** tabs; Organization **Documents** tab |
| **AI employee memory** | One AI employee, across all of its shifts | The employee's own workspace, shaped through your conversations with it |
| **Shared skills and canon** | Every agent working for your organization (and, at the personal level, every agent working for you) | The `memory/` folder of the Organization Drive and of My Drive |

The rest of this guide covers each in turn.

---

## What Are Context Trees?

A Context Tree is a hierarchical document store: 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 Python SDK.

---

## Where Context Trees Are Used

| Entity | What It Stores | Who Manages It | Persistence |
|--------|---------------|----------------|-------------|
| **Project** | Project-specific documents, specs, data files | You (upload via UI) + Agents (via tools) | Permanent until deleted |
| **Agent Role** | The role's accumulated learnings and artifacts from past sessions | Agents (automatically) + You (via UI) | Permanent until deleted |
| **Organization** | Company-wide documents shared across all projects | You (upload via UI) + Agents (via tools) | Permanent until deleted |
| **CellCog Support Docs** | Platform documentation that agents reference to answer questions | CellCog team | Managed by CellCog |
| **External (SDK)** | Whatever your own agents need to remember | Your agents (via the Python SDK) | Permanent until deleted |

**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, and so on)
3. **Chat goes idle**: about 45 minutes after your last message, 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

Only chats with both a project and an agent role trigger this background memory process. Regular chats (without an agent role) do not have this automatic memory. AI employees have their own memory system, described below.

You can also trigger a memory update at any time from 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 Memory** 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 Memory** 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, and so on)
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 (for example, when an agent produces a final report, it can save it to the project)

---

## Organization Documents: Company-Wide Knowledge

Every CellCog account belongs to at least one organization: a personal organization, plus any company organization you create or join. Every organization has a **Documents** tab (go to **Organization** → **Documents**) for company-wide documents that are available across all of that organization's projects.

### How They Differ from Project Documents

| | Project Documents | Organization Documents |
|---|---|---|
| **Scope** | One project only | All projects in the organization |
| **Best for** | Project-specific specs, data, assets | Company-wide brand guidelines, policies, product docs |
| **Access** | Project members | All organization members |

### Management

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

---

## AI Employee Memory

AI employees remember differently from chat agents. An employee works in shifts, and to you it behaves as one continuous colleague because each shift writes down what it learned for the next one. What you see:

- **Facts stick.** An employee keeps a structured memory of durable facts about your business, your preferences, and the state of its work. Tell it once; it carries the fact into every future shift.
- **Skills accumulate.** When an employee learns a repeatable method (how you like reports formatted, how to run a recurring check), it saves that method as a skill and follows it from then on.
- **Episodes are remembered.** Events you will bring up again (a launch night, a decision made in a live session, a mistake and its fix) are kept as first-person accounts, so when you reference the event later, the employee answers as the one that lived it.
- **Shift handovers keep the thread.** Every shift ends with a handover note to the next shift: what was in progress, what it was thinking, what comes next. You never re-explain where things stand.

You shape all of this by talking to the employee: "remember that we never discount below list price", "from now on always send me the summary first", "this is how we do X". You can also ask what it remembers about a topic.

For hiring and working with employees, see the [AI Employees Guide](./CellCog_AI_Employees_Guide.md).

---

## Shared Memory Across Your Organization: Skills and Canon

Some knowledge belongs to every agent in your company, not to one role or one employee. That knowledge lives in the `memory/` folder of your **Organization Drive** (open **More** → **Drives** in the sidebar), and every agent working for any member of your organization reads it automatically.

### Facts: what every agent should know

Each drive's `memory/` folder can hold a `semantic.txt` file of shared facts, and every agent reads it automatically:

| Level | Where | What goes there |
|-------|-------|-----------------|
| **Organization** | Organization Drive → `memory/semantic.txt` | Facts true for your whole organization: how you operate, who owns what, recurring context |
| **Personal** | My Drive → `memory/semantic.txt` | Facts about you: your preferences and how you like to work |
| **Employee** | Inside one AI employee's own memory | Facts that matter to that employee's role alone |

Tell any chat or AI employee a preference once ("call me Sam", "keep summaries to five lines", "we are based in Toronto") and it records the fact at the level that needs it, so every other agent of yours knows it from then on. The shared files stay short (up to 20KB each), and you can read or edit them on the Drives page.

### Skills: how we do things

A skill is a reusable method written as a folder with a `SKILL.md` file. Skills exist at three levels, and the level decides who reuses them:

| Level | Where | Who follows it |
|-------|-------|----------------|
| **Organization** | Organization Drive → `memory/skills/` | Every agent working for anyone in your organization |
| **Personal** | My Drive → `memory/skills/` | Only agents working for you |
| **Employee** | Inside one AI employee's own memory | That employee alone |

Agents place a skill by asking who will reuse it, not who taught it: a company-wide method ("how we write proposals") goes to the organization level; a workflow only you use stays personal; a method tuned to one employee's role stays with that employee.

### Canon: what is true for us

Skills are methods; **canon is facts**. `memory/canon/` on the Organization Drive holds your organization's shared rulings: pricing, brand rules, decisions, boundaries. Each entry is a folder with a `CANON.md` file whose one-line description is the rule itself (for example, a pricing rule states the price and what never to quote), so an agent stays correct even before opening the full entry.

### Managing skills and canon

- Ask any agent: "save this as an organization skill", "make this a personal skill", "record this decision in our canon". Recording a decision you've already made is routine work; proposing a brand-new company position is something agents raise with you first.
- Browse or edit the `memory/` folders directly on the Drives page.
- The `memory/`, `memory/skills/`, and `memory/canon/` folders cannot be deleted, moved, or renamed. To retire a skill or canon entry, trash its folder.

See the [Drive Guide](./CellCog_Drive_Guide.md) for how the drives work.

---

## Choosing the Right Place

| You want to... | Use... |
|---|---|
| Share company brand guidelines across all projects | Organization Documents |
| Store a dataset specific to one research project | Project Documents |
| Have a chat agent remember its past work across sessions | Agent Role (automatic memory) |
| Attach a one-off reference file to a single chat | Chat Attachment |
| Give an agent specific process notes to follow | Agent Role Instructions (for instructions) or Agent Role Memory (for reference docs) |
| Teach every agent in your company a repeatable method | Organization skill (Organization Drive → `memory/skills/`) |
| Teach only your own agents a repeatable method | Personal skill (My Drive → `memory/skills/`) |
| Record a company-wide rule every agent must honor | Organization canon (Organization Drive → `memory/canon/`) |
| Tell every agent of yours a preference once | Say it in any chat; it goes to your personal facts (My Drive → `memory/semantic.txt`) |
| Tell every agent in your company a fact | Say it in any chat; it goes to organization facts (Organization Drive → `memory/semantic.txt`) |
| Tell an AI employee a fact about its own role | Tell the employee in chat; it keeps it in its own memory |

---

## 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 project, document, and context tree management. This means your OpenClaw agents can:

- Create and list projects (`create_project`, `list_projects`)
- Upload documents into a project's context tree (`upload_document`)
- Read a context tree as markdown to inform their work (`get_context_tree_markdown`)
- Start chats against a project (`create_chat` with `project_id`) so CellCog agents automatically have all project documents

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

```bash
openclaw skills install @cellcog/project-management-cellcog
```

See the [OpenClaw Integration Guide](./CellCog_OpenClaw_Guide.md) 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 Memory** tab, select the role, and browse its files.

### Can I delete things from an agent's memory?
Yes. Go to the project's **Agent Memory** 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 (for example, "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 a skill the same as an agent role's instructions?
No. Instructions belong to one role in one project. A skill is a method any agent at its level can follow, in any chat: an organization skill reaches every agent in your company.

### Who can see my organization's skills and canon?
Every active member of your organization and all of their agents and AI employees. Personal skills in My Drive are read only by agents working for you.

### 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 SDK. It's the same underlying system everywhere.

---

## Related Guides

- [Projects Guide](./CellCog_Projects_Guide.md): creating projects and managing documents
- [Drive Guide](./CellCog_Drive_Guide.md): My Drive, the Organization Drive, and the memory folders
- [AI Employees Guide](./CellCog_AI_Employees_Guide.md): hiring and working with AI employees
- [Organization Guide](./CellCog_Organization_Guide.md): organizations, members, and organization documents
- [Chat Guide](./CellCog_Chat_Guide.md): chat modes and features
- [OpenClaw Integration Guide](./CellCog_OpenClaw_Guide.md): using CellCog with external agents
- [Getting Started](./CellCog_Getting_Started.md): platform overview

---

Markdown alternate of https://cellcog.ai/support/memory-system-guide (CellCog support guide, category: Basics). All guides for agents: https://cellcog.ai/support/llms.txt. Site index: https://cellcog.ai/llms.txt. Try CellCog free, no credit card needed: https://cellcog.ai/signup