持久记忆引擎

核心功能: 本技能提供完整工作流程和配置指南、化工作流场景等能力。

持久记忆引擎（Persistent Memory Engine）

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

功能特性总览

1. 无限分层结构化存储

用户自定义分类，无预设结构限制。常见分类如 projects/、people/、decisions/、knowledge/、collections/，每个条目以独立 Markdown 文件存储，支持 frontmatter 元数据（状态、版本、重要度、标签、关联条目、过期时间）.

处理: 解析无限分层结构化存储的输入参数,完成核心逻辑,输出标准化响应数据. 输出: 返回无限分层结构化存储的响应数据,含执行状态与操作日志.

2. 三层索引体系

根索引 ~/memory/INDEX.md 列出所有分类 → 分类索引 ~/memory/{分类}/INDEX.md 列出该分类所有条目 → 条目文件本身。三层导航确保 500+ 文件规模也能 O(1) 定位，无需全量扫描.

处理: 解析三层索引体系的输入参数,完成核心逻辑,输出标准化响应数据. 输出: 返回三层索引体系的响应数据,含执行状态与操作日志.

• 通过input_params参数指定操作类型(创建/查询/导出)

3. 混合检索策略

小规模（< 50 文件）用 grep 直接搜；大规模（50-500 文件）走索引导航；超大规模（500+ 文件）建议接入向量检索（语义回退）。按规模自动适配最优检索路径.

处理: 解析混合检索策略的输入参数,完成核心逻辑,输出标准化响应数据. 输出: 返回混合检索策略的响应数据,含执行状态与操作日志.

• 通过input_params参数指定操作类型(创建/查询/导出)

4. 记忆生命周期管理

每个条目经历"写入→激活→归档→遗忘"四阶段。超过 90 天未更新提示归档，归档超过 180 天无引用提示遗忘，过期条目移入 .trash/ 保留 30 天可恢复，避免记忆膨胀拖慢检索.

处理: 解析记忆生命周期管理的输入参数,完成核心逻辑,输出标准化响应数据. 输出: 返回记忆生命周期管理的响应数据,含执行状态与操作日志.

• 通过input_params参数指定操作类型(创建/查询/导出)

5. 冲突检测与版本化

写入前扫描同分类同主题条目，发现矛盾时不直接覆盖，保留旧版本并递增 version，主动提示用户"检测到冲突，已保留两版本"。从内置记忆单向同步，反向永不修改内置记忆.

处理: 解析冲突检测与版本化的输入参数,完成核心逻辑,输出标准化响应数据. 输出: 返回冲突检测与版本化的响应数据,含执行状态与操作日志.

• 通过input_params参数指定操作类型(创建/查询/导出) 能力覆盖范围：支持的场景关键词如下：解决跨会话遗忘、检索不准、记忆膨胀冲突的无、限分层持久记忆引、Agent、的无限分层持久记、忆系统、直击跨会话遗忘、新旧冲突四大痛点、适用于长周期项目、人脉网络、决策归档、领域知识库等场景、核心能力含三层索、适用关键词、长期记忆、跨会话记忆、记忆管理、记忆检索、持久化存储、persistent等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

场景示例

不适用场景：

• 临时性、一次性信息（如本次会话的代码片段）→ 保留在内置记忆
• 需要多设备实时云同步的场景 → 本技能不提供云同步，需配合 Git 或云盘
• 需要极高安全级别的敏感凭证存储 → 永不存储 API Key、密码、凭证
• 单次会话内的快速上下文 → 内置 Agent 记忆已足够

操作步骤

Step 1：首次初始化

输入参数

mkdir -p ~/memory
cat > ~/memory/INDEX.md << 'EOF'
# 记忆索引
# ...
| 分类 | 描述 | 条目数 | 更新时间 |
|---:|---:|---:|---:|
EOF

Step 2：与用户确认分类结构

首次使用时询问用户需要存储什么，按需创建分类：

Step 3：写入记忆条目（立即写入，不等待不批量）

当用户分享重要信息时：

1. 执行写入前预检：grep 同分类去重、检查同主题冲突
2. 写入对应 ~/memory/{分类}/{条目}.md（含 frontmatter）
3. 更新该分类的 INDEX.md
4. 然后才响应用户

Step 4：检索记忆（优先走索引）

1. 查根索引 INDEX.md → 找到目标分类
2. 查分类 INDEX.md → 找到目标条目
3. 读取条目文件详情
4. 索引找不到再用 grep 全文搜索

Step 5：周期性维护

• 每周（5 分钟）：更新 INDEX.md、归档已完成/不活跃条目
• 每月（15 分钟）：审查分类规模（> 100 条目自动分裂子分类）、清理过期条目、检查冲突版本

响应解析: 完成完成后,查看输出响应确认任务状态。成功时输出包含解析摘要和响应数据;失败时根据错误信息排查问题,查阅错误解析章节获取恢复步骤.

项目概要

技术栈：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` 并更新索引。"

### 示例 2：检索记忆并处理冲突（输入→输出）

**输入**：新会话中用户说"我之前偏好深色模式，现在改成浅色模式了"

**输出**（代理执行流程）：

```text
1. 检索：cat ~/memory/INDEX.md → 找到 preferences 分类
2. cat ~/memory/preferences/INDEX.md → 找到 ui-preferences.md
3. 读取发现旧记录："用户偏好深色模式（2026-06）"
4. 冲突检测：新信息与旧记录矛盾
5. 不直接覆盖，递增版本：
# ...
   ---
   title: UI 偏好
   version: 2
   ---
# ...
   ## 版本历史
   - v1 (2026-06-01)：用户偏好深色模式
   - v2 (2026-07-18)：用户偏好浅色模式（冲突，已确认最新）

代理响应："检测到与旧记忆冲突（旧：深色模式，新：浅色模式），已保留两版本，当前版本号 v2。"

错误处理指引

• 边界输入处理: 空输入返回提示信息, 超长输入自动截断
• 降级策略: 异常时返回默认值, 确保流程不中断
• 执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令机制: 失败时自动执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令, 最多3次

前置条件

运行环境：Windows / macOS / Linux；支持 SKILL.md 的任意 AI Agent（ Code / Cursor / Codex / CLI 等）. API Key：核心功能无需任何 API Key；语义检索增强如用云向量服务，需对应服务 Key. 可用性分类：MD+EXEC（Markdown 指令驱动，需 exec 执行文件操作命令）.

疑问汇总

Q1：这会和我 Agent 自带的记忆冲突吗？ A：不会。本系统完全并行，位于 ~/memory/，永不修改内置 MEMORY.md 与 workspace memory/。内置记忆负责当前会话快速上下文，本系统负责长期深度与规模，两者协同. Q2：记忆文件越来越多会不会很慢？ A：三层索引体系确保即使 500+ 文件也能快速定位。单分类 INDEX.md 超过 100 条目会自动分裂为子分类。超大规模建议接入向量检索（见依赖说明的可选项）. Q3：能不能多设备同步？ A：本技能不提供云同步。可通过 Git 或云盘同步 ~/memory/ 目录实现多设备。注意 .trash/ 与 .vectors/ 可加入 .gitignore. Q4：冲突版本太多怎么办？ A：定期审查冲突条目，与用户确认后合并或删除旧版本。建议每月维护时处理。每个冲突都保留版本历史，不会丢失信息. Q5：遗忘的数据能恢复吗？ A：遗忘阶段移到 ~/memory/.trash/，保留 30 天后彻底删除。30 天内可恢复。如需更长的保留期，可在 config.md 中调整 trash_retention_days.

限制条件

1. 不提供云同步：所有数据在本地 ~/memory/，无网络请求。多设备同步需用户自行通过 Git 或云盘实现，本技能不处理同步冲突.
2. 不存储敏感凭证：永不存储 API Key、密码、证书、敏感个人信息。这类数据应使用专门的密钥管理工具.
3. 语义检索为可选增强：默认零依赖，仅用 grep + 索引。超大规模（500+ 文件）场景下关键词检索召回率有限，需用户主动接入向量数据库.
4. 依赖用户主动维护：归档、分裂、冲突合并等生命周期管理需要用户在周/月回顾中确认，完全自动化的决策可能误判.
5. 不访问内置记忆（除单向同步）：仅在用户明确要求同步时读取内置记忆，反向永不修改。这意味着内置记忆中的临时上下文不会自动进入本系统.

输出说明

处理结果以结构化格式返回, 包含状态码、消息和数据字段.

安全提示

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

效能分析

特色对比

用户常见咨询

Q1: 持久记忆引擎支持哪些输入格式？

A1: 解决跨会话遗忘、检索不准、记忆膨胀冲突的无限分层持久记忆引擎。面向 AI Agent 的无限分层持久记忆系统，直击跨会话遗忘、检索不准、记忆膨胀、新旧冲突四大痛。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

故障恢复

针对持久记忆引擎使用中可能遇到的常见问题,提供以下排查方案:

持久记忆引擎通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

高频问答

操作入门

1. 配置API密钥: 在环境变量中设置对应的API Key
2. 初始化连接: 使用提供的凭证建立API连接
3. 调用接口: 传入必要参数执行API调用
4. 准备文件: 确认文件路径正确且格式受支持
5. 执行处理: 调用对应的处理函数
6. 查看结果: 检查输出文件或返回数据
7. 检查环境: 确认运行时和依赖已安装
8. 执行命令: 使用正确的参数格式执行
9. 查看输出: 检查命令输出和退出码

前置条件

• 已安装所需运行环境(参考依赖说明)
• 已获取必要的API密钥或访问凭证(如适用)
• 输入数据已准备就绪

依赖说明

运行环境

• Agent 平台: 支持SKILL.md的任意AI Agent
• 操作系统: Windows / macOS / Linux

可用性分类

• 分类: MD（纯Markdown指令，通过自然语言驱动Agent完成操作）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent完成操作。