简易本地记忆系统 🧠

面向 AI 智能体的零依赖记忆系统。

无需 API 密钥，无需外部服务，无需云依赖——仅靠智能搜索支持的纯本地存储。

架构

┌─────────────────────────────────────────────────┐
│          SIMPLE LOCAL MEMORY                    │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌─────────────┐  ┌─────────────┐             │
│  │   HOT RAM   │  │  COLD STORE │             │
│  │             │  │             │             │
│  │ SESSION-    │  │  Indexed    │             │
│  │ STATE.json  │  │  Memories   │             │
│  │             │  │  (JSON +    │             │
│  │ (active     │  │   Search)   │             │
│  │  context)   │  │             │             │
│  └─────────────┘  └─────────────┘             │
│         │                │                     │
│         └────────────────┼─────────────────┘   │
│                          ▼                      │
│                  ┌─────────────┐                │
│                  │ MEMORY.md   │ ← 人类可读     │
│                  │ + daily/    │                │
│                  └─────────────┘                │
│                                                 │
└─────────────────────────────────────────────────┘

三层记忆结构

第 1 层：HOT RAM（SESSION-STATE.json）

快速、活跃的工作记忆

{
  "current_task": "...",
  "key_context": ["...", "..."],
  "pending_actions": ["...", "..."],
  "recent_decisions": ["..."],
  "last_updated": "2026-03-15T10:30:00Z"
}

优势：

• 快速 JSON 读写
• 可抵御压缩操作（compaction）影响
• 易于程序化解析

第 2 层：COLD STORE（索引化记忆）

持久化、可搜索的记忆

# 存储一条记忆
memory-store --type preference --content "User prefers dark mode" --importance 0.9

# 搜索记忆
memory-search "what did user say about CSS"

# 列出最近的记忆
memory-list --limit 10

存储位置：memories/ 目录下的索引化 JSON 文件

第 3 层：人工整理归档（MEMORY.md + daily/）

人类可读的长期记忆

workspace/
├── MEMORY.md              # 人工整理的关键洞见
├── SESSION-STATE.json     # 当前活跃上下文
└── memories/
    ├── 2026-03-15.json    # 当日记忆快照
    ├── preferences.json   # 用户偏好
    ├── decisions.json     # 关键决策
    └── lessons.json       # 经验教训

快速开始

步骤 1：初始化

npm install -g simple-local-memory
cd your-project
memory-init

该命令将创建以下文件与目录：

• SESSION-STATE.json —— 活跃工作记忆
• MEMORY.md —— 长期人工整理记忆
• memories/ —— 记忆存储目录

步骤 2：在您的 AI 智能体中使用

适用于 Claude Code：

# 添加至自定义指令中

当我向您提供重要信息时：
1. 首先写入 SESSION-STATE.json
2. 然后使用 memory-store 存储
3. 最后回复我

每次开启对话时：
1. 先读取 SESSION-STATE.json
2. 使用 memory-search 检索相关记忆
3. 查阅 MEMORY.md 获取背景上下文

适用于 ChatGPT / Cursor：
在系统提示（system prompt）中添加：

You have access to local memory tools:
- memory-store: Save important information
- memory-search: Find relevant past context
- Read SESSION-STATE.json before responding
- Update SESSION-STATE.json when user shares preferences

记忆 CLI 命令

# 初始化记忆系统
memory-init

# 存储一条记忆
memory-store --type preference --content "User loves TypeScript" --importance 0.9

# 搜索记忆
memory-search "TypeScript preferences"

# 列出最近的记忆
memory-list --limit 10 --type preference

# 显示记忆统计信息
memory-stats

# 导出记忆
memory-export --format json --output backup.json

# 导入记忆
memory-import --file backup.json

WAL 协议（Write-Ahead Logging，预写式日志）

关键原则：务必先写入记忆，再响应用户

为何如此？ 若响应过程中发生崩溃而尚未保存，上下文将永久丢失。

记忆存储格式

memories/YYYY-MM-DD.json

{
  "date": "2026-03-15",
  "memories": [
    {
      "id": "uuid",
      "type": "preference|decision|fact|lesson",
      "content": "User prefers dark mode",
      "importance": 0.9,
      "tags": ["ui", "preferences"],
      "timestamp": "2026-03-15T10:30:00Z",
      "context": "Discussed during UI setup"
    }
  ]
}

memories/preferences.json

{
  "preferences": [
    {
      "key": "css_framework",
      "value": "Tailwind",
      "set_at": "2026-03-15T10:30:00Z",
      "reason": "User prefers over vanilla CSS"
    }
  ]
}

memories/decisions.json

{
  "decisions": [
    {
      "id": "uuid",
      "title": "Use React for frontend",
      "reason": "User requested component-based architecture",
      "made_at": "2026-03-15T10:30:00Z",
      "status": "active"
    }
  ]
}

搜索算法

基于 TF-IDF 的本地搜索：

1. 对查询语句和记忆内容进行分词（tokenize）
2. 计算词频（term frequency）
3. 按相关性 + 重要性 + 新近度综合排序
4. 返回 Top N 结果

// 示例搜索逻辑
function searchMemories(query, limit = 5) {
  const queryTokens = tokenize(query);
  const allMemories = loadAllMemories();

  const scored = allMemories.map(memory => {
    const score = calculateTFIDF(queryTokens, memory.content);
    const recencyBoost = calculateRecencyBoost(memory.timestamp);
    const importanceBoost = memory.importance || 0.5;

    return {
      ...memory,
      totalScore: score + recencyBoost + importanceBoost
    };
  });

  return scored
    .sort((a, b) => b.totalScore - a.totalScore)
    .slice(0, limit);
}

示例工作流

User: "Let's use Tailwind for this project, not vanilla CSS"

Agent process:
1. 更新 SESSION-STATE.json 中的决策字段
2. 执行：memory-store --type decision --content "Use Tailwind, not vanilla CSS" --importance 0.9
3. 执行：memory-store --type preference --content "User prefers Tailwind over vanilla CSS" --importance 0.95
4. 然后回复："Got it — Tailwind it is. I've saved this preference."

记忆类型分类

维护策略

每日维护

# 检查记忆健康状态
memory-stats

# 查看当日记忆
memory-list --date today

每周维护

# 归档旧记忆
memory-archive --days 7

# 清理重复项
memory-deduplicate

# 更新 MEMORY.md 中的洞见
# （手动：浏览 memories/ 并将关键内容补充进 MEMORY.md）

每月维护

# 导出月度备份
memory-export --format json --output monthly-backup.json

# 清理过期的每日记忆文件
memory-cleanup --days 30

记忆卫生最佳实践

1. 表述具体明确 —— “User likes dark mode” 优于 “User has preference”
2. 附带上下文 —— 说明该决策/偏好产生的原因
3. 合理设置重要性 —— 并非所有记忆都应设为 1.0
4. 正确打标签 —— 提升后续检索效率
5. 定期归档 —— 控制 SESSION-STATE.json 文件体积

故障排查

搜索无结果：
→ 检查 memories/ 目录是否存在
→ 验证 JSON 文件语法是否有效
→ 尝试更宽泛的搜索关键词

SESSION-STATE.json 过大：
→ 将历史条目迁移至 memory-store
→ 对已完成任务执行归档
→ 仅保留当前活跃上下文

记忆未成功保存：
→ 检查文件写入权限
→ 验证磁盘空间是否充足
→ 检查 JSON 格式是否合法

高级功能

记忆关联关系

{
  "id": "uuid",
  "content": "Use React for frontend",
  "related_to": ["uuid-of-other-memory"],
  "followed_by": ["uuid-of-decision"]
}

置信度评分

{
  "confidence": 0.95,
  "source": "explicit_user_statement",
  "verified_count": 3
}

过期时间

{
  "expires_at": "2026-04-15T00:00:00Z",
  "auto_archive": true
}

与 elite-longterm-memory 的对比

从 elite-longterm-memory 迁移

# 从 elite 系统导出
memory-export > elite-backup.json

# 转换格式
node convert-elite-to-simple.js elite-backup.json > simple-backup.json

# 导入至 simple 系统
memory-import --file simple-backup.json

未来增强方向（可选）

• 集成本地嵌入模型（如 Transformers.js）
• 为旧记忆增加压缩支持
• 为敏感数据增加加密支持
• 通过 GitHub Gist 实现同步
• 开发 Web UI 用于记忆管理

无需 API 密钥，无需云服务，无需追踪 —— 纯粹的本地记忆。

适用于：

• 注重隐私的用户
• 离线开发环境
• 学习记忆系统原理
• 构建定制化 AI 智能体
• 有严格数据合规要求的项目