项目记忆与记忆来源

先分清两处记忆#

ZeroWorks 的项目记忆位于工作区 projects/{项目 slug}/MEMORY.md，MCP 记忆则由独立的本地服务和图谱文件保存。两者不会自动互相同步。

两者保存的东西不一样，作用范围也不一样。先分清它们，再决定哪条信息该写去哪里。

• 值得记下来的：稳定的表达偏好、项目约定、需要反复引用的背景说明。
• 不必记下来的：一次性的进度、临时材料，以及任何一次对话都能重新确认的信息。
• 不能记下来的：密码、API Key 等访问凭据。

把记忆来源接进来#

1. 在运行 Agent 的机器上安装 Node/npx，允许工作区本地 MCP，创建来源目录 ~/.zero-works/workspaces/{工作区目录名}/sources/memory/。首次 npx 下载需要网络。
2. 选择持久、可写的绝对图谱路径，先创建父目录，把下面 MEMORY_FILE_PATH 的示例换成真实路径；不依赖 npx 缓存目录里的默认 memory.jsonl。
3. 保存下面完整 config.json，补 guide.md 说明实体命名、允许记录的信息及适用范围；按下一节添加只读 permissions.json。
4. 请 Agent 调用 source_test({"sourceSlug":"memory"})，检查工具名称包含 read_graph、search_nodes、open_nodes，再做一条只读查询。无需登录或输入凭据。

{
  "id": "memory-docs-example",
  "name": "Memory",
  "slug": "memory",
  "enabled": true,
  "provider": "memory",
  "type": "mcp",
  "mcp": {
    "transport": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-memory"
    ],
    "env": {
      "MEMORY_FILE_PATH": "/REPLACE_WITH_ABSOLUTE_PATH/memory.jsonl"
    },
    "authType": "none"
  }
}

只放行图谱读取工具#

把下面 JSON 保存到该来源的 permissions.json，只给 read_graph、search_nodes、open_nodes 添加匹配规则。正则考虑了工具名的来源前缀，不把 create、add 或 delete 误放成读取。

{
  "allowedMcpPatterns": [
    {
      "pattern": "(?:^|__)(?:read_graph|search_nodes|open_nodes)$",
      "comment": "只读图谱、搜索与精确节点读取"
    }
  ]
}

实体、观察与关系：按顺序调用#

实体由唯一 name、entityType 与 observations 字符串数组组成；每条观察只写一个稳定事实。关系包含 from、to、relationType，先创建两端实体再建立有方向的关系。

1. 先 search_nodes({"query":"User"})。没有该实体时用 create_entities 传入下面的 entities 对象；已有同名实体时改用 add_observations，不依赖 create_entities 合并观察。
2. 为已有实体追加事实：add_observations({"observations":[{"entityName":"User","contents":["Prefers concise updates"]}]}). contents 是新增观察数组，不是 observations 字段。
3. 两端存在后建立关系：create_relations({"relations":[{"from":"User","to":"ProjectA","relationType":"works_on"}]}). 之后 open_nodes({"names":["User","ProjectA"]}) 复核结果。
4. 需要更正时调用 delete_observations({"deletions":[{"entityName":"User","observations":["Prefers concise updates"]}]}). 删除用原句精确匹配，再添加新观察。

{
  "entities": [
    {
      "name": "User",
      "entityType": "person",
      "observations": [
        "Prefers conclusions before evidence"
      ]
    },
    {
      "name": "ProjectA",
      "entityType": "project",
      "observations": [
        "Uses TypeScript"
      ]
    }
  ]
}

在对话里提出记住与更正#

1. 明确说出希望记住的事实，以及它的适用范围：只对当前项目有效，还是跨项目通用。
2. 当前项目的信息请使用 project_memory_append；它只对绑定了项目的会话可用。要放进 MCP 图谱的事实，先 search_nodes 检查已有实体，再按实际工具 schema 写入。
3. 更正 MCP 观察时先 open_nodes，使用 delete_observations 删除明确的旧句，再 add_observations 添加新句；项目 MEMORY.md 则通过 project_memory_append 追加纠正，不用旧快照整体覆盖文件。

查看与清理记忆#

1. 少量图谱可 read_graph({})；按主题用 search_nodes({"query":"reporting"})，按精确实体名用 open_nodes({"names":["User"]})，先检查再清理。
2. 项目里的记忆直接打开项目目录下的 MEMORY.md 查看，它是一个普通文件。
3. 清理图谱用 delete_observations、delete_relations 或 delete_entities；删除实体会连同相关关系移除。项目 Markdown 的人工整理应先读最新文件，避免覆盖其他会话追加的内容。