# 项目

让已批准的 client 共享项目事实、决策和交接备注，而无需在不同聊天之间复制它们。

- Canonical: https://docs.xmemo.dev/zh/docs/concepts/projects
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: e82c162591e96921f73cb208323c4238c42240cf414ab2fbfcb253a4c872a206
- Edition-Digest: 1f4efc21143428aff31fb34d23aae3bba3a5144d4902a3361f2ad211093de505
- Source-Revision: sha256:d8d00f958675bca9a3263744deaa85017c659638f29847b5dc3b83ba37f78fc5

## Memory Console 中的项目工作区

项目工作区（Project Workspaces）提供结构化的上下文边界，用于在各个客户端会话之间对记忆进行分组、跟踪操作决策并管理活动任务。在 https://xmemo.dev/me#projects 的 Memory Console 中，工作区导航区域承载着项目面板，用于 "Browse project workspaces, context, and project memories."

- 工作区指标：控制台显示跨工作区的顶层统计数据，包括 Total Projects、Active、Attention Needed 和 Archived。
- 工作区置备：选择 Create New Project 会打开引导式弹窗，要求输入 Project Name（"Required, 1-128 characters."）。界面实时渲染 Project Identifier Preview（"Non-authoritative preview. The backend server assigns the authoritative project key."），并接受最长 2000 字符的可选 Description。
- 个人边界：项目目前仅限个人使用。后端服务会拒绝携带 team_id 的工作区创建请求（HTTP 400）。文档未承诺提供团队项目功能。
- 无配额限制：项目工作区不设数字方案配额或人为创建上限。账户根据工作流程需求而非方案配额来置备工作区。

## 记忆关联、生命周期状态与非破坏性移除

记忆被分配给项目，以便为连接的 agent 和仪表板审查提供受限上下文。项目详情视图汇总项目健康指标，并提供对已关联记录的细粒度检查：

- 项目关键统计：每个工作区顶部概览栏突出显示 Memories:、Open TODOs: 和 Decisions: 的实时汇总值。
- 记忆生命周期筛选：记忆浏览器按生命周期状态对记录进行分类：Active、Superseded、Expired 和 Archived。
- 非破坏性取消关联：从项目工作区中移除记忆记录只会解除关联，而不会销毁底层记忆。确认对话框明确说明："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."
- 诊断隔离：缺少规范引用或存在命名空间冲突的 item 会被隔离在带有 Unindexed - Troubleshooting Only 徽标的 Diagnostic Isolated Items 下，防止损坏的上下文泄漏到 agent 召回中。

## Knowledge 与 Working 分区及 Attention Needed 视图

如果您的账户已启用，项目工作区支持上下文记忆分区（收敛评估模式默认为关闭）：

- Knowledge 分区：保存用于持久召回的长期参考事实、长期架构决策和项目规范。
- Working 记忆分区：包含瞬态任务状态、进行中的工作会话和便签上下文，这些内容在里程碑完成后即可注销。
- Attention Needed 视图：在为您的账户激活分区整理时，高亮显示未分配候选记录、疑似重复项或待归属记录。
- 与 Knowledge Base 的区别：项目 Knowledge 分区对项目边界内的情景对话记忆进行分类。相比之下，Knowledge Base 提供通过独立存储管理的整理好的多 revision 参考文档。有关整理好的文档，请参阅 /docs/concepts/knowledge-bases 的 Knowledge Bases 概念指南。

## 项目是 scope 加 path convention

对于基础记忆范围隔离，XMemo 不需要独立的项目对象：项目由记忆写入的作用域及其内部的逻辑路径命名空间表达，同一账户可承载多个项目而不发生交叉污染。在此记忆边界之上，Project Workspaces 进一步分层构建结构化项目状态（Project API、TODO 跟踪与已记录决策），以实现跨客户端协作。

- 将项目事实写入稳定路径，例如 projects/<name>/decisions。
- 在写入和读取时均传入 project 作用域，确保检索严格受限。
- Project Workspaces 在底层记忆边界之上分层构建结构化项目状态——包括 Project API、持久化 TODO 及已记录决策。
- 项目目前仅限个人使用；API 会拒绝团队作用域的项目工作区。

## 写入项目决策

写入时将记录连接到 project path 和 scope；不需要预先配置其他内容。

```ts
await client.recordDecision(
  "Remote agents should use network MCP, not SSH stdio",
  { source: "codex", scope: "memory-os" },
);
```

## 在另一个 client 中继续项目

第二个 client recall 同一个 scope，就能取回项目上下文，无需用户重新解释。

```ts
const context = await client.recallContext("recent agent integration progress", {
  scope: "memory-os",
  maxItems: 6,
  maxTokens: 1200,
});
```

## Agent 工具与客户端 Profile 访问

授权的 agent 通过 config/mcp-documentation-contract.json 中针对特定客户端 profile 定义的工具与项目交互：

- 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。
- 聊天内小组件区别：通过 open_project_workspace 打开的 ChatGPT Project Workspace 小组件是交互式聊天内卡片界面；它与位于 https://xmemo.dev/me#projects 的完整基于 Web 的 Memory Console 有所不同。

## 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 不会每次启动都重新生成它。