---
slug: "persistent-memory-engine-free"
name: "persistent-memory-engine-free"
version: "1.0.0"
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
  - grep
  - agent
  - alpha
category: "Agents"
---
# 持久记忆引擎（基础版）

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

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

## 核心能力

### 1. 分层结构化存储
用户自定义分类，每个条目以独立 Markdown 文件存储，支持 frontmatter 元数据：

```yaml
---
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

#
## 快速开始

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

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

## 使用流程

### 第一步：首次初始化

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

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

优先走索引路径：查根索引 `INDEX.md` 找到目标分类 -> 查分类 `INDEX.md` 找到目标条目 -> 读取条目文件详情。索引找不到再用 grep 全文搜索作为回退.
**结果验证**: 任务完成后,查看输出确认状态。成功时返回摘要和数据;失败时根据错误信息排查,参考恢复章节获取修复步骤.
## 错误处理

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

## 示例

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

场景：用户说"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
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个完整实战案例.
## 输出格式

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