---
slug: "persistent-memory-engine"
name: "persistent-memory-engine"
version: 1.0.1
displayName: "持久记忆引擎"
summary: "无限分层持久记忆系统，解决跨会话遗忘、检索不准、记忆膨胀与冲突问题。面向 AI Agent 的无限分层持久记忆系统，在内置记忆之上构建并行、可扩展、可检索的结构化本地存储. 直击跨会话遗忘、"
summary_zh: "无限分层持久记忆系统，解决跨会话遗忘、检索不准、记忆膨胀与冲突问题。面向 AI Agent 的无限分层持久记忆系统，在内置记忆之上构建并行、可扩展、可检索的结构化本地存储. 直击跨会话遗忘、"
license: "MIT"
description: |-
  面向 AI Agent 的无限分层持久记忆系统，在内置记忆之上构建并行、可扩展、可检索的结构化本地存储.
  直击跨会话遗忘、检索不准、记忆膨胀、新旧冲突四大痛点。核心能力涵盖无限分层结构化存储、
  三层索引体系、混合检索策略、记忆生命周期管理、冲突检测与版本化、分类自动分裂、回收站恢复机制.
  完全位于 ~/memory/，与内置 Agent 记忆并行运作，永不修改内置 MEMORY.md.
  适用于长周期项目记忆、人脉网络管理、决策归档、领域知识库构建、多项目并行记忆等场景.
tools:
  - read
  - exec
  - write
homepage: ""
tags:
  - 智能助手
  - 记忆管理
  - 上下文
  - AI
  - memory
  - index
  - 条目
  - status
  - 分类
category: "Agents"
---
# 持久记忆引擎

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

| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| input | string | 是 | 持久记忆引擎处理的输入数据或指令 |
| options | object | 否 | 附加配置选项,如模式选择、格式偏好等 |
| callback_url | string | 否 | 异步处理完成后的回调通知URL |

## 付费版专享能力

| 能力 | 免费版 | 付费版 |
|:-----|:-----|:-----|
| 基础功能 | 支持 | 支持 |
| 多租户管理与权限分配 | 不支持 | 支持 |
| 操作审计与合规日志 | 不支持 | 支持 |
| 自定义仪表盘与报表 | 不支持 | 支持 |
| API开放与第三方集成 | 不支持 | 支持 |
| 资源配额管理与计费统计 | 不支持 | 支持 |

## 核心能力

### 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/`（收藏）.
**处理**: 解析无限分层结构化存储的输入参数,执行核心处理逻辑,返回结构化结果和执行状态.
### 2. 三层索引体系
根索引 -> 分类索引 -> 条目文件，三层导航确保大规模快速定位：

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

500+ 文件规模也能 O(1) 定位，无需全量扫描。索引在每次写入条目时自动更新.
**输入**: 用户提供三层索引体系所需的指令和必要参数.
**处理**: 解析三层索引体系的输入参数,执行核心处理逻辑,返回结构化结果和执行状态.
**输出**: 返回三层索引体系的处理结果,包含执行状态码、结果数据和执行日志.
### 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 中调整.
**处理**: 解析记忆生命周期管理的输入参数,执行核心处理逻辑,返回结构化结果和执行状态.
**输出**: 返回记忆生命周期管理的处理结果,包含执行状态码、结果数据和执行日志.
### 5. 冲突检测与版本化
写入前扫描同分类同主题条目，发现矛盾时不直接覆盖：

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

```markdown
# ...
#
## 快速开始

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

> 详细的输入输出格式请参考下方章节说明。

## 版本历史
- 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条目自动分裂子分类）、清理过期条目、检查冲突版本.
#
## 错误处理

| 错误类型 | 原因 | 处理方式 |
|---:|:---|---:|
| 找不到记忆条目 | 索引未同步更新，条目已写入但 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
   ---
# ...
   ## 当前偏好
   用户偏好浅色模式
# ...
## 版本历史(续1)
   - 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. **不访问内置记忆（除单向同步）**：仅在用户明确要求同步时读取内置记忆，反向永不修改。这意味着内置记忆中的临时上下文不会自动进入本系统.
## 输出格式

```json
{
  "success": true,
  "data": {
    "result": "持久记忆引擎处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "persistent-memory-engine"
    }
  },
  "execution_log": [
    "解析输入参数",
    "执行核心处理",
    "格式化输出结果"
  ],
  "error": null
}
```