Agent Memory Palace

为 AI Agent 提供持久化记忆管理，支持语义搜索、时间推理、经验积累和智能遗忘。

Security Scan

The skill's code and docs largely match its stated purpose (local, file-backed agent memory with optional vector search), but there are several implementation details that don't fully add up or raise caution (postinstall script, example/test files with hardcoded absolute paths, and CLI usage that can fetch/execute package code).

Purpose & Capability

Name/description (persistent memory, semantic search, time reasoning, compression, experience recording) align with the included source files (manager, storage, vector-search, LLM helpers). Required envs/credentials are none and that matches the declared metadata. The feature set and code footprint are coherent with the described functionality.

Instruction Scope

SKILL.md stays within the memory-management domain: it documents write/search/experience/summarize/parse_time and describes local file storage and an optional vector service. It does reference optional environment variables (OPENCLAW_WORKSPACE/HF_ENDPOINT and memory decay flags) which are reasonable. However, several example/test scripts (e.g. scripts/ab-test/debug-wednesday.ts) contain hardcoded absolute paths (/data/..., /data/.subagent/.jarvis) and local host vector-service configs which, if executed without review, could attempt to read or write outside a user-expected workspace. Those examples are out-of-band for the core runtime but increase risk if run blindly.

Install Mechanism

The skill package includes package.json and package-lock.json and defines a CLI (bin/memory-palace.js). package.json has a postinstall script (node scripts/check-vector-deps.cjs) which will run during npm install — postinstall scripts can execute arbitrary code on install and thus are a notable risk. SKILL.md allows running Bash commands via npx memory-palace:*; using npx to fetch and run the package on-demand means the agent (or user) could trigger remote package download and execution. There is no install spec in the registry metadata, but the presence of full package sources means installs (or npx invocations) will execute the code provided in this bundle or fetched from the registry—this is expected for a CLI skill but elevates risk compared to an instruction-only skill.

Credentials

The skill declares no required credentials or sensitive env vars and primarily uses workspace paths for storage (OPENCLAW_WORKSPACE or HOME). SKILL.md documents optional env vars (MEMORY_DECAY_*, HF_ENDPOINT) which are appropriate for behavior tuning and optional model download configuration. No unrelated secrets are requested. Caveat: README and scripts mention downloading models (HuggingFace mirror) and starting a Python vector-service; those operations access remote endpoints and download model files — acceptable for optional vector features but worth noting before enabling.

Persistence & Privilege

Flags are normal: always:false, user-invocable:true, disable-model-invocation:false. The skill writes persistent memory to a workspace directory (expected for its purpose) and does not request elevated platform privileges. There is no evidence it modifies other skills or global agent configs. The default ability for the agent to invoke the skill autonomously is standard; combine with other concerns (postinstall, npx fetching) when deciding to allow autonomous execution.

What to consider before installing

This skill appears to implement a local persistent memory system that matches its documentation, but take these precautions before installing or running it: - Review postinstall and scripts: package.json defines a postinstall script (scripts/check-vector-deps.cjs). Postinstall scripts run code during npm install — inspect that file to ensure it only checks dependencies and doesn't run unexpected commands. - Be cautious with npx usage: SKILL.md allows running the CLI via npx memory-palace:*. npx will download and run package code if not installed locally. Only run npx for packages you trust or install the package after auditing the source. - Don’t run example/test scripts without review: several ab-test/example scripts include hardcoded absolute paths (e.g., /data/.subagent/.jarvis, /data/agent-memory-palace) and local host vector-service settings. Running them as-is could read or write outside your intended workspace. - Vector/model downloads are optional but networked: enabling semantic search may download models from Hugging Face or mirrors; ensure you trust those endpoints and have bandwidth/space. If you want to avoid external downloads, run the skill in text-search fallback mode only. - Sandbox first: consider installing/running this skill in an isolated environment (container or VM) and point workspaceDir to a controlled directory. Inspect scripts/check-vector-deps.cjs, scripts/vector-service.py and any postinstall hooks before allowing them to run. If you want, I can open and summarize the specific files of highest concern (scripts/check-vector-deps.cjs, scripts/vector-service.py, and any postinstall-related code) so you can see exactly what they do.

Memory Palace

Agent 的持久化记忆系统。让 AI Agent 能够记住用户偏好、对话上下文、项目状态、经验教训，并在需要时主动检索。

🚀 快速开始

首次使用： 无需配置，向量模型未安装时自动降级到文本搜索。

立即可用：

// 记住用户说的话
memory_palace_write: { "content": "用户叫盘古，喜欢简洁的回复", "tags": ["用户", "偏好"], "importance": 0.9 }

// 下次想知道用户叫什么
memory_palace_search: { "query": "用户名字" }

// 记住项目的关键决策
memory_palace_write: { "content": "决定使用 PostgreSQL 作为主数据库", "tags": ["项目决策", "数据库"], "importance": 0.8 }

---

📋 工具选择指南

场景 1：用户告诉了我一些信息 → 写入记忆

用户说：「我叫张三」
→ memory_palace_write: { "content": "用户名叫张三", "tags": ["用户信息"], "importance": 0.7 }

场景 2：需要回忆某件事 → 搜索记忆

用户问：「我上次说叫什么名字？」
→ memory_palace_search: { "query": "用户名字" }

场景 3：完成了一个任务，学到了经验 → 记录经验

用户完成了一个 API 设计任务
→ memory_palace_record_experience: { "content": "REST API 设计时用名词而非动词命名端点", "category": "development", "applicability": "设计新的 API 端点时", "source": "task-xxx" }

场景 4：需要判断某个经验是否有用 → 验证经验

之前记录过一条经验，现在在类似场景下
→ memory_palace_verify_experience: { "id": "经验ID", "effective": true }  // 或 false

场景 5：长记忆需要提炼 → 智能总结

用户分享了一段很长的需求描述
→ memory_palace_summarize: { "id": "记忆ID" }

场景 6：记忆太多太杂，需要整理 → 压缩或提取经验

项目进行了很久，积累了很多对话记录
→ memory_palace_extract_experience: { "category": "development" }  // 提取开发经验
→ memory_palace_compress: { "memory_ids": ["id1", "id2", ...] }  // 压缩多条记忆

---

工具列表

基础操作（最常用）

工具	功能	何时用
memory_palace_write	写入记忆	用户告诉你任何重要信息时
memory_palace_get	获取记忆	知道 ID，要查看完整内容
memory_palace_update	更新记忆	发现记忆有误或需要补充
memory_palace_delete	删除记忆	记忆过时或错误时
memory_palace_search	搜索记忆	需要找某件事但不确定 ID
memory_palace_list	列出记忆	想看看记忆库里都有什么

经验管理（进阶）

工具	功能	何时用
memory_palace_record_experience	记录可复用经验	完成重要任务、学到教训时
memory_palace_get_experiences	查询经验	想参考过去的经验
memory_palace_verify_experience	验证经验有效性	在类似场景验证经验是否正确
memory_palace_get_relevant_experiences	查找相关经验	当前任务需要过去的经验指导
memory_palace_experience_stats	经验统计	查看经验库健康度

LLM 增强（智能处理）

工具	功能	何时用	超时
memory_palace_summarize	智能总结长记忆	记忆内容太长时提炼要点	60s
memory_palace_parse_time	解析时间表达	用户提到"明天"、"下周三"等	10s
memory_palace_extract_experience	从记忆提取经验	从对话中自动抽取可复用经验	60s
memory_palace_expand_concepts	语义扩展搜索	普通搜索找不到时扩展概念	15s
memory_palace_compress	智能压缩记忆	记忆太多需要精简	60s

回收站

工具	功能
memory_palace_restore	从回收站恢复记忆

---

参数详解

memory_palace_write

必填：

• content: 记忆内容（你想记住什么）

可选：

• tags: 标签数组，方便分类检索，如 ["用户", "偏好", "重要"]
• importance: 重要性 0-1，建议 0.7+ 表示重要记忆
• location: 存储位置，默认 "default"，如 "用户"、"项目A"、"日程"
• type: 类型
  • fact - 事实（默认）
  • experience - 经验
  • lesson - 教训
  • preference - 偏好
  • decision - 决策

memory_palace_search

必填：

• query: 搜索关键词（可以是自然语言描述）

可选：

• tags: 只搜索特定标签
• topK: 返回数量，默认 10

memory_palace_record_experience

必填：

• content: 经验内容
• applicability: 这个经验在什么场景下有用
• source: 来源标识（如任务 ID）

可选：

• category: 类别
  • development - 开发
  • operations - 运维
  • product - 产品
  • communication - 沟通
  • general - 一般

---

使用示例

记住用户偏好

memory_palace_write: { 
  "content": "用户偏好深色模式，喜欢简洁的回复风格",
  "tags": ["偏好", "UI"],
  "importance": 0.9,
  "type": "preference"
}

记住项目状态

memory_palace_write: { 
  "content": "MiroFish 项目已完成 MVP 开发，正在准备上线",
  "location": "MiroFish",
  "tags": ["项目", "状态"],
  "importance": 0.8,
  "type": "fact"
}

记录技术决策

memory_palace_record_experience: { 
  "content": "TypeScript 的 as const 可以让类型推断更精确",
  "category": "development",
  "applicability": "需要精确类型推断的场景，如配置对象、常量定义",
  "source": "MiroFish-dev"
}

查找相关经验

memory_palace_get_relevant_experiences: { 
  "context": "需要为新项目选择数据库",
  "limit": 3
}

智能总结

memory_palace_summarize: { 
  "id": "memory-id",
  "save_summary": true
}

---

工作原理

记忆写入流程

1. Agent 调用 write
2. 记忆存储到本地文件系统（Markdown 格式）
3. 如果有向量模型，同时建立语义索引
4. 返回记忆 ID，可用于后续检索

记忆搜索流程

1. Agent 调用 search 或 recall
2. 如果有向量模型，进行语义相似度匹配
3. 同时进行关键词匹配和过滤
4. 结合 importance 和 decayScore 排序
5. 返回最相关的记忆

遗忘机制（艾宾浩斯遗忘曲线）

记忆宫殿内置艾宾浩斯遗忘曲线机制，模拟人类记忆的自然衰减：

核心机制：

• 每条记忆有 decayScore（0-1），初始为 1.0
• 每次访问记忆，decayScore = min(1, decayScore × 0.9 + 0.2)
• decayScore < 0.1 时，记忆自动归档（可恢复）
• 归档记忆仍可搜索到，但权重降低

环境变量配置：

变量	默认值	说明
MEMORY_DECAY_ENABLED	true	启用衰减
MEMORY_DECAY_ARCHIVE_THRESHOLD	0.1	归档阈值
MEMORY_DECAY_RECOVERY_FACTOR	0.2	恢复因子

向后兼容： 已有的记忆自动初始化 decayScore = 1.0

---

注意事项

1. 向量模型可选 — 未安装时自动降级到文本搜索，不影响基本功能
2. 记忆是持久化的 — 写入后即使重启也保留
3. 经验需要验证 — 记录的经验需要 2+ 次验证才标记为"已验证"
4. 标签很重要 — 好的标签能大幅提升检索精度
5. 重要性建议 — 真正重要的记忆设置 0.7+，便于后续优先检索

---

故障排除

问题	解决方案
搜索找不到	用 expand_concepts 扩展搜索词
记忆太多	用 compress 压缩或 extract_experience 提炼
不确定记忆是否正确	用 verify_experience 验证
想不起某件事	用 search 配合关键词搜索