本地记忆配置

使用本地 Embedding 模型实现记忆检索，无需云端 API，数据完全本地化。

🎯 优势

特性	本地方案	云端方案
延迟	<100ms	500-2000ms
成本	零	$0.0001/次
隐私	✅ 数据不出境	❌ 需上传
可用性	✅ 离线可用	⚠️ 依赖网络

---

📦 推荐模型

推荐模型: embeddinggemma-300m-qat-q8_0 (300M 参数，Q8 量化)

文件大小: ~320MB
内存占用: ~350MB
推理速度: ~50ms/查询

---

🔧 安装步骤

1. 安装 node-llama-cpp

npm install -g node-llama-cpp --build-from-source

预计时间: 2-5 分钟（需编译）

2. 验证安装

npm list -g node-llama-cpp
# 应显示：[email protected]

3. 测试记忆检索

cd ~/.openclaw/workspace
openclaw -c "memory_search query='Gateway 故障'"

预期输出：

{
  "results": [
    {
      "path": "MEMORY.md",
      "startLine": 79,
      "endLine": 87,
      "score": 0.39,
      "snippet": "Gateway 瞬断自愈..."
    }
  ],
  "provider": "local",
  "model": "hf:ggml-org/embeddinggemma-300m-qat-q8_0"
}

---

⚙️ 配置位置

OpenClaw 配置 (~/.openclaw/openclaw.json)

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "local",
        "fallback": "none"
      }
    }
  }
}

模型文件位置

~/.cache/node-llama-cpp/
└── hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf  (320MB)

---

🔍 故障排查

问题 1: memory_search 返回 disabled

错误信息：

Local embeddings unavailable.
Reason: node-llama-cpp is missing

解决方案：

# 重新安装
npm install -g node-llama-cpp --build-from-source

# 验证
node -e "require('node-llama-cpp'); console.log('OK')"

问题 2: 检索结果为空

可能原因：

1. 记忆文件不存在
2. 向量索引未建立

解决方案：

# 检查记忆文件
ls -la ~/.openclaw/workspace/memory/*.md

# 重建索引
cd ~/.openclaw/workspace
openclaw -c "memory_search query='test'"  # 自动触发索引

问题 3: 检索速度慢

优化建议：

# 检查系统负载
uptime

# 减少检索结果数量
openclaw -c "memory_search query='test' maxResults=3"

# 清理旧记忆文件
/root/.openclaw/workspace/scripts/evolver-cleanup.sh 30

---

📊 性能对比

模型	大小	速度	准确率
embeddinggemma-300m	320MB	50ms	85%
nomic-embed-text	274MB	40ms	88%
text-embedding-3-small (云端)	-	500ms	90%

---

🔄 切换模型（可选）

如果想使用 nomic-embed-text（已存在于 Ollama）：

1. 修改配置

openclaw config set agents.defaults.memorySearch.provider ollama
openclaw config set agents.defaults.memorySearch.model nomic-embed-text

2. 验证 Ollama 运行

systemctl status ollama
curl http://localhost:11434/api/tags

3. 测试检索

openclaw -c "memory_search query='test'"

---

📝 最佳实践

1. 定期测试记忆健康

# 添加到心跳检查
# HEARTBEAT.md 中添加：
- [ ] 测试 memory_search 是否返回结果

2. 避免频繁修改配置

openclaw.json 设为只读：

chmod 444 ~/.openclaw/openclaw.json

3. 监控磁盘使用

# 每月检查一次
du -sh ~/.openclaw/workspace/memory/

健康阈值: <10MB（活跃文件）

---

📚 相关文档

• 自我改进系统概览
• Evolver 使用指南
• 最佳实践

---

提示: 本地模型足够日常使用，无需追求云端高精度。稳定性 > 准确率。