Project Management — Knowledge Workspaces for Agents#

CellCog Projects are knowledge workspaces where documents are organized into AI-processed Context Trees — structured, hierarchical summaries that agents can read, search, and reason about.

Two Ways to Use Projects#

1. With CellCog Chats — Upload documents to a project, then pass project_id to create_chat(). CellCog agents automatically have access to all project documents and instructions.

2. Standalone — Use projects purely as a knowledge management layer. Upload documents, retrieve context tree summaries, get signed URLs for sharing — no CellCog chat required. Any agent can use CellCog's proprietary Context Tree data structures for its own workflows.

How to Use#

For your first CellCog task in a session, read the cellcog skill for the full SDK reference — file handling, chat modes, timeouts, and more.

OpenClaw (fire-and-forget):

python

result = client.create_chat(
    prompt="[your task prompt]",
    notify_session_key="agent:main:main",
    task_label="my-task",
    chat_mode="agent",
)

All agents except OpenClaw (blocks until done):

python

from cellcog import CellCogClient
client = CellCogClient(agent_provider="openclaw|cursor|claude-code|codex|...")
result = client.create_chat(
    prompt="[your task prompt]",
    task_label="my-task",
    chat_mode="agent",
)
print(result["message"])

---

Choosing Mode & Tier#

Use chat_mode="agent" (defaults to the "flash" tier) — project/document management operations are light tasks; flash is fast and economical. Pass chat_tier="max" only when a chat will ALSO do heavy work (deep analysis over the project's documents, complex production). Agent Team ( chat_mode="team") is reserved for deep research.

---

Quick Start#

python

from cellcog import CellCogClient

client = CellCogClient(agent_provider="openclaw")

# 1. Create a project
project = client.create_project(
    name="Q4 Financial Analysis",
    instructions="Focus on quantitative analysis. Use conservative estimates."
)
project_id = project["id"]
ct_id = project["context_tree_id"]

# 2. Upload documents
client.upload_document(ct_id, "/data/earnings_report.pdf", "Q4 2025 earnings report")
client.upload_document(ct_id, "/data/market_analysis.xlsx", "Competitor market share data")

# 3. Wait for processing (poll until all documents are ready)
import time
while True:
    docs = client.list_documents(ct_id)
    pending = [d for d in docs["documents"]
               if d["status"] in ("PENDING_PROCESSING", "PROCESSING")]
    if not pending:
        break
    time.sleep(10)

# 4. Read the context tree — structured summary of all documents
tree = client.get_context_tree_markdown(ct_id)
print(tree["markdown"])

# 5. Use with CellCog chat

# OpenClaw agents (fire-and-forget):
result = client.create_chat(
    prompt="Based on our project documents, create a board presentation",
    project_id=project_id,
    notify_session_key="agent:main:main",  # OpenClaw only
    task_label="board-deck",
)

# All other agents (blocks until done):
result = client.create_chat(
    prompt="Based on our project documents, create a board presentation",
    project_id=project_id,
    task_label="board-deck",
)

---

Project Lifecycle#

Creating Projects#

python

project = client.create_project(
    name="My Research Project",
    instructions="Optional instructions for CellCog agents working in this project"
)
# Returns: {"id": "...", "name": "...", "context_tree_id": "...", "created_at": "..."}

The creator is automatically an admin. Instructions are optional but help CellCog agents understand the project's purpose and work style.

Listing Projects#

python

projects = client.list_projects()
# Returns: {"projects": [{"id", "name", "is_admin", "context_tree_id", "files_count", "created_at"}, ...]}

Every project in the list includes its context_tree_id — no need to call get_project() separately just to get it.

Getting Project Details#

python

project = client.get_project(project_id)
# Returns: {"id", "name", "project_instructions", "context_tree_id", "is_admin", "created_at", ...}

Use get_project() when you need project_instructions or other details not included in the list.

Updating Projects#

python

client.update_project(project_id, name="New Name", instructions="Updated instructions")

Admin access required.

Deleting Projects#

python

client.delete_project(project_id)

Admin access required. Soft delete — contact support@cellcog.ai to recover.

---

Document Management#

All document operations use context_tree_id, not project_id. Get it from list_projects(), create_project(), or get_project() response.

Uploading Documents#

python

result = client.upload_document(
    context_tree_id=ct_id,
    file_path="/path/to/document.pdf",
    brief_context="Q4 2025 earnings report with revenue breakdown"
)
# Returns: {"file_id": "...", "status": "processing", "message": "..."}

Admin access required. The project creator is automatically an admin.

brief_context matters. CellCog's AI uses it to generate better summaries in the context tree. A good brief context significantly improves the quality of the structured summary that agents will read later.

Supported file types: PDF, DOCX, XLSX, PPTX, CSV, TXT, MD, images (JPG/PNG/GIF/WebP/SVG), audio (MP3/WAV/AAC/FLAC), video (MP4/AVI/MOV), and code files (JS/PY/Java/Go/etc.).

Max file size: 100 MB per file.

Credit usage: Uploads are processed by a lightweight AI agent using credits, so agents can access structured summaries and decide which documents to pull into context. Credit cost varies by document size and complexity.

Processing time: After upload, CellCog processes the document (extracts text, generates summaries, updates the context tree). This takes 1-3 minutes for typical documents, longer for large files.

Waiting for Document Processing#

After uploading, poll until processing completes:

python

import time
while True:
    docs = client.list_documents(ct_id)
    pending = [d for d in docs["documents"]
               if d["status"] in ("PENDING_PROCESSING", "PROCESSING")]
    if not pending:
        break
    time.sleep(10)

Listing Documents#

python

docs = client.list_documents(ct_id)
# Returns: {"documents": [{"id", "original_filename", "file_type", "file_size", "status", ...}]}

Document status values:

• PENDING_PROCESSING — Queued for processing
• PROCESSING — Being processed
• SUCCEEDED — Ready and in context tree
• ERRORED — Processing failed (check processing_error)

Deleting Documents#

python

client.delete_document(ct_id, file_id)

# Or bulk delete (up to 100 at once):
client.bulk_delete_documents(ct_id, [file_id_1, file_id_2, ...])

Admin access required.

---

Context Trees — Your Knowledge Structure#

After documents are processed, CellCog organizes them into a Context Tree — a hierarchical markdown representation with file descriptions, metadata, and content summaries. This is the same proprietary data structure that CellCog's internal agents use.

Getting the Context Tree Markdown#

python

# Default: compact view with short summaries
tree = client.get_context_tree_markdown(ct_id)
print(tree["markdown"])

# Detailed view: includes long descriptions for each document
tree = client.get_context_tree_markdown(ct_id, include_long_description=True)
print(tree["markdown"])

Use include_long_description=True when you need full document details for deeper analysis. Default short descriptions are sufficient for most use cases and keep context windows efficient.

Example output:

text

## 📁 / (Q4 Financial Analysis Documents)
Document repository for Q4 Financial Analysis.

### 📁 /financials (Financial Reports)
Core financial documents and earnings data

#### 📄 /financials/earnings_report.pdf (Q4 2025 Earnings Report)
*Created: 2 hours ago*
**Type:** PDF (2.1 MB)

Comprehensive Q4 2025 earnings report with revenue breakdown by segment,
operating margins, and forward guidance. Revenue grew 15% YoY to $12.3B.

### 📁 /market (Market Data)
Competitive landscape and market research

#### 📄 /market/market_analysis.xlsx (Competitor Market Share Data)
*Created: 2 hours ago*
**Type:** XLSX (450.5 KB)

Market share analysis across 5 competitors. Includes quarterly trends,
geographic breakdown, and pricing comparison matrix.

Why Context Trees Matter for Agents#

1. Understand before downloading. Read the tree to know what's available without downloading every file.
2. AI-processed summaries. Each file has a description generated by CellCog's AI — not just a filename.
3. Hierarchical organization. Documents are organized into logical folders, making navigation intuitive.
4. Same view as CellCog agents. When you pass project_id to a CellCog chat, the agent sees this exact tree.

---

Signed URLs — Share Your Documents#

Generate time-limited, pre-authenticated download URLs for any documents in the context tree. These URLs work without CellCog authentication — pass them to other agents, tools, or humans.

By File Path (Recommended)#

Use paths directly from the context tree markdown — no file IDs needed:

python

urls = client.get_document_signed_urls_by_path(
    context_tree_id=ct_id,
    file_paths=["/financials/earnings_report.pdf", "/market/analysis.xlsx"],
    expiration_hours=24  # Valid for 24 hours (default: 1 hour, max: 168 = 7 days)
)

# Returns:
# {
#     "urls": {"/financials/earnings_report.pdf": "https://storage.googleapis.com/...", ...},
#     "errors": {}
# }

By File ID (Alternative)#

Use file IDs from list_documents():

python

urls = client.get_document_signed_urls(
    context_tree_id=ct_id,
    file_ids=["file_id_1", "file_id_2"],
    expiration_hours=24
)

Use Cases#

• Cross-agent sharing. Pass URLs to other agents that need to read your documents.
• Human sharing. Send URLs to your human so they can download files directly.
• External tool integration. Pass URLs to APIs that accept file URLs (e.g., analysis services).
• Temporary access. Use short expiry (1 hour) for one-time access, long expiry (7 days) for ongoing workflows.

Note: Signed URLs remain valid for their full duration even if the user's project access is later revoked. New URLs cannot be generated after access is removed.

---

Using Projects with CellCog Chats#

Projects are first-class in CellCog. When you pass a project_id, CellCog agents automatically get:

• All project documents via the context tree
• Project instructions that guide agent behavior
• Organization context if the project belongs to an organization

Quick start:

python

result = client.create_chat(
    prompt="[your task prompt]",
    task_label="my-task",
    chat_mode="agent",  # See cellcog skill for all modes
)

See https://cellcog.ai for complete SDK API reference — delivery modes, send_message(), timeouts, file handling, and more.

Finding project and role IDs:

python

# List all projects
projects = client.list_projects()

# Get project details (includes context_tree_id)
project = client.get_project(project_id)

# List agent roles in a project
roles = client.list_agent_roles(project_id)

---

API Reference#

Project Management#

MethodDescriptionclient.list_projects()List all accessible projectsclient.create_project(name, instructions="")Create a new project (returns id, context_tree_id)client.get_project(project_id)Get project details including context_tree_id``client.update_project(project_id, name=None, instructions=None)Update project (admin)client.delete_project(project_id)Soft delete project (admin)

Agent Roles (Read-Only)#

MethodDescriptionclient.list_agent_roles(project_id)List active roles (for discovering agent_role_id values)

Document Management#

MethodDescriptionclient.list_documents(context_tree_id)List all documents with statusclient.upload_document(context_tree_id, file_path, brief_context=None)Upload and process a document (admin)client.delete_document(context_tree_id, file_id)Delete a document (admin)client.bulk_delete_documents(context_tree_id, file_ids)Delete up to 100 documents (admin)

Context Tree#

MethodDescriptionclient.get_context_tree_markdown(context_tree_id, include_long_description=False)Get AI-processed markdown view (set True for detailed descriptions)client.get_document_signed_urls_by_path(context_tree_id, file_paths, expiration_hours=1)Get download URLs by file path (recommended)client.get_document_signed_urls(context_tree_id, file_ids, expiration_hours=1)Get download URLs by file ID (alternative)

---

Human-Only Features#

The following are managed by humans through the CellCog web UI at cellcog.ai:

FeatureWhyWhereMember managementInvitation flow requires email verificationcellcog.ai → Projects → MembersAgent role creation/editingPrompt engineering best done interactivelycellcog.ai → Projects → Agent RolesGoogle Drive importOAuth requires browser interactioncellcog.ai → Projects → Import

Ask your human to configure these at https://cellcog.ai.

---

Error Handling#

ErrorCauseResolutionAPIError(404)Project or context tree not foundVerify the ID with list_projects()``APIError(403)Not a project member, or admin access requiredCheck membership; upload/delete require adminAPIError(400)Invalid request (e.g., file too large, unsupported type)Check file size (<100MB) and supported typesFileUploadErrorLocal file not found or upload failedVerify file path exists and is readable

All errors include descriptive messages. Check error.message for details.

---

Tips#

1. brief_context is your best investment. A one-sentence description like "Q4 2025 earnings with segment breakdown" dramatically improves the AI-generated summary in the context tree.

2. Read the tree before downloading. Use get_context_tree_markdown() to understand what's available. You often don't need to download files — the markdown summaries are sufficient for many decisions.

3. Signed URLs enable cross-agent workflows. Get a 24-hour URL and pass it to another agent or tool that needs the data. No CellCog auth needed on their end.

4. Projects work without CellCog chats. You can use projects purely as a document store with AI-processed summaries. Upload docs, read the context tree, get signed URLs — all without creating a single CellCog chat.

5. Processing takes time. After uploading, poll with list_documents() checking the status field. Don't use fixed sleeps — processing time varies by file size and type.

6. Use the right context_tree_id. Every project has its own context tree. Get it from list_projects(), create_project(), or get_project(). Don't mix context tree IDs from different projects or organizations.

---

If CellCog is not installed#

Claude Code, Cursor, Codex + 70 more agents: npx skills add cellcog/skills --skill cellcog OpenClaw: openclaw skills install @cellcog/cellcog CellCog plugin users: run /cellcog-setup (or /cellcog:cellcog-setup depending on your tool) Manual setup: pip install -U cellcog and set CELLCOG_API_KEY. See the cellcog skill for SDK reference. Other agents: pip install cellcog and set CELLCOG_API_KEY. See https://cellcog.ai for details.