本地长记忆

本地长记忆（LocalMemo Pro）

零 API、零云端、零数据出域的本地向量记忆系统。基于 Ollama + LanceDB，在本地完成 embedding 生成与语义检索，适合隐私敏感、离线、成本敏感场景。

痛点与对策速查

本地 vs 云端对比

结论：个人/小团队/隐私场景用本地；追求极致质量且不敏感数据用云端。

架构

┌───────────────────────────────────────────────────────────────┐
│                   LOCALMEMO PRO 本地架构                        │
├───────────────────────────────────────────────────────────────┤
│                                                                │
│  L1 热内存     SESSION-STATE.md    活跃任务上下文（抗压缩）     │
│      ↓                                                         │
│  L2 温向量     LanceDB            本地向量检索（embedding缓存）│
│      ↓         ↑ embedding 由 Ollama 本地生成                  │
│  L3 冷存储     Git-Notes          结构化决策（永久）           │
│      ↓                                                         │
│  L4 精选归档   MEMORY.md + daily/ 人类可读长期记忆             │
│                                                                │
│  全程零外部 API · 零数据出域 · 离线可用                        │
└───────────────────────────────────────────────────────────────┘

快速开始（3 步）

第 1 步：安装本地 embedding 引擎

# 安装 Ollama
# macOS/Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows: 从 https://ollama.com/download 下载安装包

# 拉取 embedding 模型（约 274MB）
ollama pull nomic-embed-text

# 验证
ollama --version

第 2 步：初始化记忆系统

cd skills/localmemo-pro
npm install
node bin/init.js

初始化创建：

• SESSION-STATE.md — 热内存
• MEMORY.md — 长期记忆
• memory/ — 每日日志目录
• memory/vectors/ — LanceDB 向量数据库
• memory/cache/ — embedding 缓存目录

第 3 步：使用记忆工具

# 存储
node bin/memory.js store "用户喜欢深色模式" --importance 0.9 --category preference

# 搜索
node bin/memory.js search "用户界面偏好"

# 统计
node bin/memory.js stats

# 遗忘
node bin/memory.js forget --query "深色模式"

Embedding 缓存机制（差异化核心）

相同文本反复生成 embedding 是本地系统的主要性能瓶颈。本系统实现 embedding 缓存：

文本 → SHA256(文本) → 查缓存目录
                          ├─ 命中 → 直接返回向量（<1ms）
                          └─ 未命中 → Ollama 生成 → 写入缓存（10-50ms）

缓存配置

{
  "embeddingCache": {
    "enabled": true,
    "path": "./memory/cache",
    "maxSizeMb": 500,
    "ttlDays": 90,
    "compression": true
  }
}

缓存达到上限时自动 LRU 淘汰最久未用的 embedding。

模型选择指南

推荐：默认用 nomic-embed-text（质量/速度/大小均衡）。资源紧张用 all-MiniLM-L6，质量优先用 bge-m3。

WAL 写前日志协议

原则：先写状态，再回复用户。 保证崩溃/压缩时不丢上下文。

资源占用控制（差异化核心）

本地系统最大风险：向量库无限增长导致内存/CPU/磁盘膨胀。

三级资源控制

维护命令

# 查看资源占用
node bin/memory.js stats --detailed

# 压缩向量库
node bin/memory.js compact

# 清理旧记忆
node bin/memory.js cleanup --before 30d

# 去重
node bin/memory.js dedup

# 导出备份
node bin/memory.js backup ./backups/memory-$(date +%Y%m%d).zip

# 清理 embedding 缓存
node bin/memory.js cache-clean --older-than 30d

Agent 配置集成

在 Agent 配置文件中启用本地记忆插件：

{
  "plugins": {
    "entries": {
      "localmemo-pro": {
        "enabled": true,
        "config": {
          "ollamaUrl": "http://localhost:11434",
          "embeddingModel": "nomic-embed-text",
          "dbPath": "./memory/vectors",
          "cachePath": "./memory/cache",
          "autoRecall": true,
          "autoCapture": false,
          "maxMemoryMb": 500,
          "minImportance": 0.5
        }
      }
    }
  }
}

启用后自动提供工具：

• memory_recall — 搜索相关记忆
• memory_store — 存储重要信息
• memory_forget — 删除记忆

代理行为指令

会话开始时

1. 读取 SESSION-STATE.md（热内存）
2. 执行 memory_recall 搜索相关历史
3. 检查 memory/YYYY-MM-DD.md 近期活动

对话进行中

会话结束时

1. 更新 SESSION-STATE.md 最终状态
2. 重要内容移至 MEMORY.md
3. 创建/更新 memory/YYYY-MM-DD.md

真实场景示例

场景 1：医疗隐私场景

用户："记录患者对青霉素过敏"
→ 本地 embedding 生成（数据不出域）
→ memory_store："患者青霉素过敏" importance=1.0 category=medical
→ 存储在本地 LanceDB，符合 HIPAA 合规

后续查询：
  memory_recall query="患者过敏史"
  → 本地检索，零数据外传

场景 2：离线开发场景

环境：飞机上无网络，本地开发

用户："上次我们怎么解决 CORS 问题的？"
→ memory_recall query="CORS 跨域解决"
→ 本地 Ollama 生成 query embedding（离线）
→ LanceDB 本地检索
→ 召回："CORS 用代理中间件解决，配置在 middleware/cors.js"
→ 无需网络即可回忆历史决策

场景 3：成本敏感场景

独立开发者，月 API 预算 $0

存储 1000 条记忆：
  云端方案：embedding 费用约 $0.5-1/月
  本地方案：$0（一次性模型下载 274MB）

检索 100 次/天：
  云端方案：embedding 费用约 $0.3/月
  本地方案：$0（embedding 缓存命中后 <1ms）

年度节省：约 $10-15

常见问题 FAQ

Q1：本地 embedding 质量够用吗？ A：nomic-embed-text 在 MTEB 基准上表现接近 text-embedding-3-small，对个人/小规模记忆库完全够用。如需更高质量可切换 bge-m3。

Q2：Ollama 占多少内存？ A：nomic-embed-text 运行时约 2-4GB 内存。资源紧张可用 all-MiniLM-L6（约 500MB）。

Q3：embedding 缓存会占多少磁盘？ A：每条记忆的 embedding 约 3KB（768 维 float32）。10000 条记忆约 30MB，缓存上限可配置（默认 500MB）。

Q4：能和云端方案混用吗？ A：可以。重要记忆用云端高质量 embedding，日常用本地。但需注意维度一致性，建议统一用一种。

Q5：向量库损坏怎么办？ A：定期 node bin/memory.js backup 备份。损坏后从备份恢复，或从 MEMORY.md + daily/ 重建（记忆内容仍在文件中）。

故障排查

文件结构

workspace/
├── SESSION-STATE.md          # 热内存
├── MEMORY.md                 # 精选长期记忆
├── memory/
│   ├── vectors/              # LanceDB 向量库
│   ├── cache/                # embedding 缓存
│   ├── 2026-07-18.md         # 每日日志
│   ├── lessons.md            # 教训记录
│   └── topics/               # 主题文件
├── bin/
│   ├── init.js               # 初始化脚本
│   └── memory.js             # 记忆管理 CLI
└── localmemo-config.json     # 配置文件

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• Node.js：16+（运行记忆管理脚本）
• 内存：建议 8GB+（Ollama 运行需 2-4GB）
• 磁盘：建议 2GB+ 可用空间

第三方依赖

API Key 配置

• 本 Skill 核心功能无需任何 API Key
• 完全本地运行，零外部 API 调用
• 如需可选的云端备份功能，另行配置对应服务 Key

可用性分类

• 分类：MD+EXEC（Markdown 指令 + exec 命令行执行）
• 说明：基于 Markdown 的 AI Skill 驱动 Agent 执行本地记忆管理。核心记忆协议纯 Markdown 可工作；向量检索、embedding 生成需 Ollama + LanceDB 环境。