Smart Agent Memory

跨平台 Agent 长期记忆系统。分层上下文供给 + 温度模型 + Skill经验记忆 + 结构化存储 + 自动归档。三层存储：Markdown（人可读，QMD 可搜索）+ JSON（结构化）+ SQLite/FTS5（高性能全文搜索）。纯 Node.js 原生模块，零外部依赖。

Security Scan

Skill mostly matches its stated purpose (local long-term memory) but contains several surprising/intrusive behaviors (workspace-wide injection, file writes, skill extraction) and a metadata inconsistency that you should review before enabling it.

Purpose & Capability

The name/description describe a local, Node.js-based long-term memory system and the included code implements that: search, JSON/SQLite stores, Markdown logs, GC, temperature model, and a CLI. Declared runtime requirement (node) aligns. However, SKILL.md advertises explicit read/write permissions for ~/.openclaw/workspace/memory while the registry metadata in the manifest lists no required config paths — a mismatch. Also the CLI's setup scans and modifies all ~/.openclaw/workspace* workspaces (injecting BOOTSTRAP.md), which is more intrusive than a simple single-directory memory helper and should be expected only if the skill truly needs to touch multiple workspaces.

Instruction Scope

Runtime instructions explicitly tell the agent to run a one-time setup that 'automatically discover(s) ~/.openclaw/workspace* and inject BOOTSTRAP.md' into each workspace, plus recommended cron jobs that cause regular autonomous runs of reflect/gc. The code also supports extracting lessons into SKILL.md templates (lib/extract.js) — i.e., generating skill files. These behaviors write to and modify multiple workspace paths and can create skill-like artifacts; they go beyond read-only memory lookup and could unexpectedly modify project/skill directories. The SKILL.md also claims a platform-level 'memory_search' automatic recall integration — verify that this is actually provided by your platform and not an assumption.

Install Mechanism

There is no remote install step (instruction-only plus included JS files), so nothing is downloaded at install time. That reduces remote-code-fetch risk. The code does execFileSync('qmd' ...) when qmd is present (lib/search.js) — qmd is optional but this launches an external binary if available; SKILL.md did not list qmd as a required binary, so the search may call an external tool unpredictably if present on PATH.

Credentials

The skill requests no credentials or environment secrets and only needs Node and filesystem access. That is consistent with a local memory store. However, SKILL.md metadata declares 'trust: high' and explicit read/write permissions for ~/.openclaw/workspace/memory; the registry metadata did not declare required config paths — this mismatch should be resolved. The code uses MEMORY_DIR env var as an override, which is reasonable and not a secret, but the default places data under ~/.openclaw/workspace/memory and modifies workspace directories.

Persistence & Privilege

always:false (no forced global enable) and autonomous invocation is not disabled (normal). The real concern is the skill's ability to modify multiple workspaces during setup (inject BOOTSTRAP.md), archive/move files under .archive, append files to daily logs and skills directories, and potentially write SKILL.md files via extraction. Those are persistent, write-capable operations that alter agent/ workspace state and could change what agents see or what skills exist. This elevated filesystem write capability is coherent with a memory tool but is a meaningful privilege that should be reviewed and limited if undesired.

What to consider before installing

What to check before installing: - Understand and accept that this skill will write to and modify your home workspace paths (default: ~/.openclaw/workspace/memory) and — during setup — will scan and inject BOOTSTRAP.md into every ~/.openclaw/workspace* it finds. If you have private or sensitive projects in those workspaces, back them up first. - The CLI can create or append Markdown and JSON/SQLite files, archive old logs, and can auto-generate SKILL.md templates from lessons (i.e., it can create skill-like files). Decide whether you want a skill that can produce new skill artifacts or alter workspace content. - There is a metadata inconsistency: the SKILL.md advertises explicit read/write permissions but the registry metadata lists no required config paths. Confirm which is authoritative and whether you are comfortable granting those filesystem permissions. - The code may call an external binary 'qmd' if present (for hybrid search). If you do not want that binary invoked, ensure it's absent from PATH or review/modify lib/search.js. - If you plan to use it across multiple agents or teams, set governance/ownership rules for the shared memory directory to avoid noisy writes or accidental leaks across agents. - To minimize risk: run setup manually and inspect what files it writes (or run in an isolated test account/sandbox), review the memory-cli.js extract and setup implementations, and consider restricting MEMORY_DIR to a dedicated directory (set MEMORY_DIR env) before running setup. Given these intrusive but explainable capabilities (workspace-wide injection and skill extraction), the skill is coherent with its stated purpose but contains behaviors that could be surprising or risky; treat it as 'suspicious' until you verify and constrain its actions.

Smart Agent Memory 🧠 v2.1

跨平台 Agent 长期记忆系统 — 分层上下文供给 + Skill经验记忆 + 温度模型 + 自动归档。

⚡ 核心原则：分层加载，按需供给

绝对不要全量加载记忆！ 先读索引，再按需钻取。这是省 token 的关键。

记忆使用流程（每次需要记忆时）

1. index    → 读取精简索引（总览，<500 tokens）
2. 判断     → 根据当前任务决定需要哪部分记忆
3. context  → 按 tag/skill/时间 加载具体上下文
4. 行动     → 基于加载的上下文执行任务

Skill 经验记忆流程（工具调用后）

工具调用成功/踩坑 → remember "经验总结" --skill <skill-name>
下次调用该工具前 → skill-mem <skill-name> 加载经验

CLI Reference

CLI=~/.openclaw/skills/smart-agent-memory/scripts/memory-cli.js

# ★ 分层上下文（核心，优先使用）
node $CLI index                              # 精简记忆索引（先读这个！）
node $CLI context --tag <tag>                # 按标签加载上下文
node $CLI context --skill <skill-name>       # 按 Skill 加载经验+相关事实
node $CLI context --days 7                   # 最近 N 天的记忆
node $CLI context --entity-type person       # 按实体类型加载

# ★ Skill 经验记忆
node $CLI remember "该API时间参数必须用ISO格式" --skill api-tool
node $CLI skill-mem <skill-name>             # 读取某 Skill 的经验
node $CLI skill-list                         # 列出所有有经验记忆的 Skill

# 基础记忆操作
node $CLI remember <content> [--tags t1,t2] [--skill name] [--source conversation]
node $CLI recall <query> [--limit 10]
node $CLI forget <id>
node $CLI facts [--tags t1] [--limit 50]

# 教训与实体
node $CLI learn --action "..." --context "..." --outcome positive --insight "..."
node $CLI lessons [--context topic]
node $CLI entity "Alex" person --attr role=CTO
node $CLI entities [--type person]

# ★ 会话生命周期（模拟 mem9 自动钩子）
node $CLI session-start                      # 对话开场：加载记忆概览+最近上下文（一个命令搞定）
node $CLI session-end "本次讨论了XX，决定了YY"  # 对话结束：存会话摘要

# 维护
node $CLI gc [--days 30]                     # 归档冷数据
node $CLI reflect                            # 夜间反思
node $CLI stats                              # 记忆健康
node $CLI search <query>                     # 全文搜索 .md（优先qmd，兜底内置）
node $CLI temperature                        # 温度报告
node $CLI extract <lesson-id> --skill-name x # 提炼 Skill

Setup / Config / Scripts

Setup（必须执行一次）

node ~/.openclaw/skills/smart-agent-memory/scripts/memory-cli.js setup

自动发现 ~/.openclaw/workspace* 下所有工作区，逐个注入 BOOTSTRAP.md。

Storage / Config

• 依赖：node
• 默认存储：~/.openclaw/workspace/memory/
• 单 agent：直接使用本地 workspace 记忆
• 共享 workspace / 多 agent：多个 agent 可共享同一记忆目录
• 多 workspace 场景：setup 会自动扫描并注入

Session Init / Finish

node ~/.openclaw/skills/smart-agent-memory/scripts/memory-cli.js session-start
node ~/.openclaw/skills/smart-agent-memory/scripts/memory-cli.js session-end "本次做了什么"

Common Scripts

安装技能后运行一次：

node ~/.openclaw/skills/smart-agent-memory/scripts/memory-cli.js setup

自动发现 ~/.openclaw/workspace* 下所有工作区，逐个注入 BOOTSTRAP.md 记忆启动指令。 幂等，新增工作区后再跑一次即可。

Agent 行为规范

🔄 记忆召回（已自动）

所有 agent 通过 memory_search（OpenClaw 内置 mandatory recall）自动搜索 memory/*.md。 双层存储确保每次写入都同步生成 Markdown，所以 memory_search / qmd 天然能搜到所有结构化数据。 无需额外操作，无需 workspace 配置，跨 agent 通用。

需要深入某方向时，用 CLI 钻取：

node $CLI context --tag <tag>       # 按标签
node $CLI context --skill <name>    # 按 Skill 经验
node $CLI context --days 7          # 按时间

📝 记忆写入（有内容就写）

node $CLI remember "关键信息" --tags tag1,tag2    # 事实
node $CLI learn --action "..." --context "..." --outcome positive --insight "..."  # 教训
node $CLI session-end "本次讨论了XX，决定了YY"    # 会话摘要

⚠️ 不要攒到最后！ 有内容就写，中途断了也不丢。 每晚 cron 兜底检查，确保不遗漏。

✅ MUST DO

• 每次需要历史信息时：先 index，看概览，再决定加载哪部分
• 工具调用踩坑后：remember "经验" --skill <name> 沉淀经验
• 调用不熟悉的工具前：skill-mem <name> 检查有没有历史经验
• 记录新信息时：打好 tags，方便后续按需检索
• 搜索记忆时：search 命令优先走 qmd（语义搜索），qmd 不可用时自动降级为内置 TF 搜索

❌ NEVER DO

• 不要一次性 facts --limit 999 全量加载
• 不要在每轮对话都加载全部记忆
• 不要忽略 index 直接 recall（除非你确切知道要搜什么）
• 不要把记忆操作全堆到对话结束时

🔗 多 Agent 调度经验记忆

当 spawn 子 agent 成功/失败时，立即记录经验：

node $CLI remember "spawn 子 agent 用 runtime=subagent 成功，不能带 streamTo" --skill multi-agent-dispatch --tags spawn,subagent

关键经验已沉淀：

• runtime="subagent" 模式禁止带 streamTo 参数（会直接报错）
• runtime="acp" 模式可带 streamTo="parent"（仅限 openclaw.json 中配置了 runtime.type: "acp" 的 agent）
• 子 agent 结果通过 auto-announce 自动推送，不需要轮询

Storage Layout

~/.openclaw/workspace/memory/
├── YYYY-MM-DD.md           ← 每日日志
├── skills/                 ← ★ Skill 经验记忆（新增）
│   ├── api-tool.md
│   └── deploy.md
├── lessons/                ← 教训 Markdown
├── decisions/              ← 决策 Markdown
├── people/                 ← 人物档案
├── reflections/            ← 反思记录
├── .data/                  ← JSON 结构化数据
├── .archive/               ← 归档冷数据
└── .index.json             ← 温度索引 + 统计

Recommended Cron Jobs

安装后建议通过 OpenClaw cron 工具添加以下定时任务：

每晚反思（推荐）

{
  "name": "memory-reflect",
  "schedule": { "kind": "cron", "expr": "45 23 * * *", "tz": "Asia/Shanghai" },
  "payload": {
    "kind": "agentTurn",
    "message": "运行记忆反思：node ~/.openclaw/skills/smart-agent-memory/scripts/memory-cli.js reflect，然后总结今天的记忆变化。"
  },
  "sessionTarget": "isolated",
  "delivery": { "mode": "none" }
}

每周日 GC 归档（推荐）

{
  "name": "memory-gc",
  "schedule": { "kind": "cron", "expr": "0 2 * * 0", "tz": "Asia/Shanghai" },
  "payload": {
    "kind": "agentTurn",
    "message": "运行记忆GC：node ~/.openclaw/skills/smart-agent-memory/scripts/memory-cli.js gc --days 30，报告归档了多少条记忆。"
  },
  "sessionTarget": "isolated",
  "delivery": { "mode": "none" }
}

每日会话摘要检查（可选，弥补遗忘）

{
  "name": "memory-session-check",
  "schedule": { "kind": "cron", "expr": "0 22 * * *", "tz": "Asia/Shanghai" },
  "payload": {
    "kind": "agentTurn",
    "message": "检查今天的记忆情况：运行 node ~/.openclaw/skills/smart-agent-memory/scripts/memory-cli.js stats，如果今天有对话但 facts 没增长，回顾今天的对话并用 session-end 补存摘要。"
  },
  "sessionTarget": "isolated",
  "delivery": { "mode": "none" }
}

Agent 可用 cron 工具的 add action 直接添加以上任务，JSON 作为 job 参数传入。