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.
Quick Start
CODEBLOCK0
Project Lifecycle
Creating Projects
CODEBLOCK1
The creator is automatically an admin. Instructions are optional but help CellCog agents understand the project's purpose and work style.
Listing Projects
CODEBLOCK2
Every project in the list includes its context_tree_id — no need to call get_project() separately just to get it.
Getting Project Details
CODEBLOCK3
Use get_project() when you need project_instructions or other details not included in the list.
Updating Projects
CODEBLOCK4
Admin access required.
Deleting Projects
CODEBLOCK5
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
CODEBLOCK6
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:
CODEBLOCK7
Listing Documents
CODEBLOCK8
Document status values:
- -
PENDING_PROCESSING — Queued for processing - INLINECODE13 — Being processed
- INLINECODE14 — Ready and in context tree
- INLINECODE15 — Processing failed (check
processing_error)
Deleting Documents
CODEBLOCK9
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
CODEBLOCK10
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:
CODEBLOCK11
Why Context Trees Matter for Agents
- 1. Understand before downloading. Read the tree to know what's available without downloading every file.
- AI-processed summaries. Each file has a description generated by CellCog's AI — not just a filename.
- Hierarchical organization. Documents are organized into logical folders, making navigation intuitive.
- 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:
CODEBLOCK12
By File ID (Alternative)
Use file IDs from list_documents():
CODEBLOCK13
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:
CODEBLOCK14
See the cellcog mothership skill (clawhub install cellcog) 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
| Method | Description |
|---|
| INLINECODE23 | List all accessible projects |
| INLINECODE24 |
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)
| Method | Description |
|---|
| INLINECODE31 | List active roles (for discovering agent_role_id values) |
Document Management
| Method | Description |
|---|
| INLINECODE33 | List all documents with status |
| INLINECODE34 |
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
| Method | Description |
|---|
| INLINECODE37 | Get AI-processed markdown view (set True for detailed descriptions) |
| INLINECODE38 |
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:
| Feature | Why | Where |
|---|
| Member management | Invitation flow requires email verification | cellcog.ai → Projects → Members |
| Agent role creation/editing |
Prompt engineering best done interactively | cellcog.ai → Projects → Agent Roles |
|
Google Drive import | OAuth requires browser interaction | cellcog.ai → Projects → Import |
Ask your human to configure these at https://cellcog.ai.
Error Handling
| Error | Cause | Resolution |
|---|
| INLINECODE40 | Project or context tree not found | Verify the ID with INLINECODE41 |
| INLINECODE42 |
Not a project member, or admin access required | Check membership; upload/delete require admin |
|
APIError(400) | Invalid request (e.g., file too large, unsupported type) | Check file size (<100MB) and supported types |
|
FileUploadError | Local file not found or upload failed | Verify 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.
Project Cog — 面向智能体的知识工作空间
CellCog项目是知识工作空间，文档在其中被组织成AI处理的上下文树——智能体可以阅读、搜索和推理的结构化分层摘要。
使用项目的两种方式
1. 配合CellCog聊天 — 将文档上传到项目，然后将projectid传递给createchat()。CellCog智能体自动访问所有项目文档和指令。
2. 独立使用 — 纯粹将项目作为知识管理层使用。上传文档、检索上下文树摘要、获取用于分享的签名URL——无需CellCog聊天。任何智能体都可以使用CellCog专有的上下文树数据结构进行自己的工作流程。
快速入门
python
from cellcog import CellCogClient
client = CellCogClient(agent_provider=openclaw)
1. 创建项目
project = client.create_project(
name=第四季度财务分析,
instructions=专注于定量分析。使用保守估计。
)
project_id = project[id]
ct
id = project[contexttree_id]
2. 上传文档
client.upload
document(ctid, /data/earnings_report.pdf, 2025年第四季度收益报告)
client.upload
document(ctid, /data/market_analysis.xlsx, 竞争对手市场份额数据)
3. 等待处理（轮询直到所有文档就绪）
import time
while True:
docs = client.list
documents(ctid)
pending = [d for d in docs[documents]
if d[status] in (PENDING_PROCESSING, PROCESSING)]
if not pending:
break
time.sleep(10)
4. 读取上下文树——所有文档的结构化摘要
tree = client.get
contexttree
markdown(ctid)
print(tree[markdown])
5. 配合CellCog聊天使用
OpenClaw智能体（即发即忘）：
result = client.create_chat(
prompt=根据我们的项目文档，创建一份董事会演示文稿,
project
id=projectid,
notify
sessionkey=agent:main:main, # 仅限OpenClaw
task_label=board-deck,
)
所有其他智能体（阻塞直到完成）：
result = client.create_chat(
prompt=根据我们的项目文档，创建一份董事会演示文稿,
project
id=projectid,
task_label=board-deck,
)
项目生命周期
创建项目
python
project = client.create_project(
name=我的研究项目,
instructions=在此项目中工作的CellCog智能体的可选指令
)
返回：{id: ..., name: ..., contexttreeid: ..., created_at: ...}
创建者自动成为管理员。指令是可选的，但有助于CellCog智能体理解项目的目标和工作方式。
列出项目
python
projects = client.list_projects()
返回：{projects: [{id, name, isadmin, contexttreeid, filescount, created_at}, ...]}
列表中的每个项目都包含其contexttreeid——无需单独调用get_project()来获取它。
获取项目详情
python
project = client.getproject(projectid)
返回：{id, name, projectinstructions, contexttreeid, isadmin, created_at, ...}
当需要projectinstructions或列表中未包含的其他详情时，使用getproject()。
更新项目
python
client.updateproject(projectid, name=新名称, instructions=更新后的指令)
需要管理员权限。
删除项目
python
client.deleteproject(projectid)
需要管理员权限。软删除——联系support@cellcog.ai恢复。
文档管理
所有文档操作使用contexttreeid，而不是projectid。从listprojects()、createproject()或getproject()的响应中获取。
上传文档
python
result = client.upload_document(
contexttreeid=ct_id,
file_path=/path/to/document.pdf,
brief_context=2025年第四季度收益报告，包含收入细分
)
返回：{file_id: ..., status: processing, message: ...}
需要管理员权限。 项目创建者自动成为管理员。
brief_context很重要。 CellCog的AI使用它来在上下文树中生成更好的摘要。一个好的简要上下文能显著提高智能体后续将读取的结构化摘要的质量。
支持的文件类型： PDF、DOCX、XLSX、PPTX、CSV、TXT、MD、图片（JPG/PNG/GIF/WebP/SVG）、音频（MP3/WAV/AAC/FLAC）、视频（MP4/AVI/MOV）和代码文件（JS/PY/Java/Go等）。
最大文件大小： 每个文件100 MB。
积分使用： 上传由轻量级AI智能体使用积分处理，以便智能体可以访问结构化摘要并决定将哪些文档拉入上下文。积分成本因文档大小和复杂度而异。
处理时间： 上传后，CellCog处理文档（提取文本、生成摘要、更新上下文树）。典型文档需要1-3分钟，大文件需要更长时间。
等待文档处理
上传后，轮询直到处理完成：
python
import time
while True:
docs = client.listdocuments(ctid)
pending = [d for d in docs[documents]
if d[status] in (PENDING_PROCESSING, PROCESSING)]
if not pending:
break
time.sleep(10)
列出文档
python
docs = client.listdocuments(ctid)
返回：{documents: [{id, originalfilename, filetype, file_size, status, ...}]}
文档状态值：
- - PENDINGPROCESSING — 排队等待处理
- PROCESSING — 正在处理
- SUCCEEDED — 就绪并已在上下文树中
- ERRORED — 处理失败（检查processingerror）
删除文档
python
client.deletedocument(ctid, file_id)
或批量删除（一次最多100个）：
client.bulk
deletedocuments(ct
id, [fileid
1, fileid_2, ...])
需要管理员权限。
上下文树——您的知识结构
文档处理后，CellCog将它们组织成上下文树——一种分层markdown表示，包含文件描述、元数据和内容摘要。这与CellCog内部智能体使用的专有数据结构相同。
获取上下文树Markdown
python
默认：紧凑视图，带简短摘要
tree = client.get
contexttree
markdown(ctid)
print(tree[markdown])
详细视图：包含每个文档的长描述
tree = client.get
contexttree
markdown(ctid, include
longdescription=True)
print(tree[markdown])
当需要完整的文档详情进行深入分析时，使用includelongdescription=True。默认的简短描述对大多数用例来说已经足够，并能保持上下文窗口高效。
示例输出：
📁 /（第四季度财务分析文档）
第四季度财务分析的文档仓库。
📁 /financials（财务报告）
核心财务文档和收益数据
📄 /financials/earnings_report.pdf（2025年第四季度收益报告）
创建时间：2小时前
类型： PDF（2.1 MB）
全面的2025年第四季度收益报告，包含按业务板块划分的收入细分、
营业利润率和前瞻性指引。收入同比增长15%，达到123亿美元。
📁 /market（市场数据）
竞争格局和市场研究
📄 /market/market_analysis.xlsx（竞争对手市场份额数据）
创建时间：2小时前
类型： XLSX（450.5 KB）
涵盖5个竞争对手的市场份额分析。包括季度趋势、
地理细分和定价对比矩阵。
为什么上下文树对智能体很重要
- 1. 先了解再下载。 阅读树以了解可用内容，无需下载每个文件。
- AI处理的摘要。 每个文件都有CellCog AI生成的描述——不仅仅是文件名。
- 分层组织。 文档被组织成逻辑文件夹，使导航直观。
- 与CellCog智能体相同的视图。 当您将project_id传递给CellCog聊天时，智能体看到的就是这个确切的树。
签名URL——分享您的文档
为上下文树中的任何文档生成有时间限制、预认证的下载URL。这些URL无需CellCog认证即可使用——将它们传递给其他智能体、工具或人类。
按文件路径（推荐）
直接使用上下文树markdown中的路径——无需文件ID：
python
urls = client.getdocumentsignedurlsby_path(
contexttreeid=ct_id,
filepaths=[/financials/earningsreport
