持久记忆引擎

SKILL.md

---
slug: persistent-memory-engine
name: persistent-memory-engine
version: "1.0.0"
displayName: 持久记忆引擎
summary: 解决跨会话遗忘、检索不准、记忆膨胀冲突的无限分层持久记忆引擎
license: MIT
description: |-
  持久记忆引擎是面向 AI Agent 的无限分层记忆系统，针对"跨会话信息遗忘、关键词检索不准、记忆膨胀导致性能下降、新旧记忆冲突"四大高频痛点而设计。它在 Agent 内置记忆之上构建并行、可扩展、可检索的结构化存储，让 Agent 真正具备长期记忆能力。

  核心能力：用户自定义分类的无限存储、三层索引体系（根索引→分类索引→条目）、混合检索（关键词+语义回退）、记忆生命周期管理（写入→激活→归档→遗忘）、冲突检测与合并、从内置记忆单向同步、按规模自动分裂子分类、写入前预检（去重+版本化）。

  适用场景：长周期项目上下文管理、客户/人脉关系网络、决策推理归档、领域知识库构建、收藏与清单管理、多项目并行记忆、个人助理长期记忆。

  差异化：相比仅提供"文件夹+grep"的简单记忆方案，本技能新增 (1) 三层索引体系，支持 500+ 文件规模的高效导航，无需全量扫描；(2) 混合检索策略，小规模用 grep、大规模走索引、超大规模建议语义回退；(3) 记忆生命周期管理，条目自动经历"写入→激活→归档→遗忘"四阶段，避免膨胀；(4) 冲突检测，同一主题新旧信息矛盾时主动提示并保留版本历史；(5) 写入前预检，去重 + 版本化，避免重复存储与信息覆盖。

  触发关键词：长期记忆、跨会话记忆、记忆管理、记忆检索、记忆归档、持久化存储、memory、long-term memory、persistent memory
tags:
- 记忆管理
- 持久化存储
- 知识库
- 上下文管理
tools:
- read
- exec
---

# 持久记忆引擎（Persistent Memory Engine）

面向 AI Agent 的**无限分层持久记忆系统**，在内置记忆之上构建并行、可扩展、可检索的结构化存储，解决跨会话遗忘与记忆膨胀问题。

## 设计动机：四大高频痛点

| 痛点 | 典型表现 | 本技能对策 |
|------|----------|------------|
| 跨会话遗忘 | 新会话不记得上次的关键决策、用户偏好 | 持久化到 `~/memory/`，会话启动时主动加载索引 |
| 检索不准 | grep 关键词漏召回、同义词找不到 | 混合检索：关键词 + 索引导航 + 语义回退建议 |
| 记忆膨胀 | 文件越多越慢、单分类 500+ 条目卡顿 | 生命周期管理（激活→归档→遗忘）+ 自动分裂子分类 |
| 新旧记忆冲突 | 用户改了偏好，旧记忆还在误导 | 冲突检测 + 版本化保留 + 矛盾提示 |

## 与内置记忆的关系

```text
内置 Agent 记忆              本技能（~/memory/）
┌─────────────────────┐     ┌─────────────────────────────┐
│ MEMORY.md           │     │ 无限分层存储                  │
│ memory/（每日日志）  │  +  │ 任意自定义结构                │
│ 基础回忆            │     │ 完整索引与检索                │
└─────────────────────┘     └─────────────────────────────┘
        ↓                            ↓
   快速上下文                  深度与规模
   （自动工作）                （无限扩展）
```

**并行而非替代**：内置记忆保持不变，本技能在其之上叠加深度存储。两者协同：内置负责当前会话快速上下文，本技能负责长期深度与规模。

## 快速开始（< 60 秒）

### 步骤 1：首次初始化

```bash
mkdir -p ~/memory
# 创建根索引
cat > ~/memory/INDEX.md << 'EOF'
# 记忆索引

| 分类 | 描述 | 条目数 | 更新时间 |
|------|------|--------|----------|
EOF
```

### 步骤 2：与用户确认分类结构

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

| 用户说... | 创建分类 |
|-----------|----------|
| "我有很多项目" | `~/memory/projects/` |
| "我认识很多人" | `~/memory/people/` |
| "我想记录决策" | `~/memory/decisions/` |
| "我在学某领域" | `~/memory/knowledge/{领域}/` |
| "我收藏某类东西" | `~/memory/collections/{类型}/` |

### 步骤 3：写入第一条记忆

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

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

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

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

## 架构：三层索引体系

```text
~/memory/
├── INDEX.md              # 根索引：列出所有分类
├── config.md             # 系统配置
│
├── [用户自定义分类]/
│   ├── INDEX.md          # 分类索引：列出该分类所有条目
│   ├── {条目1}.md        # 单个记忆条目
│   ├── {条目2}.md
│   └── [子分类]/         # 当条目 > 100 时自动分裂
│       ├── INDEX.md      # 子分类索引
│       └── ...
│
└── sync/                 # 可选：从内置记忆单向同步
    └── ...
```

### 三层索引导航流程

```text
查找信息时：
1. ~/memory/INDEX.md        → 找到目标分类
2. ~/memory/{分类}/INDEX.md  → 找到目标条目
3. ~/memory/{分类}/{条目}.md  → 读取详情

例：
~/memory/INDEX.md → "projects 分类有 30 个项目"
~/memory/projects/INDEX.md → "alpha 项目在 alpha.md"
~/memory/projects/alpha.md → 读取 alpha 项目详情
```

## 核心规则

### 规则 1：与内置记忆隔离

本系统位于 `~/memory/`，**永不修改**：
- Agent 的 `MEMORY.md`（工作区根目录）
- Agent 的 `memory/` 文件夹（如工作区中存在）

### 规则 2：用户定义结构

无预设结构，根据用户需求创建分类。常见分类：

| 分类 | 存储内容 | 典型条目数 |
|------|----------|------------|
| `projects/` | 详细项目上下文 | 10-50 |
| `people/` | 人脉网络与完整背景 | 50-200 |
| `decisions/` | 决策推理归档 | 20-100 |
| `knowledge/` | 领域专业知识 | 100-500 |
| `collections/` | 收藏与清单 | 不定 |

### 规则 3：每个分类必有索引

每个文件夹必须有 `INDEX.md`，格式：

```markdown
| 名称 | 状态 | 更新时间 | 文件 |
|------|------|----------|------|
| Alpha | Active | 2026-07 | alpha.md |
| Beta | Paused | 2026-06 | beta.md |

合计：2 个活跃，5 个归档
```

**索引规模约束**：单个 INDEX.md 不超过 100 条目。超出时自动分裂为子分类。

### 规则 4：立即写入

当用户分享重要信息时：
1. 写入对应 `~/memory/{分类}/{条目}.md`
2. 更新该分类的 `INDEX.md`
3. 然后才响应用户

**不等待、不批量**。立即写入避免信息丢失。

### 规则 5：检索优先走索引

```text
1. 先问："这在 ~/memory/ 还是内置记忆？"
2. 查索引：INDEX.md → 分类 INDEX.md → 条目文件
3. 索引找不到再 grep
```

```bash
# 小规模（< 50 文件）：直接 grep
grep -r "关键词" ~/memory/

# 大规模（50+ 文件）：走索引导航
cat ~/memory/INDEX.md
cat ~/memory/projects/INDEX.md
cat ~/memory/projects/alpha.md

# 超大规模（500+ 文件）：分层索引 + 语义回退
# 建议接入向量检索（见"高级配置"）
```

### 规则 6：从内置记忆单向同步（可选）

```text
~/memory/sync/
├── preferences.md    # 从内置记忆同步
└── decisions.md      # 从内置记忆同步
```

**同步方向**：内置 → 本系统，**反向永不修改**内置记忆。

## 记忆生命周期管理

每个条目经历四阶段：

```text
写入 → 激活 → 归档 → 遗忘
  │       │       │       │
  │       │       │       └─ 超过保留期且无引用，移到 trash/ 或删除
  │       │       └─ 超过 90 天未更新或标记完成，移到 archived/
  │       └─ 当前活跃使用中
  └─ 首次创建
```

### 条目 frontmatter 规范

```yaml
---
title: 条目标题
status: active | archived | forgotten  # 生命周期状态
created: 2026-07-18
updated: 2026-07-18
version: 1                              # 版本号，每次更新递增
importance: 0.8                         # 重要度 0-1
tags: [标签1, 标签2]
related: [其他条目ID]                   # 关联条目
expires_at: 2026-10-18                 # 可选：过期时间
---
```

### 自动归档规则

| 条件 | 动作 |
|------|------|
| 超过 90 天未更新且 status=active | 提示用户归档 |
| status=archived 超过 180 天无引用 | 提示遗忘 |
| 条目含 `expires_at` 且已过期 | 自动归档 |

## 冲突检测与版本化

当新信息与已有记忆矛盾时：

```text
检测：写入前扫描同分类同主题条目
  - 发现矛盾 → 不直接覆盖
  - 保留旧版本，新增版本号
  - 主动提示用户："检测到与旧记忆冲突，已保留两版本"

例：
  旧：用户偏好深色模式（2026-06）
  新：用户偏好浅色模式（2026-07）
  → alpha.md version 2 保留两版本，标注冲突
```

### 版本化存储格式

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

## 写入前预检

写入新条目前执行：

1. **去重检查**：grep 同分类是否已有相同/相似内容
2. **冲突检查**：同主题条目是否矛盾
3. **索引更新**：确保 INDEX.md 同步更新
4. **版本化**：如为更新已有条目，递增 version

## 规模扩展：自动分裂

当分类增长过大时：

```text
触发条件：INDEX.md > 100 条目

分裂策略：
~/memory/projects/
├── INDEX.md           # 改为"参见 active/ 和 archived/"
├── active/
│   ├── INDEX.md       # 30 个活跃项目
│   └── ...
└── archived/
    ├── INDEX.md       # 200 个归档项目
    └── ...
```

**分裂建议阈值**：
| 规模 | 检索方式 | 建议 |
|------|----------|------|
| < 50 文件 | grep 直接搜 | 无需分裂 |
| 50-500 文件 | 索引导航 | 按状态/时间分裂 |
| 500+ 文件 | 分层索引+语义 | 按多维度分裂，建议接入向量检索 |

## 存储分配指南：本系统 vs 内置记忆

| 存在本系统（~/memory/） | 保留在内置记忆 |
|------------------------|----------------|
| 详细项目历史 | 当前项目状态 |
| 完整人脉档案 | 关键联系人速查 |
| 全部决策推理 | 近期决策 |
| 领域知识库 | 快速事实 |
| 收藏与清单 | — |
| 任何会膨胀的内容 | 摘要 |

**原则**：内置记忆用于快速上下文，本系统用于深度与规模。

## 典型工作流（3 个真实场景）

### 场景一：长周期项目记忆

```text
用户："这个项目已经做了 3 个月，每次开新会话都要重新解释背景"

流程：
1. 首次：在 ~/memory/projects/{项目名}.md 创建条目
2. 每次关键决策：立即写入条目 + 更新版本号
3. 新会话启动：读取 INDEX.md → 项目条目 → 恢复上下文
4. 项目完成：status 改为 archived，移到 archived/
```

### 场景二：人脉网络管理

```text
用户："我认识很多人，记不清谁是谁"

流程：
1. 创建 ~/memory/people/ 分类
2. 每人一个 .md 文件，含：背景、关系、上次互动、共同话题
3. 每次交流后更新该人条目
4. 检索：INDEX.md 按姓名/公司/标签查找
```

### 场景三：决策推理归档

```text
用户："为什么我们当时选了方案 A 而不是方案 B？"

流程：
1. 每次重大决策：在 ~/memory/decisions/ 创建条目
2. 记录：决策内容、备选方案、推理过程、参与人、时间
3. 后续回溯：按时间或主题检索
4. 决策变更：新增版本，保留旧推理
```

## 维护计划

### 每周（5 分钟）
- 更新 INDEX.md（新增条目）
- 归档已完成/不活跃条目

### 每月（15 分钟）
- 审查分类规模，分裂过大分类
- 清理过期条目（移到 archived/ 或 forgotten/）
- 检查冲突版本，合并或确认

### 记忆变慢时
- 检查 INDEX.md 规模（保持 < 100 行）
- 分裂大分类为子分类
- 归档旧内容
- 考虑接入语义检索

## 高级配置：语义检索（可选）

当记忆规模超过 500 文件，关键词检索不够时：

```text
方案一：接入本地向量检索
  - 用 Transformers.js 生成 embedding
  - 存储到 ~/memory/.vectors/
  - 查询时先向量检索定位，再读文件

方案二：接入外部向量数据库
  - Chroma / LanceDB / Qdrant
  - 适合超大规模（1000+ 文件）
  - 需额外依赖与配置
```

> 本技能默认不依赖向量数据库，保持零依赖。语义检索为可选增强。

## 常见陷阱

| 陷阱 | 后果 | 规避 |
|------|------|------|
| 修改内置记忆 | 破坏 Agent 基础功能 | 永不触碰 MEMORY.md 与 workspace memory/ |
| 无索引 | 找东西要全量扫描 | 每个分类必有 INDEX.md |
| 单分类过大 | 检索变慢 | > 100 条目自动分裂 |
| 全量同步内置记忆 | 重复存储、浪费空间 | 只同步需要组织的部分 |
| 延迟写入 | 信息丢失 | 用户分享重要信息后立即写入 |
| 直接覆盖旧版本 | 丢失历史与冲突线索 | 版本化保留 |

## 安全与隐私

- 所有数据在本地 `~/memory/`，无外部服务
- 无网络请求
- **永不存储**：API Key、密码、凭证、敏感个人信息
- 不访问内置记忆（仅在同步时读取）

## FAQ

**Q1：这会和我 Agent 自带的记忆冲突吗？**
A：不会。本系统完全并行，位于 `~/memory/`，永不修改内置记忆。两者协同工作。

**Q2：记忆文件越来越多会不会很慢？**
A：三层索引体系确保即使 500+ 文件也能快速定位。超大规模建议接入语义检索（见高级配置）。

**Q3：能不能多设备同步？**
A：本技能不提供云同步。可通过 Git 或云盘同步 `~/memory/` 目录实现多设备。

**Q4：冲突版本太多怎么办？**
A：定期审查冲突条目，与用户确认后合并或删除旧版本。建议每月维护时处理。

**Q5：遗忘的数据能恢复吗？**
A：遗忘阶段移到 `~/memory/.trash/`，保留 30 天后彻底删除。30 天内可恢复。

## 故障排查

| 症状 | 可能原因 | 解决方案 |
|------|----------|----------|
| 找不到记忆 | 索引未更新 | 检查 INDEX.md，手动补条目 |
| 检索结果过多 | 分类过大 | 分裂子分类，缩小范围 |
| 同一信息重复 | 写入前未去重 | 执行去重检查，合并条目 |
| 版本冲突混乱 | 长期未维护 | 月度审查，合并冲突版本 |
| 记忆文件损坏 | 写入中断 | 从 .trash/ 或备份恢复 |

## 依赖说明

### 运行环境
- **Agent 平台**：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
- **操作系统**：Windows / macOS / Linux
- **存储**：用户主目录可写（`~/memory/`）

### 第三方依赖

| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| grep / find | 系统命令 | 必需 | 操作系统自带 |
| cat / mkdir / echo | 系统命令 | 必需 | 操作系统自带 |
| 向量数据库（可选） | 外部依赖 | 可选 | Chroma / LanceDB / Qdrant，超大规模时启用 |

### API Key 配置
- 本技能基于本地文件存储，**无需任何 API Key**
- 语义检索增强（可选）如用云向量服务，需对应服务 Key

### 可用性分类
- **分类**：MD+EXEC（Markdown 指令驱动，需 exec 执行文件操作命令）
- **说明**：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 管理本地记忆文件