核心功能: 本技能提供中文交互、化工作流场景等能力。

持久记忆引擎（基础版）

面向 AI Agent 的基础持久记忆系统，在内置记忆之上构建并行的结构化本地存储，解决跨会话遗忘问题。本系统完全位于 ~/memory/，与内置 Agent 记忆并行运作，永不修改内置 MEMORY.md 与 workspace memory/ 目录。

核心能力

1. 分层结构化存储

用户自定义分类，每个条目以独立 Markdown 文件存储，支持 frontmatter 元数据：

---
title: Alpha项目
status: active
created: 2026-07-18
updated: 2026-07-18
tags: [web, react]
importance: 0.8
---

支持的元数据字段：title（标题）、status（状态：active/archived）、created/updated（时间戳）、tags（标签数组）、importance（重要度0-1）。常见分类：projects/（项目）、people/（人脉）、decisions/（决策）、knowledge/（知识库）。

2. 三层索引体系

根索引 -> 分类索引 -> 条目文件，三层导航确保快速定位：

层级	文件路径	作用
根索引	~/memory/INDEX.md	列出所有分类、描述、条目数
分类索引	~/memory/{分类}/INDEX.md	列出该分类所有条目、状态、文件名
条目文件	~/memory/{分类}/{条目}.md	完整条目内容与元数据

索引在每次写入条目时自动更新，确保检索路径畅通。

输出: 返回三层索引体系的执行结果,包含操作状态和输出数据。

3. 混合检索策略

按规模适配检索路径：

文件规模	检索策略	命令
小规模（<50文件）	grep 全文搜索	grep -r "关键词" ~/memory/{分类}/
中规模（50-500文件）	索引导航优先	查 INDEX.md 定位 -> 读条目文件

小规模直接 grep，大规模走索引导航定位条目文件。索引找不到再用 grep 全文搜索作为回退。

输出: 返回混合检索策略的执行结果,包含操作状态和输出数据。

4. 写入前去重检查

写入记忆条目前执行基础预检：

• grep 同分类下是否有相同 title 或高度相似内容
• 发现重复时提示用户，不自动覆盖
• 写入条目文件后同步更新分类 INDEX.md

使用流程

领先步：首次初始化

创建 ~/memory/ 目录和根索引 INDEX.md。与用户确认需要存储的内容类型，按需创建分类目录和分类索引。例如用户说"我有很多项目"则创建 ~/memory/projects/ 并初始化该分类的 INDEX.md。

第二步：写入记忆条目

当用户分享重要信息时，执行写入前去重检查，写入对应 ~/memory/{分类}/{条目}.md（含 frontmatter 元数据），更新该分类的 INDEX.md，然后响应用户。写入立即执行，不等待不批量。

第三步：检索记忆

优先走索引路径：查根索引 INDEX.md 找到目标分类 -> 查分类 INDEX.md 找到目标条目 -> 读取条目文件详情。

结果处理: 执行完成后,查看输出结果确认操作状态。成功时输出包含处理摘要和结果数据;失败时根据错误信息排查问题,参考错误处理章节获取恢复步骤。

错误处理

错误类型	原因	处理方式
找不到记忆条目	索引未同步更新，条目已写入但 INDEX.md 未追加记录	检查 INDEX.md 是否含该条目行，手动补录条目记录到分类索引
同一信息重复存储	写入前未执行去重检查，同一内容被多次写入	执行 grep 去重，合并重复条目，保留最新版本
记忆文件损坏	写入过程中断或磁盘错误导致 Markdown 文件格式损坏	从 Git 备份恢复；无备份时从 frontmatter 重建条目骨架

示例

示例：写入项目记忆并更新索引

场景：用户说"Alpha项目用 React + TypeScript + Tailwind，目标是构建客户管理系统，今天选定了 React 而非 Vue"。

# 写入条目
cat > ~/memory/projects/alpha.md << 'EOF'
---
title: Alpha项目
status: active
created: 2026-07-18
updated: 2026-07-18
tags: [web, react, typescript, tailwind]
importance: 0.8
---

## 项目概要
技术栈：React + TypeScript + Tailwind
目标：构建客户管理系统

## 关键决策
- 2026-07-18：选定 React 而非 Vue（团队熟悉度）
EOF

# 更新分类索引
echo "| Alpha项目 | active | 2026-07 | alpha.md |" >> ~/memory/projects/INDEX.md

代理响应："已将 Alpha项目 记忆写入 ~/memory/projects/alpha.md 并更新索引。"

FAQ

Q1: 这会和我 Agent 自带的记忆冲突吗？

不会。本系统完全并行，位于 ~/memory/，永不修改内置 MEMORY.md 与 workspace memory/。内置记忆负责当前会话快速上下文，本系统负责长期存储，两者协同。

Q2: 记忆文件越来越多会不会很慢？

三层索引体系确保即使大量文件也能快速定位。小规模用 grep 直接搜索，大规模走索引导航优先定位条目文件，索引找不到再回退到 grep 全文搜索。

Q3: 能不能多设备同步？

本技能不提供云同步。可通过 Git 或云盘同步 ~/memory/ 目录实现多设备。注意 .trash/ 目录可加入 .gitignore 避免同步无用数据。

依赖说明

运行环境

• Agent平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• 本地存储：可写的 ~/memory/ 目录

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供
文件系统（可写 ~/memory/）	本地存储	必需	操作系统自带
grep / find	系统命令	必需	操作系统自带
cat / mkdir / echo	系统命令	必需	操作系统自带

API Key 配置

• 核心功能无需任何 API Key

可用性分类

• 分类：MD+EXEC（Markdown指令驱动，需exec执行文件操作命令）
• 说明：通过自然语言指令驱动Agent执行记忆存储和检索操作

已知限制

1. 无记忆生命周期管理：基础版不支持写入->激活->归档->遗忘四阶段生命周期，条目不会自动归档或清理，需用户手动管理。
2. 无冲突检测与版本化：基础版不自动检测新旧信息矛盾，写入时遇到同主题条目仅提示去重，不保留版本历史。
3. 无分类自动分裂：基础版不支持单分类超过100条目时自动分裂为子分类，大规模分类检索效率会下降。
4. 无回收站恢复：基础版不提供遗忘阶段的回收站机制，删除的条目无法恢复。
5. 无向量语义检索：基础版仅支持 grep 关键词检索和索引导航，超大规模（500+文件）场景下召回率有限。

升级提示

当前为基础版，以下高级能力需升级至完整版解锁：

• 记忆生命周期管理：每个条目经历"写入->激活->归档->遗忘"四阶段，超过90天未更新提示归档，归档超过180天无引用提示遗忘，避免记忆膨胀拖慢检索。
• 冲突检测与版本化：写入前扫描同分类同主题条目，发现矛盾时不直接覆盖，保留旧版本并递增 version，主动提示用户冲突情况。
• 分类自动分裂：单分类条目数超过100时按状态或时间自动分裂为子分类，确保大规模检索效率。
• 回收站恢复机制：遗忘阶段条目移入 ~/memory/.trash/，保留30天可恢复，支持 trash_retention_days 参数自定义保留期。
• 写入前完整预检：去重检查 + 冲突检测 + 索引同步 + 原子写入四步预检流程，任一步骤失败自动回滚。
• 超大规模向量检索：500+文件场景下接入 Chroma/LanceDB/Qdrant 向量数据库做语义检索增强，按规模自动推荐最优检索策略。

升级至完整版以获取全部8项核心能力、8个领域专属错误处理场景和3个完整实战案例。

安全注意事项

风险类型	防范措施
API密钥泄露	通过环境变量配置，禁止硬编码到代码或配置文件中
命令执行风险	仅执行白名单命令，避免拼接用户输入到命令行参数中
敏感数据暴露	输出结果中不包含密钥、令牌等敏感信息

使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。

效率量化分析

操作场景	手动耗时	自动化耗时	效率提升
文件解析与提取	5-10分钟/个	<5秒/个	60-120x
批量文件处理(100个)	8-16小时	<5分钟	96-192x
API调用与响应解析	2-3分钟/次	<1秒/次	120-180x
多接口数据聚合	15-30分钟	<10秒	90-180x
命令执行与结果收集	3-5分钟/次	<2秒/次	90-150x
重复任务批量执行	因任务而异	线性缩减	5-50x
错误排查与修复	10-30分钟	<30秒	20-60x

差异化对比

对比维度	本技能	传统手动方式	通用脚本工具
自动化程度	全流程自动	完全手动	部分自动
错误处理	内置错误恢复	依赖人工经验	基本try-catch
可复用性	参数化配置	一次性脚本	模板化
安全合规	内置安全检查	无安全保障	无安全保障
适用场景	核心功能	通用场景	通用场景

核心功能

• 自动化执行: 基于指令驱动的自动化流程
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据