ClawHub
SkillsPluginsOfficialDocsSupport
K
plugins/deki18/openclaw-cortex-memory
Memory
#memory-store#long-term-memory#memory-system#rag

Cortex Memory

Long-term memory system for OpenClaw AI Agent

deki18@deki18

OpenClaw Cortex Memory

OpenClaw 长期记忆插件 - 专为 OpenClaw AI 助手设计的智能记忆系统

License: MIT Node.js: 22+ OpenClaw: Plugin

面向 OpenClaw 的长期记忆插件,集成多路检索、事件归档、图谱关系、向量化与反衰减排序,支持历史增量导入、规则反思和可观测诊断,帮助 Agent 在跨会话中持续积累并稳定调用高价值记忆。


核心能力

1) 语义检索

  • 多路召回:keyword / BM25 / vector / graph 混合检索
  • 排序融合:加权打分 + RRF + 可选 reranker
  • 结果融合:可选 readFusion,支持权威融合返回
  • 时序建模:memoryDecay + 命中反衰减(anti-decay)

2) 事件存储

  • 分层写入:active(会话)与 archive(结构化事件)
  • 摘要优先:归档记录保留 summary 与 source_text
  • 向量分块:支持 summary/evidence 双通道向量记录
  • 增量同步:按状态文件增量导入历史会话

3) 图谱关系

  • 图谱独立层:graph/memory.jsonl 独立于 archive 文本层
  • 关系追溯:每条关系可追溯 source_event_id
  • 关系查询:query_graph 支持方向、关系类型、路径搜索
  • 冲突治理:单值事实冲突进入队列,支持人工 accept/reject 闭环
  • 可视化导出:export_graph_view 输出状态化图谱快照(含来源证据)
  • 质量门禁:graphQualityMode 支持 off/warn/strict

4) 规则演进

  • 反思沉淀:reflect_memory 将事件抽象为规则
  • 去重治理:规则与事件均有去重控制,避免污染
  • 规则复用:规则写入 CORTEX_RULES.md 供后续任务复用

5) 运维诊断

  • cortex_diagnostics:模型连通、层级状态、字段对齐检查
  • backfill_embeddings:支持 incremental / vector_only / full
  • lint_memory_wiki:Wiki/图谱一致性巡检与修复建议
  • 完整状态文件:便于快速定位同步、回填、质量问题

已注册工具(与当前代码一致)

  • search_memory
  • store_event
  • query_graph
  • export_graph_view
  • lint_memory_wiki
  • list_graph_conflicts
  • resolve_graph_conflict
  • get_hot_context
  • get_auto_context
  • reflect_memory
  • sync_memory
  • backfill_embeddings
  • delete_memory
  • cortex_diagnostics(推荐)

工具参数速览

工具关键参数
search_memoryquery, top_k
store_eventsummary, entities, entity_types, outcome, relations
query_graphentity, rel, dir, path_to, max_depth
export_graph_viewwrite_snapshot
lint_memory_wiki无
list_graph_conflictsstatus, limit
resolve_graph_conflictconflict_id, action, note
get_hot_contextlimit
get_auto_contextinclude_hot
reflect_memory无
sync_memory无
backfill_embeddingslayer, batch_size, max_retries, retry_failed_only, rebuild_mode
cortex_diagnostics无
delete_memorymemory_id

Agent 使用手册(系统提示词)

可直接粘贴到 Agent 的系统提示词中使用

Cortex Memory 记忆插件使用规则(核心规则,不允许删除)

你已接入 Cortex Memory。必须遵循以下规则:

  1. 禁止臆造历史事实;凡涉及历史对话、用户偏好、项目既有决策,先检索再回答。
  2. 单个任务内避免频繁写入:store_event / reflect_memory 应按里程碑触发(通常每个完整任务 0-2 次)。
  3. 用户询问历史信息、偏好、项目上下文时:先调用 search_memory,再回答,触发词如“上次、之前、你记得、上个月、去年、上个星期、昨天、前天、我记得、你查一下”等。
  4. 需要当前会话热上下文时:调用 get_hot_context。
  5. 需要自动召回相关记忆时:调用 get_auto_context。
  6. 需要实体关系、依赖链路或路径关系时:调用 query_graph。
  7. 仅在“重要事项已结束且结论明确”后调用 store_event 记录结果;结论未定时先不写入。
  8. 当任务经历“失败 -> 调整 -> 成功”时:先用 store_event 记录失败原因与成功方案,再调用 reflect_memory 沉淀可复用规则。
  9. 需要导入历史会话时:调用 sync_memory。
  10. 当 cortex_diagnostics 显示 active/archive 有未向量化记录,或迁移后需重建向量层时:调用 backfill_embeddings(按需选择 incremental / vector_only / full)。
  11. 出现配置校验失败、记忆读写异常、检索结果异常或数据目录问题时:优先调用 cortex_diagnostics。
  12. 仅在用户明确要求删除记忆,且已确认 memory_id 时,才调用 delete_memory;禁止在未确认情况下自动删除。
  13. 工具调用失败时:读操作可重试一次;写操作(如 store_event / reflect_memory / delete_memory / resolve_graph_conflict)重试前先确认是否已成功落库,避免重复写入。
  14. 调用任意 Cortex Memory 工具前,先确认当前运行环境可见该工具;若工具不可见,必须立即报告“当前 lane 不可用”,不得虚构执行结果。
  15. sync_memory 与 backfill_embeddings 属于关键路径任务:执行前后应避免并发重复触发;若已有同任务进行中,复用当前结果或等待完成。
  16. 当用户明确请求 Cortex Memory 任务(如 sync_memory / search_memory / store_event)时,禁止切换到无关流程(如心跳巡检、日报、闲聊任务);若被系统任务打断,先完成用户请求再处理后台任务。
  17. 当 query_graph 返回 conflict_hint 时,不得静默覆盖冲突事实;应先调用 list_graph_conflicts,并与用户确认后再 resolve_graph_conflict。
  18. 需要解释图谱状态分布或排查投影异常时,优先调用 export_graph_view 与 lint_memory_wiki。
  19. 记忆检索结果与模型推断必须分开表述:可明确标注“来自记忆检索/图谱”与“基于当前信息的推断”。
  20. 涉及隐私或用户明确要求“不要记忆”的内容,禁止调用 store_event / reflect_memory 写入长期记忆。

快速开始

安装

bash
cd ~/openclaw
openclaw plugins install clawhub:openclaw-cortex-memory
openclaw plugins enable openclaw-cortex-memory

如果 clawhub: 安装出现 fetch failed,可改用 npm 包本地安装(推荐兜底):

bash
npm pack openclaw-cortex-memory@0.1.0-Alpha.34
openclaw plugins install ./openclaw-cortex-memory-0.1.0-Alpha.34.tgz
openclaw plugins enable openclaw-cortex-memory
rm ./openclaw-cortex-memory-0.1.0-Alpha.34.tgz

完成安装后,请先按下方"最小配置"示例配置 openclaw.json,确认配置无误后再启动 gateway。

更新

bash
rm -r ~/.openclaw/extensions/openclaw-cortex-memory
npm pack openclaw-cortex-memory@0.1.0-Alpha.34
openclaw plugins install ./openclaw-cortex-memory-0.1.0-Alpha.34.tgz
openclaw plugins enable openclaw-cortex-memory
rm ./openclaw-cortex-memory-0.1.0-Alpha.34.tgz
openclaw plugins list  --enabled
openclaw gateway restart

卸载

bash
cd ~/openclaw
openclaw plugins disable openclaw-cortex-memory
openclaw plugins uninstall openclaw-cortex-memory

如需卸载插件但保留记忆数据:

bash
cd ~/openclaw
openclaw plugins disable openclaw-cortex-memory
openclaw plugins uninstall openclaw-cortex-memory --keep-data

最小配置(推荐先跑起来)

json
{
  "plugins": {
    "allow": ["openclaw-cortex-memory"],
    "slots": { "memory": "openclaw-cortex-memory" },
    "entries": {
      "openclaw-cortex-memory": {
        "enabled": true,
        "config": {
          "autoSync": true,
          "autoReflect": false,
          "graphQualityMode": "warn",
          "wikiProjection": {
            "enabled": true,
            "mode": "incremental",
            "maxBatch": 100
          },
          "embedding": {
            "provider": "api",
            "model": "text-embedding-3-large",
            "apiKey": "${EMBEDDING_API_KEY}",
            "baseURL": "https://your-embedding-endpoint/v1",
            "dimensions": 3072
          },
          "llm": {
            "provider": "api",
            "model": "gpt-4",
            "apiKey": "${LLM_API_KEY}",
            "baseURL": "https://your-llm-endpoint/v1"
          },
          "reranker": {
            "provider": "api",
            "model": "BAAI/bge-reranker-v2-m3",
            "apiKey": "${RERANKER_API_KEY}",
            "baseURL": "https://your-reranker-endpoint/v1/rerank"
          }
        }
      }
    }
  }
}

如果你启用了工具白名单(tools.allow),请把插件 ID 也加入白名单,否则该插件工具在会话中会不可见:

json
{
  "tools": {
    "allow": ["openclaw-cortex-memory"]
  }
}

外部端点与凭证声明(审查说明)

本插件是本地长期记忆系统,但以下能力依赖用户自配置的外部模型端点:

  • embedding:向量化(/embeddings)
  • llm:写入门控、规则反思、读融合(/chat/completions)
  • reranker:候选重排序(/rerank)

对应凭证要求:

  • 环境变量(可选):EMBEDDING_API_KEY、LLM_API_KEY、RERANKER_API_KEY
  • 插件配置(常用):embedding.apiKey、llm.apiKey、reranker.apiKey
  • 端点配置:embedding.baseURL、llm.baseURL、reranker.baseURL

网络发送的数据边界

  • 会发送:用于模型推理的文本片段(如 query、候选摘要、转写片段、待向量化文本)
  • 不会主动发送:本地配置文件原文、系统环境变量全集、插件状态文件全集
  • 凭证使用方式:仅作为 Authorization: Bearer 请求头调用你配置的端点

风险与建议

  • 你应只配置可信模型网关,密钥权限最小化(建议专用 key)
  • 生产环境建议启用网关审计与请求日志脱敏
  • 如不希望联网推理,不要配置外部端点/密钥(相关能力将降级或跳过)
高级配置(默认已内置,不懂可以不改)
  • readFusion:融合候选数、通道权重、通道 TopK、最小 lexical/semantic 命中、长度归一
  • memoryDecay:最小衰减地板、默认半衰期、事件类型半衰期、anti-decay 参数
  • vectorChunking:分块大小、重叠、evidence 最大分块数
  • writePolicy:archive/active 质量阈值与文本长度限制
  • readTuning:打分权重、RRF 参数、recency 分桶、auto-context 轻量检索

数据目录

默认情况下(未配置 dbPath),数据目录为 OpenClaw workspace 下:

  • Linux/macOS: ~/.openclaw/workspace/memory/openclaw-cortex-memory
  • Windows: %USERPROFILE%\\.openclaw\\workspace\\memory\\openclaw-cortex-memory

如果当前进程无法识别 OpenClaw 基础目录(例如离线脚本直接运行且无相关环境变量),会回退到项目目录:

  • <projectRoot>/data/memory

如果在插件配置里设置了 dbPath,则以下文件都会写到你指定的 dbPath 下:

  • <memoryRoot>/CORTEX_RULES.md
  • <memoryRoot>/sessions/active/sessions.jsonl
  • <memoryRoot>/sessions/archive/sessions.jsonl
  • <memoryRoot>/graph/memory.jsonl
  • <memoryRoot>/graph/memory.md
  • <memoryRoot>/graph/mutation_log.jsonl
  • <memoryRoot>/graph/mutation_log.md
  • <memoryRoot>/graph/conflict_queue.jsonl
  • <memoryRoot>/graph/superseded_relations.jsonl
  • <memoryRoot>/wiki/index.md
  • <memoryRoot>/wiki/log.md
  • <memoryRoot>/wiki/entities/*.md
  • <memoryRoot>/wiki/topics/*.md
  • <memoryRoot>/wiki/timelines/*.md
  • <memoryRoot>/wiki/graph/view.json
  • <memoryRoot>/wiki/graph/timeline.jsonl
  • <memoryRoot>/wiki/graph/network.mmd
  • <memoryRoot>/wiki/graph/network.md
  • <memoryRoot>/wiki/.projection_index.json
  • <memoryRoot>/wiki/.rebuild_queue.jsonl
  • <memoryRoot>/vector/lancedb
  • <memoryRoot>/vector/lancedb_events.jsonl
  • <memoryRoot>/.sync_state.json
  • <memoryRoot>/.session_end_state.json
  • <memoryRoot>/.rule_store_state.json
  • <memoryRoot>/.dedup_index.json
  • <memoryRoot>/.read_hit_stats.json

常用命令

bash
npm run typecheck
npm run test:graph-quality
npm run test:graph-quality-zh

MIT License

Install

$
openclaw plugins install clawhub:openclaw-cortex-memory@latest
Downloads
Repository
deki18/openclaw-cortex-memory
Security audit
Review
Last updated
7mo ago
Current version
v0.1.0-Alpha.34
Type
Code Plugin
Download
ClawHub

Skills and plugins for OpenClaw agents. Part of the wider OpenClaw ecosystem.

Explore docs

SkillsPluginsOfficialAudits

Publish SkillPublish PluginCreate org

OverviewOpenClawDocsBlog

SupportGitHubDiscord

Built alongside the OpenClaw ecosystem

LobsterCrabboxClickClackCrabfleetOctopoolClawSweeperagent-skillsdiscrawlgitcrawlslacrawlnotcrawltelecrawlgraincrawlcrawlkitcrawlbaracpxmcporterTachikomaclawpatchclawbenchPeekaboocookbookplugin-inspectorwacrawlcrabpotAll projectsLobsterCrabboxClickClackCrabfleetOctopoolClawSweeperagent-skillsdiscrawlgitcrawlslacrawlnotcrawltelecrawlgraincrawlcrawlkitcrawlbaracpxmcporterTachikomaclawpatchclawbenchPeekaboocookbookplugin-inspectorwacrawlcrabpotAll projects

© 2026 OpenClaw Foundation

Privacy policy·Status·Deployed on Vercel·Powered by Convex

....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals
  hooks runners slash-commands skill.md templates scanners review-bots     safe browse paths   official gateways   publisher handles   org trust   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@
openclaw ecosystem    crabbox clickclack crawler packs gateway plugins   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship
---- downloads installs stars lineage ownership docs package integrity   >>> install scan publish verify    @@ gateway @@ registry @@ agents @@   :::: signed manifests ::::: moderated releases ::::: version history ::::
  safe browse paths   official gateways   publisher handles   org trust     30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship     hooks runners slash-commands skill.md templates scanners review-bots
....:: clawhub/openclaw ::....  skills plugins publishers trust signals   :::: signed manifests ::::: moderated releases ::::: version history ::::   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins
>>> install scan publish verify    @@ gateway @@ registry @@ agents @@     hooks runners slash-commands skill.md templates scanners review-bots   ---- downloads installs stars lineage ownership docs package integrity
  30 skills 12 plugins    /api/v1/skills   /owners   /audit   /ship   openclaw ecosystem    crabbox clickclack crawler packs gateway plugins     safe browse paths   official gateways   publisher handles   org trust
:::: signed manifests ::::: moderated releases ::::: version history ::::   ---- downloads installs stars lineage ownership docs package integrity   ....:: clawhub/openclaw ::....  skills plugins publishers trust signals