Engram

Engram 是 OpenClaw 的分层语义记忆插件。短期层以多轮对话形成的完整 Episode 为基本单元，长期层保存在 LanceDB；自动召回会合并两层结果，但不会把单句对话碎片直接当作长期记忆。

记忆模型

• Turn：短期保留的原始 user/assistant 消息，只用于形成可追溯的 Episode。
• Episode：一段完整情境，包含 who / what / when / where / why / how、结果、状态、实体和来源引用。
• Claim：从 Episode 中提取的可晋升事实。shadow 模式只审查，auto 模式通过终审后幂等写入长期向量库。
• Long-term memory：LanceDB 中的稳定记忆；升级 Episode 架构不会清空、重建或重新嵌入已有记录。

旧的逐轮 Markdown 摘要、文件行级 BM25、recall-hits 和 daily/monthly settle 链路已停止使用。历史文件不会被插件自动删除，升级后可自行归档。

要求与安装

• Node.js ^20.19 || ^22.13 || >=24
• OpenClaw >=2026.7.2

openclaw plugins install @scotthuang/engram

Engram 使用 memory 独占槽位。由于核心 Auto-Recall 的 before_prompt_build 会读取当前会话上下文，第三方插件还必须通过 plugins.entries.engram.hooks.allowConversationAccess 被显式授予会话访问权限。不要把该字段放在插件条目顶层：

{
  "plugins": {
    "allow": ["engram"],
    "slots": { "memory": "engram" },
    "entries": {
      "engram": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        },
        "config": {}
      }
    }
  }
}

修改配置后请安全重启 Gateway，并用 OpenClaw 的插件检查命令确认运行时确实注册了 before_prompt_build 与 Episode 生命周期 hooks。

配置

下面示例省略了密钥；建议使用精确的环境变量引用 ${ENV_NAME}。升级现有安装时必须原样保留 embedding.model、embedding.baseUrl、embedding.dimensions、API key 引用以及 lancedbDir。

{
  "shortTerm": {
    "rawRetentionDays": 7,
    "idleBoundaryMinutes": 30,
    "minTurns": 2,
    "maxTurns": 16,
    "maxChars": 12000,
    "recallTopK": 2,
    "promotionMode": "shadow"
  },
  "embedding": {
    "model": "text-embedding-v3",
    "apiKey": "${ENGRAM_EMBEDDING_API_KEY}",
    "baseUrl": "https://example.invalid/v1",
    "dimensions": 1024
  },
  "condense": {
    "apiKey": "${ENGRAM_LLM_API_KEY}",
    "baseUrl": "https://example.invalid",
    "model": "your-structured-extraction-model"
  },
  "queryRewrite": {
    "enabled": false,
    "timeoutMs": 10000
  }
}

promotionMode 的含义：

• off：不生成长期晋升候选。
• shadow：默认值；执行提取、评分、去重和审计，但不写 LanceDB。
• auto：仅对通过终审的 Claim 执行受控、幂等写入；建议先观察 Shadow 结果再开启。

完整字段和边界以 openclaw.plugin.json 为准。旧字段 shortTerm.engine、shortTermDays、settleModel、saveStagingFile 与顶层 promotion 已删除，严格配置校验下必须从 OpenClaw 配置中移除。

诊断与导出

openclaw memory-sys stats
openclaw memory-sys profile
openclaw memory-sys episodes-export --agent main
openclaw memory-sys episodes-export --agent main --output episodes.json
npm run sim -- --agent main "我们之前为什么重构短期记忆？"

episodes-export 输出 Episode、Claim 和来源消息引用，便于审计，不修改任何记忆。Memory API 的健康检查和 HTTP 接口见 docs/memory-api.md。

升级

从旧短期架构升级前，请阅读 docs/episode-v2-migration.md。核心顺序是：备份 OpenClaw 配置和 LanceDB、移除旧配置字段、安装、授予 allowConversationAccess、重启、核对 hooks，并比较升级前后的长期向量记录。

开发与发布检查

npm install
npm run verify
npm run build
npm pack

npm run verify 包含 TypeScript、ESLint、Node 测试、Python 测试与 Web 检查；prepack 还会执行干净构建、测试和发布包 smoke test。