记忆 wiki

memory-wiki 是一个内置插件，它将持久知识编译为可导航的 wiki：确定性页面、带证据的结构化声明、出处信息、仪表板，以及机器可读摘要。

它不会取代主动记忆插件。回忆、提升、索引和梦境处理仍由已配置的记忆插件（memory-core、Honcho 等）负责。memory-wiki 与其并列运行，将知识编译为持续维护的 wiki 层。

在使用其 CLI、工具或运行时集成之前，请先启用该插件：

openclaw plugins enable memory-wiki

启用操作会自动应用于正在运行的 Gateway。如果 Gateway 处于离线状态，请先启动它再使用运行时集成。参见 应用更改并检查。

实用规则：

• memory_search：对已配置的所有语料库执行一次广泛的回忆检索
• wiki_search / wiki_get：当你需要 wiki 特定的排序、出处信息或页面级信念结构时
• memory_search corpus=all：当主动记忆插件支持语料库选择时，一次调用即可覆盖两层

常见的本地优先配置使用内置记忆进行回忆，并使用 bridge 模式下的 memory-wiki 生成持久的综合页面。参见配置中的 bridge 模式示例。

如果 bridge 模式报告导出的产物为零，说明主动记忆插件当前未暴露公共 bridge 输入。请先运行 openclaw wiki doctor，然后确认主动记忆插件支持公共产物。

Vault 模式¶

• isolated（默认）：自有 vault、自有来源，不依赖主动记忆插件。适用于自包含的策展知识库。
• bridge：通过公共插件 SDK 接口从主动记忆插件读取公共记忆产物和事件日志。用于编译记忆插件导出的产物，而无需深入插件私有内部。
• unsafe-local：针对本地私有路径的显式同机逃生通道。刻意保持实验性和不可移植性；仅在你理解信任边界且确实需要 bridge 模式无法提供的本地文件系统访问时才使用。

vault 模式和 vault 范围是彼此独立的选项：

• vaultMode 选择 wiki 输入的来源。
• vault.scope 选择是所有代理共用一个 vault，还是每个代理获得一个子 vault。

vault.scope: "global" 是默认值，并保留现有的单 vault 行为。当代理之间不得共享 wiki 页面、编译摘要、搜索结果或写入时，请在 isolated 或 bridge 模式下使用 vault.scope: "agent"。代理范围不能与 unsafe-local 模式组合，因为那些配置的私有路径不是代理拥有的输入。配置验证会拒绝此组合。

bridge 模式可以按 bridge.* 配置开关来索引：

• 导出的记忆产物（indexMemoryRoot）
• 每日笔记（indexDailyNotes）
• 梦境报告（indexDreamReports）
• 记忆事件日志（followMemoryEvents）

当 bridge 模式激活且 bridge.readMemoryArtifacts 启用时，openclaw wiki status、openclaw wiki doctor 和 openclaw wiki bridge import 会通过正在运行的 Gateway 路由，因此它们看到的主动记忆插件上下文与代理/运行时记忆一致。如果 bridge 被禁用或产物读取关闭，这些命令保持本地/离线行为。

Vault 布局¶

<vault>/
  AGENTS.md
  WIKI.md
  index.md
  inbox.md
  entities/
  concepts/
  syntheses/
  sources/
  reports/
  _attachments/
  _views/
  .openclaw-wiki/

受管内容保留在生成的块内；人工笔记块在重新生成时会被保留。

• sources/：导入的原始材料以及 bridge/unsafe-local 支持的页面
• entities/：持久的事物、人物、系统、项目、对象
• concepts/：想法、抽象、模式、策略（也是 OKF 导入的落点）
• syntheses/：编译摘要和维护的汇总
• reports/：生成的仪表板

Open Knowledge Format 导入¶

openclaw wiki okf import ./bundles/ga4

将解包后的 Open Knowledge Format 包导入 wiki 概念页面。当数据目录、文档爬虫或增强代理已经生成 OKF 时，这非常合适：将 OKF 保留为可移植的交换产物，让 memory-wiki 将其转换为 OpenClaw 原生的概念页面和编译摘要。

• 非保留的 .md 文件作为概念文档
• 每个导入的概念都需要非空的 type frontmatter 字段；缺少 type 会产生 missing-type 警告，并跳过该文件
• 未知的 type 值会作为通用概念被接受
• index.md 和 log.md 是保留文件，永远不会作为概念导入
• 损坏的或外部的 Markdown 链接保持不变
• 内联代码、围栏代码和缩进代码块中的链接保持原样

导入的页面平铺在 concepts/ 下，因此现有的编译、搜索、获取和仪表板流程无需第二棵 wiki 树即可看到它们。每个页面保留原始 OKF 概念 ID、源路径、type、resource、tags、时间戳以及完整的生产者 frontmatter。内部 OKF 链接会重写到生成的 wiki 概念页面，并同时生成带 kind: okf-link 的结构化 relationships 条目。

结构化声明与证据¶

页面携带结构化的 claims frontmatter，而不仅仅是自由文本。每条声明可包含 id、text、status、confidence、evidence[] 和 updatedAt。每条证据条目可包含 kind、sourceId、path、lines、weight、confidence、privacyTier、note 和 updatedAt。

这让 wiki 表现得像一个信念层，而不是被动的笔记堆。声明可以被追踪、评分、质疑，并回溯到来源进行解析。

面向 Agent 的实体元数据¶

实体页面携带可用于人员、团队、系统、项目或任何其他实体类型的通用路由元数据：

• entityType：例如 person、team、system、project
• canonicalId：跨别名和导入的稳定身份键
• aliases：解析到同一页面的名称、句柄或标签
• privacyTier：自由格式字符串；public 被视为无需审查，其他任何值（例如 local-private、sensitive、confirm-before-use）都会在 reports/privacy-review.md 中被标记
• bestUsedFor / notEnoughFor：简洁的路由提示
• lastRefreshedAt：源刷新时间戳，独立于页面编辑时间
• personCard：可选的人员专属路由卡片（句柄、社交账号、邮箱、时区、领域、可询问事项、避免询问事项、置信度、隐私级别）
• relationships：指向相关页面的类型化边（目标、类型、权重、置信度、证据类型、隐私级别、备注）

对于人员维基，请先从 reports/person-agent-directory.md 开始，然后在使用联系方式或推断事实之前，使用 wiki_get 打开人员页面。

pageType: entity
entityType: person
id: entity.example-person
canonicalId: maintainer.example-person
aliases:
  - Alex
  - example-handle
privacyTier: local-private
bestUsedFor:
  - Example ecosystem routing
notEnoughFor:
  - legal approval
lastRefreshedAt: "2026-04-29T00:00:00.000Z"
personCard:
  handles:
    - "@example-handle"
  socials:
    - "https://x.example/example-handle"
  emails:
    - alex@example.com
  timezone: America/Chicago
  lane: Example ecosystem
  askFor:
    - Example rollout questions
  avoidAskingFor:
    - unrelated billing decisions
  confidence: 0.8
  privacyTier: confirm-before-use
relationships:
  - targetId: entity.other-person
    targetTitle: Other Person
    kind: collaborates-with
    confidence: 0.7
    evidenceKind: discrawl-stat
claims:
  - id: claim.example.routing
    text: Alex is useful for example-ecosystem routing.
    status: supported
    confidence: 0.9
    evidence:
      - kind: maintainer-whois
        sourceId: source.maintainers
        privacyTier: local-private

编译流水线¶

编译读取维基页面，规范化摘要，并在 OpenClaw 的共享 SQLite 插件状态中持久化一个面向机器的快照。运行时代码在异步 prompt 准备期间使用由生命周期拥有的所有者快照来加载 SQLite；同步 prompt 组装从不抓取 Markdown 或读取缓存文件。编译输出还为 search/get 的初始维基索引、将 claim-id 回溯到所属页面、紧凑 prompt 补充以及报告生成提供支持。

源编辑和 vault 恢复只有在下次编译后才会面向机器。重启或刷新插件生命周期时，会将 vault 的因果链式编译发布与 SQLite 进行比较，并拒绝来自较新的、已回滚状态的快照。在回滚之前启动的编译器无法针对已恢复的前驱状态发布。prompt 准备不会轮询 vault，也不会安装文件监视器。 回滚隔离后，运行进程中的编译会立即清除所有者；独立的编译器进程需要刷新插件生命周期，以便守护进程确认新的持久化发布。 ChatGPT 导入回滚会在编译前记录导入后的编辑，并在插件状态中保留其恢复路径，因此中断的回滚可以协调恢复目录，并在重试时报告相同的已保留页面。目标恢复会在持久化的进程重启栅栏之前完成。在此之后，重试会重建派生索引、仪表板和编译缓存，而不会重写源页面，也不会移动或删除恢复工件。之后的正常编译可能会刷新机器管理的 Related 块。这涵盖了普通文件系统调用返回后的进程内失败和进程重启。它不保证跨内核或主机断电的写入顺序。与栅栏持久化竞争的路径名写入，要么在成功栅栏之后保留，要么由栅栏前的重试保存在 recovered/ 下。在导入拥有的 inode 被分类并解除链接之前打开的文件描述符进行的写入没有保证，可能会丢失。 编译缓存可重建：发布纪元之前的缓存行被视为未命中，并由下次编译替换；它们不会被迁移。

仪表板和健康报告¶

当启用 render.createDashboards 时，编译会在 reports/ 下维护仪表板：

搜索和检索¶

两种搜索后端：

• shared：在可用时使用共享内存搜索流程
• local：在本地搜索维基

三个语料库：wiki、memory、all。

• wiki_search / wiki_get 在可能时使用编译摘要作为第一遍
• claim id 会解析回所属页面
• 有争议/过期/新鲜的 claim 会影响排名
• 来源标签会保留到结果中

搜索模式（--mode / 工具 mode 参数）：

当结果匹配结构化声明时，wiki_search 会在其 details 负载中返回 matchedClaimId、matchedClaimStatus、matchedClaimConfidence、 evidenceKinds 和 evidenceSourceIds。文本输出在可用时包含紧凑的 Claim: 和 Evidence: 行。

智能体工具¶

该插件还会注册一个非独占的内存语料库补充，因此当活动内存插件支持语料库选择时，共享的 memory_search 和 memory_get 可以访问 wiki。

在 Control UI 中浏览 wiki¶

Control UI 可以直接浏览已编译的 wiki：打开 Memory 页面，然后 Dreams → Diary → Memory Wiki。该选项卡将 合成、实体和概念页面分组——还包括携带声明、未决问题或矛盾的来源页面和报告页面——并提供每页计数以及整个 vault 的页面细分，并内联打开完整页面内容。没有该元数据的原始来源和报告会 计入细分，但不会作为卡片列出；请从 Imported Insights 子选项卡打开它们，该子选项卡用于审查外部历史导入在提升前浮现的内容。

启用插件后，两个子选项卡都会出现；在智能体范围的 vault 配置中，它们显示所选智能体自己的 vault。UI 通过插件的 网关方法（wiki.overview、wiki.get、wiki.importInsights）读取；内联 页面预览使用 wiki.get，这与智能体通过 wiki_get 工具访问的查找相同。

每个仪表板在其编译快照中最多保留最新的 2,500 张卡片。 当 vault 超过该上限时，UI 会显示返回项数和总项数。

仪表板请求从不扫描原始 vault 页面，也不会等待完整 vault 编译。 在自动恢复期间，UI 会报告仪表板正在重建； 请稍后重新加载选项卡。当 ingest.autoCompile 为 false 时，来源变更或较旧的缓存会改为报告需要编译。运行 openclaw wiki compile，然后重新加载选项卡。

提示和上下文行为¶

启用 context.includeCompiledDigestPrompt 后，内存提示部分会附加来自插件状态的紧凑编译快照：仅顶级页面、 仅顶级声明、矛盾计数、问题计数、置信度/新鲜度限定词。这是可选启用的，因为它会改变提示结构；它主要对明确消费内存 补充的上下文引擎或提示组装重要。

配置¶

将配置放在 plugins.entries.memory-wiki.config 下：

{
  plugins: {
    entries: {
      "memory-wiki": {
        enabled: true,
        config: {
          vaultMode: "isolated",
          vault: {
            scope: "global",
            path: "~/.openclaw/wiki/main",
            renderMode: "obsidian",
          },
          obsidian: {
            enabled: true,
            useOfficialCli: true,
            vaultName: "OpenClaw Wiki",
            openAfterWrites: false,
          },
          bridge: {
            enabled: false,
            readMemoryArtifacts: true,
            indexDreamReports: true,
            indexDailyNotes: true,
            indexMemoryRoot: true,
            followMemoryEvents: true,
          },
          unsafeLocal: {
            allowPrivateMemoryCoreAccess: false,
            paths: [],
          },
          ingest: {
            autoCompile: true,
            maxConcurrentJobs: 1,
            allowUrlIngest: true,
          },
          search: {
            backend: "shared",
            corpus: "wiki",
          },
          context: {
            includeCompiledDigestPrompt: false,
          },
          render: {
            preserveHumanBlocks: true,
            createBacklinks: true,
            createDashboards: true,
          },
        },
      },
    },
  },
}

关键开关：

状态目录默认为 ~/.openclaw。当设置 OPENCLAW_STATE_DIR 时，默认 wiki 库将使用该目录。显式 vault.path 值会保留其配置位置，并且 ~/ 仍会相对于主目录展开。

按代理的库¶

将 vault.scope 设置为 agent，可为每个已配置的代理提供独立的 wiki。在此作用域中，vault.path 是父目录，OpenClaw 会追加规范化后的代理 id：

{
  agents: {
    entries: {
      support: { default: true },
      marketing: {},
    },
  },
  plugins: {
    entries: {
      "memory-wiki": {
        enabled: true,
        config: {
          vaultMode: "bridge",
          vault: {
            scope: "agent",
            path: "~/.openclaw/wiki",
          },
          bridge: {
            enabled: true,
            readMemoryArtifacts: true,
          },
        },
      },
    },
  },
}

这会解析为 ~/.openclaw/wiki/support 和 ~/.openclaw/wiki/marketing。如果在代理作用域中省略 vault.path，父目录默认为 <state-dir>/wiki，其中状态目录为 ~/.openclaw 或 OPENCLAW_STATE_DIR 的值。因此，默认 main 代理使用 <state-dir>/wiki/main。

代理工具、编译后的提示摘要，以及通过 memory_search / memory_get 暴露的 wiki 补充内容，会从活动代理上下文中解析库。除非命令传入 --agent <agentId>，否则 CLI 调用使用已配置的默认代理。在多代理设置中，Gateway 调用仍需要请求中的 agentId。

在桥接模式下，代理作用域的导入仅在其 agentIds 包含所选代理时才接受公开记忆工件。属于其他代理的工件、没有所有权元数据的工件，或所有者未知的工件会被跳过。全局作用域保留现有的共享工件行为。

示例：内置记忆 + 桥接模式¶

当你希望使用内置记忆进行回忆，并使用 memory-wiki 作为维护的知识层时，请使用此配置。每一层都保持专注：memory-core 搜索记忆笔记和符合条件的会话源，而 memory-wiki 编译稳定的实体、声明、仪表板和源页面。

{
  plugins: {
    entries: {
      "memory-wiki": {
        enabled: true,
        config: {
          vaultMode: "bridge",
          bridge: {
            enabled: true,
            readMemoryArtifacts: true,
            indexDreamReports: true,
            indexDailyNotes: true,
            indexMemoryRoot: true,
            followMemoryEvents: true,
          },
          search: {
            backend: "shared",
            corpus: "all",
          },
          context: {
            includeCompiledDigestPrompt: false,
          },
        },
      },
    },
  },
}

这使内置记忆负责主动召回，memory-wiki 专注于编译后的页面和仪表盘，并且在你有意启用编译摘要提示之前，提示结构保持不变。

CLI¶

openclaw wiki status
openclaw wiki doctor
openclaw wiki init
openclaw wiki ingest ./notes/alpha.md
openclaw wiki compile
openclaw wiki lint
openclaw wiki search "alpha"
openclaw wiki get entity.alpha
openclaw wiki apply synthesis "Alpha Summary" --body "..." --source-id source.alpha
openclaw wiki bridge import
openclaw wiki obsidian status

有关完整命令参考，请参阅 CLI: wiki，包括 wiki okf import、wiki apply metadata、wiki unsafe-local import、 wiki chatgpt import / wiki chatgpt rollback，以及完整的 wiki obsidian 子命令集。

Obsidian 支持¶

当 vault.renderMode 为 obsidian 时，插件会写入兼容 Obsidian 的 Markdown，并可选择使用官方 obsidian CLI 进行状态探测、库搜索、打开页面、 调用命令以及跳转到每日笔记。这是可选的；在没有 Obsidian 的情况下，wiki 仍可在原生模式下工作。

代理作用域的库仍可使用兼容 Obsidian 的 Markdown，但配置验证会在 vault.scope: "agent" 时拒绝 obsidian.useOfficialCli: true。 obsidian.vaultName 设置是全局的，无法为每个代理选择不同的 Obsidian 库。 请改用 wiki 工具和 CLI 操作，或将由 Obsidian 操作的 wiki 保留在全局作用域中。

推荐工作流¶

1. 保留主动记忆插件用于召回

召回、提升和做梦仍由已配置的记忆后端负责。

2. 启用 memory-wiki

除非明确想要桥接模式，否则从 isolated 模式开始。

3. 当来源重要时使用 wiki_search / wiki_get

当你需要 wiki 特定的排名或页面级信念结构时，优先使用这些而不是 memory_search。

4. 使用 wiki_apply 进行小范围综合或元数据更新

避免手动编辑受管理的生成块。

5. 在重要更改后运行 wiki_lint

可发现矛盾、未决问题和来源缺失。

6. 开启仪表盘以显示过期/矛盾情况

设置 render.createDashboards: true（默认）。

相关文档¶

• 记忆概览
• CLI: memory
• CLI: wiki
• 插件 SDK 概览
• 记忆 LanceDB