# 项目指南

创建个人项目工作区，管理记忆关联，跟踪 TODO 与决定，并界定 agent 上下文作用域。

- Canonical: https://docs.xmemo.dev/zh/docs/guides/projects
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 7f95ace70e5137cfc69dccdd21827d3a6a830c65f25f2cff83b344d35824c8ef
- Edition-Digest: 6f63895978833ee4dddc8fe60db0980a8b9e3e0b05690ae0fcb25deb848fbb1c
- Source-Revision: sha256:192851794c728ed3868a5be3be886563c1566aa6aec82e2a9d21109e443f6368

## 用户目标

建立专用的项目工作区以组织上下文记忆、跟踪操作决定和活动任务、在连接的 agent 中检索聚焦的项目上下文，并验证移除项目关联后核心个人记忆依然完好无损。

## 可用性与前提条件

项目工作区在 Memory Console（https://xmemo.dev/me#projects）中跨所有个人账户提供，并通过支持的 MCP 客户端配置文件提供：

- 个人边界：目前项目严格仅限个人；尝试使用 team_id 创建项目将被服务器拒绝（HTTP 400）。文档未对团队项目做出任何承诺。
- 无上限配额：工作区的创建不受数值计划配额或人为项目限制的约束。账户可按需预配工作区。
- 分区视图：如果您的账户启用了该功能，"需要注意"（Attention Needed）视图以及知识记忆（Knowledge）与工作记忆（Working）分区将正常运行（收敛评估模式默认处于关闭状态）。
- Agent 连接性：连接的 agent 根据 config/mcp-documentation-contract.json 中约定的客户端配置文件访问相应的项目工具。

## 1. 在 Memory Console 中导航至项目

登录您的个人仪表板并打开 https://xmemo.dev/me#projects。在左侧导航栏中，选择 Workspace 部分并点击 Projects。面板标题显示 "Browse project workspaces, context, and project memories."，并展示 Total Projects、Active、Attention Needed 和 Archived 的顶层指标。

```text
https://xmemo.dev/me#projects
Workspace -> Projects -> Total Projects (0) | Active (0) | Attention Needed (—) | Archived (0)
```

## 2. 预配新的个人项目工作区

点击顶部操作区域的 Create New Project 打开工作区弹窗：

- 项目名称：输入描述性项目名称（例如 "Incident Response Automation"）。该字段提示 "Required, 1-128 characters."，并针对控制字符和路径分隔符（/ 或 \）进行验证。
- 项目标识符预览：查看预览标识符（#incident-response-automation）。帮助提示确认："Non-authoritative preview. The backend server assigns the authoritative project key."
- 描述：可选输入最多 2000 个字符的作用域章程（例如 "Operational runbooks, triage checklists, and automated incident response workflows."）。
- 提交：点击 Create Project。服务器分配规范标识符并打开项目详细信息视图。

## 3. 关联记忆、TODO 与决定

预配好工作区后，为其填充作用域限定的上下文、待处理任务和架构决定：

- 关联记忆：写入一条作用域限定在项目内的合成运维 runbook 记忆（scope: "incident-response-automation"）："Runbook policy: P0 production outages trigger immediate secondary on-call escalation after 15 minutes of unacknowledged alerts."
- 记录 TODO：在项目详细信息视图中或通过 agent 添加任务："Draft post-incident review template for payment gateway timeouts."
- 记录决定：记录架构决定："Use PagerDuty webhook adapter for primary incident ingestion."
- 检查焦点指标：焦点栏反映实时汇总：Memories: 1, Open TODOs: 1, Decisions: 1。

```ts
await client.remember(
  "Runbook policy: P0 production outages trigger immediate secondary on-call escalation after 15 minutes of unacknowledged alerts.",
  {
    path: "projects/incident-response-automation/runbooks/p0-escalation",
    scope: "incident-response-automation",
  },
);
```

## 4. 验证 agent 上下文召回

连接已授权的 agent 客户端以验证项目检索返回作用域限定的记录，而没有跨项目干扰：

- Cursor 或 Ordinary Full：Agent 调用 get_project_context(project_id="incident-response-automation") 检索活动记忆、待处理 TODO 和已记录的决定。
- ChatGPT 或 Generic Public：Agent 调用 get_project_summary(project_id="incident-response-automation") 或 open_project_workspace 检查摘要状态。
- ChatGPT 聊天内小组件：由 open_project_workspace 打开的聊天内交互式小组件直接在会话内部提供内联任务卡片；它有别于 https://xmemo.dev/me#projects 上的完整 Web 版 Memory Console。

```json
{
  "project_id": "incident-response-automation",
  "status": "active",
  "memories_count": 1,
  "open_todos": 1,
  "decisions": 1,
  "summary": "Operational runbooks, triage checklists, and automated incident response workflows."
}
```

## 5. 取消关联记忆并验证无损移除

验证移除项目记忆仅解除了工作区关联，同时保留了底层的个人记忆记录：

- 打开记忆抽屉：在项目记忆列表中，选择运维 runbook 条目以展开详细信息抽屉。
- 发起移除：点击抽屉操作中的 Remove from Project。
- 确认取消关联：弹窗打开，标题为 "Remove from Project"，副标题为 "This memory will be disassociated from this project workspace."。注意警告提示："The memory content remains in your personal memory archive, but will no longer appear in this project context."
- 执行确认：点击 Remove。项目记忆计数递减至 0。
- 验证全局持久性：导航至个人记忆归档（/me#memory），确认 runbook 记忆依然完好且可检索。

## 可观察结果

完成此工作流后，您的工作区展现出完全的操作隔离性：

- 工作区状态：该项目列在活动项目（Active）下，规范 slug 为 #incident-response-automation。
- 上下文隔离：连接的 agent 查询项目上下文并接收作用域限定的事实，不会受到无关项目的污染。
- 数据安全性：从工作区解除记忆记录关联成功递减了项目汇总，同时在您的归档中永久保留了个人记忆记录。

## Agent 可以访问的内容

Agent 工具的可用性严格取决于 config/mcp-documentation-contract.json 中配置的客户端配置文件：

- chatgpt-public、generic-public 和 public-only 配置文件：公开 project、get_project_summary 和 open_project_workspace。
- claude-plugin 配置文件：公开 project 和 get_project_context。
- cursor-plugin 与 ordinary-full 配置文件：公开 get_project_context、update_project_todo 和 update_project_decision。
- 配置文件边界：其他客户端配置文件不公开项目工具。尝试调用未约定的工具将导致工具发现拒绝。

## 共享与生命周期边界

项目工作区强制执行明确的操作与数据边界：

- 个人边界：目前所有工作区仅限个人。不支持团队工作区，提供 team_id 的请求将无法通过验证。
- 生命周期状态：记忆浏览器将记录归类为 Active、Superseded、Expired 和 Archived 状态。
- 策展分区：如果您的账户启用了该功能，工作区将提供知识记忆（Knowledge）和工作记忆（Working）分区。Knowledge 分区保存持久规范；Working 分区存储瞬态会话状态。
- 与知识库的区别：项目分区用于分类会话式情景记忆。相比之下，知识库通过多修订版本快照提供正式的、带版本的文档管理。有关精心策展的文档，请参阅 /docs/concepts/knowledge-bases。
- 配额边界：个人项目工作区没有数值配额限制。

## 故障恢复

常见极端情况与恢复操作：

- 重复的项目名称（HTTP 409）：服务器拒绝重复的项目名称，提示 "A project with this name or identifier already exists in your workspace."。请提供不同的项目名称。
- 无效的项目名称（HTTP 400）：项目名称不能包含斜杠（/ 或 \）、超过 128 个字符或使用保留令牌（_project、.、..）。请在创建对话框中更正名称。
- 客户端配置文件工具不匹配：如果 agent 找不到 get_project_context，请验证活动客户端配置文件。chatgpt-public 配置文件公开 get_project_summary，而 get_project_context 在 cursor-plugin 和 ordinary-full 下公开。
- 版本冲突（HTTP 409）：如果另一个会话同时修改了项目或记忆，抽屉会显示 "Modified elsewhere, please reload" 以及 Reload 按钮。点击 Reload 刷新状态。

## 相关参考

有关补充能力和技术参考，请参阅：

- 项目概念参考：/docs/concepts/projects 了解架构详细信息与作用域划分规范。
- Memory Console 指南：/docs/guides/memory-console 了解完整的控制台演练。
- 知识库指南：/docs/concepts/knowledge-bases 了解经过策展的参考文档管理。
- 项目 REST API：/docs/api/projects 了解经过身份验证的编程式端点。

## ChatGPT 用户

让 ChatGPT 持久访问你的 XMemo 偏好、项目事实、决策和 TODO，同时不把 bearer token 粘贴到聊天里。

通过 ChatGPT/OpenAI app 的 OAuth 流程连接托管 XMemo MCP server，然后为你的 XMemo 账户批准 memory:read 与 memory:write 授权。

保存一条合成偏好或项目笔记，开启新聊天，再让 ChatGPT 在继续工作前通过 XMemo 召回它。

如果 OAuth 失败或工具未出现，先在宿主应用里退出该 MCP server，重新连接 XMemo server URL 并重试，再考虑创建 direct token。

## Copilot / Codex 开发者

在 IDE 与 CLI agent 之间携带仓库决策、编码规范、bug 修复说明和任务历史。

在可用时对 VS Code / GitHub Copilot 和 Gemini CLI 使用 OAuth。对于 Copilot CLI、Codex、Cursor 或其他直连 MCP 客户端，请在本地环境或密钥存储中保留 XMEMO_KEY，并设置稳定的 XMEMO_AGENT_INSTANCE_ID。

记录一条代码库决策或 bug 修复，然后让下一个 IDE 或 CLI agent 在编辑前召回相关 XMemo 上下文。

如果召回为空，检查所选 MCP 配置路径、direct client 的 XMEMO_KEY 环境变量，以及宿主应用中是否存在过期 OAuth 凭据。

## 团队 / 企业 pilot owner

用账户控制、来源归因、导出/删除流程和 reviewer-safe 设置证据来评估共享记忆。

创建或进入受保护的 XMemo workspace，邀请已批准用户，然后根据 readiness badges 通过 OAuth 或 scoped direct credential 连接各客户端。

让一名 pilot 成员保存一条合成团队记忆，在 XMemo 中确认来源归因，然后审阅删除/导出和支持路径。

如果成员无法连接，先检查角色权限、OAuth 批准、客户端 readiness 状态和支持指引，再签发新 token。

## 自主 agent operator

让 headless 或定时 agent 记录进度、取回历史决策，并保持稳定的非秘密实例身份。

获取 /api/v1/mcp/config/autonomous-agent。当 runner 支持 OAuth + 自定义 headers 时优先使用 auth_modes.oauth；只有完全 headless 的 runner 才使用 auth_modes.xmemo_key，并从密钥库读取 XMEMO_KEY。

运行一个会向 XMemo 写入进度的合成任务，重启 runner，并确认它使用同一个 XMEMO_AGENT_INSTANCE_ID 召回该进度。

如果归因变化或召回分散到多个实例，请把 XMEMO_AGENT_INSTANCE_ID 持久化到 git 之外，并确认 runner 不会每次启动都重新生成它。