slug: elite-longterm-memory name: elite-longterm-memory version: "1.2.3" displayName: 长期记忆系统 summary: 六层记忆架构,从会话状态到云端备份,结合WAL协议与向量检索。 license: MIT description: |- 融合六种成熟方法的AI代理记忆架构:会话状态热内存、向量数据库 温存储、Git笔记冷存储、策展归档、云端备份与自动事实提取。通过 WAL协议保证持久性,覆盖记忆卫生、故障诊断与即时修复。适用于 独立开发者、企业团队和自动化工作流场景。 tools:

• read
• exec

长期记忆系统

融合六种成熟方法的AI代理记忆架构,从会话状态到云端备份,通过WAL协议保证持久性,永不丢失上下文、决策与教训。

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY="your_api_key_here"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。

核心能力

1. HOT RAM 会话状态

• SESSION-STATE.md 作为代理的"内存",在压缩、重启、分心中存活
• 包含当前任务、关键上下文、待办动作、近期决策四个区块
• 规则:在响应用户之前先写入,由用户输入触发而非代理记忆

处理: 按照skill规范执行HOT RAM 会话状态操作,遵循单一意图原则。 输出: 返回HOT RAM 会话状态的执行结果,包含操作状态和输出数据。

2. WARM STORE 向量检索

• 基于向量数据库的语义搜索,跨所有记忆自动召回相关上下文
• memory_recall query="project status" limit=5 召回相关记忆
• memory_store text="User prefers dark mode" category="preference" importance=0.9 存储记忆
• 配置 minScore: 0.3、maxResults: 10 控制召回质量与数量

3. COLD STORE 知识图谱

• 结构化决策、教训与上下文,分支感知
• python3 memory.py -p $DIR remember '{"type":"decision","content":"Use React for frontend"}' -t tech -i h 存储决策
• python3 memory.py -p $DIR get "frontend" 检索主题记忆
• 永久性决策记录,跨会话稳定

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

4. CURATED ARCHIVE 策展归档

• 人类可读长期记忆,日志+提炼智慧
• 结构:MEMORY.md(策展长期,小于5KB)+ memory/YYYY-MM-DD.md(每日日志)+ memory/topics/(主题文件)
• 每日日志记录当天活动,定期合并到 MEMORY.md

处理: 按照skill规范执行CURATED ARCHIVE 策展归档操作,遵循单一意图原则。 输出: 返回CURATED ARCHIVE 策展归档的执行结果,包含操作状态和输出数据。

5. CLOUD BACKUP 云端同步

• 跨设备同步,与知识库对话
• supermemory add "Important context" 添加上下文
• supermemory search "what did we decide about..." 搜索决策
• 可选层,依赖 API Key

输入: 用户提供CLOUD BACKUP 云端同步所需的指令和必要参数。 输出: 返回CLOUD BACKUP 云端同步的执行结果,包含操作状态和输出数据。

6. AUTO-EXTRACTION 事实提取

• 自动从对话中提取偏好、决策、事实
• 去重并更新已有记忆
• 相比原始历史减少80% token消耗
• 跨会话自动工作

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

7. WAL协议

写前日志:在响应之前写入状态,而非之后。

• 用户陈述偏好 → 写入 SESSION-STATE.md → 再响应
• 用户做决策 → 写入 → 再响应
• 用户给截止日期 → 写入 → 再响应
• 用户纠正你 → 写入 → 再响应
• 原因:若先响应再崩溃/压缩,上下文丢失;WAL保证持久性

处理: 按照skill规范执行WAL协议操作,遵循单一意图原则。 输出: 返回WAL协议的执行结果,包含操作状态和输出数据。

8. 记忆卫生

每周维护:

• 审查 SESSION-STATE.md,归档已完成任务
• 检查向量库垃圾:memory_recall query="*" limit=50
• 清除无关向量:memory_forget id=<id>
• 合并每日日志到 MEMORY.md

输入: 用户提供记忆卫生所需的指令和必要参数。 输出: 返回记忆卫生的执行结果,包含操作状态和输出数据。

9. 故障模式诊断

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

10. 即时修复检查表

• 忘记偏好 → 在 MEMORY.md 添加 ## Preferences 段
• 重复错误 → 每个错误记录到 memory/lessons.md
• 子代理缺上下文 → 在 spawn 任务提示中包含关键上下文
• 忘记近期工作 → 严格的每日文件纪律
• 记忆搜索不工作 → 检查 OPENAI_API_KEY 是否设置

输入: 用户提供即时修复检查表所需的指令和必要参数。 输出: 返回即时修复检查表的执行结果,包含操作状态和输出数据。

能力覆盖范围

本skill还覆盖以下能力场景: 六层记忆架构、从会话状态到云端、协议与向量检索、融合六种成熟方法、代理记忆架构、会话状态热内存、温存储、Git、笔记冷存储、云端备份与自动事、协议保证持久性、覆盖记忆卫生、故障诊断与即时修、适用于、独立开发者、企业团队和自动化、工作流场景。这些能力在上述核心功能中均有对应处理逻辑。

适用场景

不适用于:需要100%确定性的关键决策、无LLM环境的纯规则系统。

使用流程

1. 创建 SESSION-STATE.md 热内存文件
2. 在配置中启用向量检索(minScore: 0.3、maxResults: 10、autoRecall: true、minImportance: 0.7)
3. 初始化 Git 笔记冷存储
4. 验证 MEMORY.md 与 memory/ 目录结构
5. (可选)配置云端同步 API Key
6. 会话开始读取热内存,对话中遵循WAL协议,会话结束更新状态
7. 每周执行记忆卫生

命令参数说明

• -provider: 命令参数,用于指定操作选项
• -STATE: 命令参数,用于指定操作选项
• -lancedb: 命令参数,用于指定操作选项

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

命令参数说明

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

命令参数说明

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

命令参数说明

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

命令参数说明

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

命令参数说明

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

命令参数说明

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

命令参数说明

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

命令参数说明

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

示例

示例1:WAL协议执行

用户: "这个项目用 Tailwind,不用原生 CSS"

代理(内部):
1. 写入 SESSION-STATE.md: "Decision: Use Tailwind, not vanilla CSS"
2. 存入知识图谱: 关于CSS框架的决策
3. memory_store: "User prefers Tailwind over vanilla CSS" importance=0.9
4. 然后响应: "明白,用 Tailwind..."

示例2:配置片段

{
  "memorySearch": {
    "enabled": true,
    "provider": "llm-provider",
    "sources": ["memory"],
    "minScore": 0.3,
    "maxResults": 10
  },
  "plugins": {
    "entries": {
      "memory-lancedb": {
        "enabled": true,
        "config": {
          "autoCapture": false,
          "autoRecall": true,
          "captureCategories": ["preference", "decision", "fact"],
          "minImportance": 0.7
        }
      }
    }
  }
}

示例3:SESSION-STATE.md 结构

## Current Task
重构用户认证模块

## Key Context
- User preference: 优先函数式风格
- Decision made: 用 JWT 不用 session
- Blocker: 等待设计团队确认登录页

## Pending Actions
- [ ] 完成token刷新逻辑
- [ ] 编写认证中间件测试

## Recent Decisions
2026-07-21: 采用 JWT 无状态认证

错误处理

常见问题

Q1: WAL协议为何要在响应前写入?

A: 若先响应再崩溃或压缩,上下文丢失。WAL(写前日志)保证持久性:用户陈述偏好/决策/截止日期/纠正时,先写入 SESSION-STATE.md 再响应,即使中途断电也能恢复。

Q2: 向量检索的 minScore: 0.3 与 maxResults: 10 如何调优?

A: minScore 过低会注入无关记忆,过高会漏掉相关项;0.3 是平衡起点。maxResults 控制上下文窗口占用,10 条通常够用。若召回噪声多,提高 minScore 到 0.5;若漏召回,降到 0.2。

Q3: minImportance: 0.7 意味着什么?

A: 重要性低于 0.7 的记忆不会被自动捕获。偏好与决策设为 0.9,普通事实设为 0.7,临时信息不存储。这避免向量库被低价值记忆污染。

Q4: MEMORY.md 为何要小于 5KB?

A: MEMORY.md 是策展的长期摘要,每次会话开始都会读取。过大消耗上下文窗口且稀释关键信息。详细内容拆分到 memory/topics/ 主题文件,MEMORY.md 只放索引与最重要的决策。

Q5: 事实提取工具如何减少80% token?

A: 原始对话历史包含大量寒暄与重复,事实提取工具自动抽取偏好、决策、事实等结构化条目,去重并更新。后续会话只注入提取后的精炼记忆,而非完整历史,token 消耗大幅下降。

Q6: 子代理如何继承记忆上下文?

A: 子代理默认不读取父代理的记忆文件。在 spawn 任务提示中显式包含关键上下文(当前任务、相关决策、用户偏好),或让子代理调用 memory_recall 自行检索。

已知限制

• 需要 LLM 支持语义检索,无 API Key 环境仅能用文件记忆
• 向量数据库需要磁盘空间存储向量索引
• 云端同步依赖外部服务可用性
• 记忆质量依赖写入纪律,WAL协议需严格执行
• 不适用于需要100%确定性的关键决策场景