跳转至

记忆 wiki

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

它不会替换当前记忆插件。回忆、提升、索引和梦境仍由已配置的记忆插件(memory-core、Honcho 及其他)负责。memory-wiki 与其并列,将知识编译为受维护的 wiki 层。

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

openclaw plugins enable memory-wiki

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

层 负责内容
当前记忆插件 回忆、语义搜索、提升、梦境、记忆运行时
memory-wiki 编译的 wiki 页面、富含来源信息的综合内容、仪表盘、wiki 搜索/获取/应用

实用规则:

  • 使用 memory_search 对已配置的任意语料库执行一次广泛回忆
  • 当你需要 wiki 特定的排序、来源信息或页面级信念结构时,使用 wiki_search / wiki_get
  • 当当前记忆插件支持语料库选择时,使用 memory_search corpus=all 在一次调用中覆盖两个层

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

如果 bridge 模式报告零个导出工件,则当前记忆插件目前未公开公共 bridge 输入。请先运行 openclaw wiki doctor,然后确认当前记忆插件支持公共工件。

保险库模式

  • isolated(默认):拥有独立的保险库和独立来源,不依赖当前记忆插件。适用于自包含的精选知识库。
  • bridge:通过公共插件 SDK 接口从当前记忆插件读取公共记忆工件和事件日志。适用于在不触及私有插件内部的情况下,编译记忆插件导出的工件。
  • unsafe-local:针对本地私有路径的显式同机器逃生通道。有意设计为实验性且不可移植;仅在你理解信任边界并且确实需要 bridge 模式无法提供的本地文件系统访问时使用。

保险库模式和保险库范围是两个独立的选择:

  • vaultMode 决定 wiki 输入来自哪里。
  • vault.scope 决定所有代理是否使用同一个保险库,还是每个代理获得一个子保险库。

vault.scope: "global" 是默认值,并保留现有的单保险库行为。当代理之间不能共享 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>/
  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 表现得像一个信念层,而不是被动的笔记堆。声明可以被跟踪、评分、质疑,并回溯解析到来源。

面向代理的实体元数据

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

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

对于人员 wiki,请先从 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

编译流水线

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

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

仪表板与健康报告

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

报告 跟踪内容
reports/open-questions.md 存在未解决问题的页面
reports/contradictions.md 矛盾注释集群
reports/low-confidence.md 低置信度页面和声明
reports/claim-health.md 缺少结构化证据的声明
reports/stale-pages.md 过期或新鲜度未知
reports/person-agent-directory.md 人员/实体路由卡片
reports/relationship-graph.md 结构化关系边
reports/provenance-coverage.md 证据类别覆盖
reports/privacy-review.md 使用前需要审核的非公开隐私层级
报告 跟踪

搜索与检索

两种搜索后端:

  • shared:当可用时使用共享 memory 搜索流程
  • local:在本地搜索 wiki

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

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

搜索模式(--mode / 工具 mode 参数):

模式 加权
auto 平衡默认
find-person 类人物实体、别名、账号、社交信息、规范 ID
route-question 代理卡片、ask-for/best-used-for 提示、关系上下文
source-evidence 来源页面和结构化证据元数据
raw-claim 匹配的结构化 claim;返回 claim/证据元数据

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

代理工具

工具 用途
wiki_status 当前 vault 模式和范围、已解析的代理、健康状态、Obsidian CLI 可用性
wiki_search 搜索 wiki 页面,并在配置时搜索共享 memory 语料库;接受 mode 用于人物查找、问题路由、来源证据或原始 claim 下钻
wiki_get 按 id/path 读取 wiki 页面;当启用共享搜索且查找未命中时,回退到共享 memory 语料库
wiki_apply 在不进行自由页面修改的情况下,执行窄范围的 synthesis/元数据变更
wiki_lint 结构检查、来源缺口、矛盾、未解决问题

wiki_search 有 30 秒截止时间,并遵循回合取消。超时或取消会返回工具错误, 而不是空结果,并停止正在进行的页面扫描。对于已知页面,请使用其 id 或 path 调用 wiki_get。

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

在 Control UI 中浏览 wiki

Control UI 可以直接浏览已编译的 wiki:打开 Memory 页面,然后进入 Dreams → Diary → Memory Wiki。该标签页将综合、实体和概念 页面聚合成组——还包括携带 claim、未解决问题或矛盾的来源页面和报告页面——并提供 每页计数以及完整 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, 然后重新加载标签页。

Prompt 与上下文行为

当启用 context.includeCompiledDigestPrompt 时,memory prompt 部分会从插件状态 附加一个紧凑的编译快照:仅包含顶级页面、仅包含顶级 claim、矛盾数量、问题数量、 置信度/新鲜度限定词。这是可选功能,因为它会改变 prompt 形状;它主要对显式消费 memory 补充的上下文引擎或 prompt 组装重要。

配置

将配置放在 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,
          },
        },
      },
    },
  },
}

关键开关:

键 值 / 默认值 说明
vaultMode isolated(默认)、bridge、unsafe-local 选择输入和集成行为
vault.scope global(默认)、agent 一个共享库,或每个代理一个子库
vault.path 全局默认 <state-dir>/wiki/main 全局精确指定库;代理作用域的父目录默认为 <state-dir>/wiki
vault.renderMode native(默认)、obsidian obsidian 会写入 Obsidian 友好页面,而不是原生输出
bridge.readMemoryArtifacts 默认 true 导入活动 memory 插件的公共工件
bridge.followMemoryEvents 默认 true 在 bridge 模式下包含事件日志
unsafeLocal.allowPrivateMemoryCoreAccess 默认 false 运行 unsafe-local 导入所必需
unsafeLocal.paths 默认 [] 在 unsafe-local 模式下要导入的显式本地路径
ingest.autoCompile 默认 true 在导入来源变更后重建编译输出
search.backend shared(默认)、local 可用时,shared 使用共享 memory 搜索流程;local 仅搜索 wiki
search.corpus wiki(默认)、memory、all wiki 搜索覆盖的语料库
context.includeCompiledDigestPrompt 默认 false 将所选代理的紧凑摘要快照附加到 memory prompt 部分
render.createBacklinks 默认 true 生成确定性的相关块
render.createDashboards 默认 true 生成仪表板页面

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

每个代理的库

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

{
  agents: {
    ownership: "explicit",
    defaults: {
      heartbeat: { agentId: "support" },
      systemAgent: { agentId: "support" },
      authInheritance: { agentId: "support" },
    },
    entries: {
      support: { workspace: "~/.openclaw/workspace" },
      marketing: {},
    },
  },
  talk: { agentId: "support" },
  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。

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

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

Warning

更改 vault.scope 不会复制或拆分现有库。在代理作用域中, 显式配置的 vault.path 会成为父目录,因此在切换生产代理之前, 请有意地移动或导入现有页面。请先备份库。

每个代理的库是同一进程内的知识边界,而不是操作系统安全边界。 具有主机文件系统访问权限的插件和未沙箱化工具仍可能读取其他代理的目录。 当代理之间互不信任时,请使用沙箱隔离或 独立的 Gateway 配置文件。

示例:内置 memory + bridge 模式

当你希望使用内置 memory 进行召回,并使用 memory-wiki 作为维护的知识层时,请使用此配置。每一层都保持专注:memory-core 搜索 memory 笔记和符合条件的会话来源,而 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 专注于编译后的页面和仪表盘,并且在你有意启用编译摘要 Prompt 之前,Prompt 结构保持不变。

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(默认)。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw