Smart Agent Memory

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

Security Scan

The skill's code and CLI largely match its stated local memory purpose, but there are packaging/metadata inconsistencies and a setup behavior that may write outside the declared memory path (possible scope creep) which merits caution.

Purpose & Capability

Name/description (local agent long-term memory) align with provided code (remember/recall/search, GC, extract to SKILL.md, temperature model, SQLite fallback). Declared binary requirement is only 'node', which matches. However SKILL.md and README claim 'setup' will auto-discover ~/.openclaw/workspace* and inject BOOTSTRAP.md into discovered workspaces; the skill metadata permissions list only read/write for ~/.openclaw/workspace/memory. That is an incoherence: the described setup behavior implies writing outside the declared memory directory (modifying other workspace files), which is not obviously necessary for the core memory functionality.

Instruction Scope

Runtime instructions and CLI are narrowly scoped to reading/writing memory files, building indexes, and optional cron jobs for GC/reflect. No instructions request external network access or unrelated system data. The notable scope creep is the documented setup: auto-discovering all workspaces and injecting BOOTSTRAP.md (modifying other workspace roots). The skill also suggests agent-level cron job additions via OpenClaw's cron tool — sensible for scheduled tasks but should be an explicit user action (not automatic).

Install Mechanism

No external installers, downloads, or package fetches are present. Code is bundled (no install spec). All code uses standard Node.js built-ins and local filesystem operations; SQLite backend uses node:sqlite (native module) when available. This is low-risk from an install mechanism perspective.

Credentials

The skill requests no environment variables or external credentials and only requires the 'node' binary, which is proportionate. Metadata declares read/write permissions for ~/.openclaw/workspace/memory which matches most file operations. However, the documented 'setup' behavior that injects BOOTSTRAP.md into all ~/ .openclaw/workspace* directories suggests broader write activity than the declared permission scope — this should be confirmed before running setup.

Persistence & Privilege

The skill is not always-enabled and does not request special credentials. Still, it intentionally persists data to the user's ~/.openclaw/workspace/memory and suggests installing scheduled cron-like jobs via OpenClaw's cron tool. The setup step claims to modify other workspace directories by injecting BOOTSTRAP.md (modifying files outside its own memory subdirectory), which elevates its footprint and should be treated as an impactful filesystem modification.

What to consider before installing

This package appears to implement a local agent memory system matching its description, but exercise caution before enabling it broadly. What to check before installing/activating: - Inspect and run 'setup' only after reviewing its implementation: confirm exactly which paths it writes to (does it write BOOTSTRAP.md outside ~/.openclaw/workspace/memory?). Prefer running setup in a safe environment or with a dry-run if available. - Backup your ~/.openclaw/workspace* directories before running setup so you can revert any injected files. - The skill suggests adding scheduled jobs via the platform cron tool — do not accept automatic cron additions without reviewing the job JSON. Add jobs manually if you want them. - Packaging inconsistencies exist (versions in SKILL.md/_meta.json differ and homepage/source are missing). Treat the author as unverified; prefer installing in an isolated environment first (container or throwaway account) and review behavior. - If you need SQLite features, ensure Node.js >= 22.5 is acceptable for your environment; otherwise the code will use JSON mode. If you want higher assurance, ask the maintainer for a canonical homepage/repo and a signed release, or for a minimal dry-run mode for setup that shows what files would be changed without modifying disk.

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

安装技能后运行一次：

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（除非你确切知道要搜什么）
• 不要把记忆操作全堆到对话结束时

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 参数传入。