project-cog（项目齿轮）

Project Cog — 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):

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):

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"])

Quick Start

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

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

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

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

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

Admin access required.

Deleting Projects

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

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:

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

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

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

# 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:

## 📁 / (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:

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():

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:

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:

# 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

Agent Roles (Read-Only)

Document Management

Context Tree

Human-Only Features

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

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

Error Handling

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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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

Run /cellcog-setup (or /cellcog:cellcog-setup depending on your tool) to install and authenticate. OpenClaw users: Run clawhub install cellcog instead. 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.