Persistent Memory Engine

面向 AI Agent 的无限分层持久记忆系统，在内置记忆之上构建并行、可扩展、可检索的结构化本地存储。 直击跨会话遗忘、检索不准、记忆膨胀、新旧冲突四大痛点。核心能力涵盖无限分层结构化存储、 三层索引体系、混合检索策略、记忆生命周期管理、冲突检测与版本化、分类自动分裂、回收站恢复机制。 完全位于 ~/memory/，与内置 Agent 记忆并行运作，永不修改内置 MEMORY.md。 适用于长周期项目记忆、人脉网络管理、决策归档、领域知识库构建、多项目并行记忆等场景。

持久记忆引擎

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

核心能力

1. 无限分层结构化存储

用户自定义分类，无预设结构限制。每个条目以独立 Markdown 文件存储，支持 frontmatter 元数据：

yaml

---
title: Alpha项目
status: active
created: 2026-07-18
updated: 2026-07-18
version: 1
tags: [web, react]
importance: 0.8
related: [beta-project, tech-stack-decision]
expires: 2026-12-31
---

支持的元数据字段：title（标题）、status（状态：active/archived/expired）、created/updated（时间戳）、version（版本号）、tags（标签数组）、importance（重要度0-1）、related（关联条目ID数组）、expires（过期时间）。

常见分类：projects/（项目）、people/（人脉）、decisions/（决策）、knowledge/（知识库）、collections/（收藏）。

处理: 按照skill规范执行无限分层结构化存储操作,遵循单一意图原则。

2. 三层索引体系

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

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

500+ 文件规模也能 O(1) 定位，无需全量扫描。索引在每次写入条目时自动更新。

输入: 用户提供三层索引体系所需的指令和必要参数。 处理: 按照skill规范执行三层索引体系操作,遵循单一意图原则。 输出: 返回三层索引体系的执行结果,包含操作状态和输出数据。

3. 混合检索策略

按规模自动适配最优检索路径：

文件规模	检索策略	命令	延迟
小规模（<50文件）	grep 全文搜索	grep -r "关键词" ~/memory/{分类}/	<100ms
中规模（50-500文件）	索引导航优先	查 INDEX.md 定位 -> 读条目文件	<200ms
超大规模（500+文件）	向量语义检索（可选）	接入 Chroma/LanceDB/Qdrant	<500ms

小规模直接 grep，大规模走索引导航，超大规模建议接入向量数据库做语义回退。系统按当前分类文件数自动推荐最优策略。

• 执行混合检索策略操作，处理输入数据并返回结果
• 验证执行结果，确认输出符合预期格式
• 参考混合检索策略相关配置参数进行设置

4. 记忆生命周期管理

每个条目经历四阶段生命周期，避免记忆膨胀拖慢检索：

阶段	触发条件	状态变化	检索权重
写入	用户分享重要信息	status=active	最高
激活	被检索或更新	status=active（刷新时间戳）	高
归档	超过90天未更新	status=archived，移入 archived/ 子目录	降低
遗忘	归档超过180天无引用	移入 .trash/，保留30天	不参与检索

过期条目移入 ~/memory/.trash/ 保留30天可恢复，30天后彻底删除。trash_retention_days 参数可在 config.md 中调整。

处理: 按照skill规范执行记忆生命周期管理操作,遵循单一意图原则。 输出: 返回记忆生命周期管理的执行结果,包含操作状态和输出数据。

5. 冲突检测与版本化

写入前扫描同分类同主题条目，发现矛盾时不直接覆盖：

• 检测：grep 同分类下 title 或 tags 匹配的条目，对比内容关键字段
• 处理：保留旧版本，递增 version，新版本标记为当前版本
• 提示：主动告知用户"检测到冲突，已保留两版本，当前版本号 v2"
• 历史：版本历史记录在条目文件的"版本历史"章节

markdown

### 能力覆盖范围

本skill还覆盖以下能力场景: 无限分层持久记忆、解决跨会话遗忘、检索不准、记忆膨胀与冲突问、Agent、的无限分层持久记、忆系统、在内置记忆之上构、建并行、可扩展、可检索的结构化本、地存储、直击跨会话遗忘、新旧冲突四大痛点、核心能力涵盖无限、分类自动分裂、回收站恢复机制、完全位于、与内置、记忆并行运作、永不修改内置、适用于长周期项目、人脉网络管理、决策归档、领域知识库构建、多项目并行记忆等。这些能力在上述核心功能中均有对应处理逻辑。

**输出**: 返回冲突检测与版本化的执行结果,包含操作状态和输出数据。

## 版本历史
- v1 (2026-06-01)：用户偏好深色模式
- v2 (2026-07-18)：用户偏好浅色模式（冲突，已确认最新）

从内置记忆单向同步，反向永不修改内置记忆。

6. 分类自动分裂

单分类条目数超过阈值时提示分裂为子分类：

• 触发：单分类 INDEX.md 超过100条目
• 策略：按 status（active/archived）或时间（年/月）或标签分裂
• 操作：创建子分类目录，移动条目，更新索引
• 回滚：分裂后如不满意可合并回原分类

7. 回收站恢复机制

遗忘阶段的条目移入 ~/memory/.trash/，保留可恢复窗口：

• 保留期：默认30天，可通过 config.md 调整
• 恢复：mv ~/memory/.trash/{条目}.md ~/memory/{分类}/，status 改回 active
• 清理：超过保留期的条目在下次维护时彻底删除
• 审计：.trash/INDEX.md 记录所有遗忘条目的元数据

8. 写入前预检流程

每次写入记忆条目前执行完整预检，确保数据质量：

1. 去重检查：grep 同分类下是否有相同 title 或高度相似内容
2. 冲突检测：检查同主题条目是否存在矛盾
3. 索引同步：确认 INDEX.md 格式正确，准备追加条目记录
4. 原子写入：先写入条目文件，再更新索引，任一步骤失败则回滚

使用流程

第一步：首次初始化

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

第二步：写入记忆条目

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

第三步：检索记忆

优先走索引路径：查根索引 INDEX.md 找到目标分类 -> 查分类 INDEX.md 找到目标条目 -> 读取条目文件详情。索引找不到再用 grep 全文搜索作为回退。

第四步：处理冲突与版本

检测到新旧信息矛盾时，不直接覆盖旧条目。保留旧版本，递增 version 号，写入新版本，在版本历史章节记录变更。主动告知用户冲突情况，由用户确认哪条为权威版本。

第五步：周期性维护

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

命令参数说明

• -stack-decision: 命令参数,用于指定操作选项
• -preferences: 命令参数,用于指定操作选项

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

错误处理

错误类型	原因	处理方式
找不到记忆条目	索引未同步更新，条目已写入但 INDEX.md 未追加记录	检查 INDEX.md 是否含该条目行，手动补录条目记录到分类索引
检索结果噪音过大	单分类过大（超过100条目），grep 返回过多无关结果	按状态或时间分裂为子分类，缩小检索范围；或启用 tags 过滤
同一信息重复存储	写入前未执行去重检查，同一内容被多次写入	执行 grep 去重，合并重复条目，保留 version 最高的版本
版本冲突混乱	长期未做月度维护，冲突版本堆积	执行月度审查，与用户确认后合并或删除旧版本，保留权威版本
记忆文件损坏	写入过程中断或磁盘错误导致 Markdown 文件格式损坏	从 ~/memory/.trash/ 或 Git 备份恢复；无备份时从 frontmatter 重建条目骨架
误修改内置 MEMORY.md	违反隔离规则，写入了 Agent 内置记忆文件	立即从 Git 或备份恢复内置记忆文件，本系统只允许写入 ~/memory/ 目录
条目过期但仍被引用	自动归档误判活跃条目为过期	将条目 status 改回 active，从 archived/ 移回主目录，更新更新时间戳
超大规模检索变慢	500+ 文件未接入向量语义检索	启用可选的向量数据库（Chroma/LanceDB/Qdrant）做语义检索增强

示例

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

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

bash

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

## 项目概要
技术栈：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 并更新索引。"

示例二：检索记忆并处理冲突版本

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

text

1. 检索：cat ~/memory/INDEX.md -> 找到 preferences 分类
2. cat ~/memory/preferences/INDEX.md -> 找到 ui-preferences.md
3. 读取发现旧记录："用户偏好深色模式（2026-06-01）"
4. 冲突检测：新信息与旧记录矛盾
5. 不直接覆盖，递增版本：

   ---
   title: UI偏好
   status: active
   version: 2
   updated: 2026-07-18
   ---

   ## 当前偏好
   用户偏好浅色模式

   ## 版本历史
   - v1 (2026-06-01)：用户偏好深色模式
   - v2 (2026-07-18)：用户偏好浅色模式（冲突，已确认最新）

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

示例三：生命周期归档与回收站恢复

场景：维护时发现 projects/beta.md 超过90天未更新需归档，后用户要求恢复。

bash

# 归档操作（90天未更新）
mkdir -p ~/memory/projects/archived
mv ~/memory/projects/beta.md ~/memory/projects/archived/beta.md
# 更新条目 status
sed -i 's/status: active/status: archived/' ~/memory/projects/archived/beta.md
# 更新分类索引，将beta行标记为archived

# 180天后无引用，移入回收站
mkdir -p ~/memory/.trash
mv ~/memory/projects/archived/beta.md ~/memory/.trash/beta.md
echo "| beta项目 | expired | 2026-07-18 | projects/archived/beta.md |" >> ~/memory/.trash/INDEX.md

# 用户要求恢复（30天内）
mv ~/memory/.trash/beta.md ~/memory/projects/beta.md
sed -i 's/status: archived/status: active/' ~/memory/projects/beta.md
# 更新 updated 时间戳为当前日期

代理响应："beta项目已从回收站恢复，状态更新为 active。"

FAQ

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

不会。本系统完全并行，位于 ~/memory/，永不修改内置 MEMORY.md 与 workspace memory/。内置记忆负责当前会话快速上下文，本系统负责长期深度与规模，两者协同。仅在用户明确要求时从内置记忆单向同步到本系统，反向永不修改。

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

三层索引体系确保即使500+文件也能快速定位。单分类 INDEX.md 超过100条目会自动提示分裂为子分类。超大规模建议接入向量数据库（Chroma/LanceDB/Qdrant）做语义检索增强，系统按当前文件数自动推荐最优检索策略。

Q3: 冲突版本太多怎么办？

定期审查冲突条目，与用户确认后合并或删除旧版本。建议每月维护时处理。每个冲突都保留完整版本历史，不会丢失信息。冲突检测在写入前自动执行，发现矛盾时递增版本号而非覆盖，确保新旧信息并存。

Q4: 遗忘的数据能恢复吗？

可以。遗忘阶段移到 ~/memory/.trash/，保留30天后彻底删除。30天内可通过 mv 命令恢复，将 status 改回 active。如需更长的保留期，可在 ~/memory/config.md 中调整 trash_retention_days 参数。回收站索引 .trash/INDEX.md 记录所有遗忘条目的元数据。

Q5: 能不能多设备同步？

本技能不提供云同步。可通过 Git 或云盘同步 ~/memory/ 目录实现多设备。注意 .trash/ 与 .vectors/ 可加入 .gitignore 避免同步无用数据。同步冲突需用户手动解决，建议每台设备使用独立分支，定期合并。

Q6: 向量检索增强怎么启用？

向量检索为可选增强，默认零依赖，仅用 grep + 索引。超大规模（500+文件）场景下关键词检索召回率有限，需用户主动接入向量数据库。安装 Chroma（pip install chromadb）或 LanceDB（pip install lancedb），在 ~/memory/config.md 中配置 vector_provider 和 embedding_model，系统自动将新写入条目生成嵌入并索引。

依赖说明

运行环境

• 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 / sed	系统命令	必需	操作系统自带
向量数据库（Chroma/LanceDB/Qdrant）	外部依赖	可选	超大规模（500+文件）语义检索增强时启用
Transformers.js（本地 embedding）	运行时库	可选	语义检索增强时启用

API Key 配置

• 核心功能无需任何 API Key
• 语义检索增强如使用云向量服务，需对应服务 Key

可用性分类

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

已知限制

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