Smart Memory System

基于检索增强技术，实现语义搜索、记忆优化与对话增强，显著降低 token 消耗并提升检索准确率。

Security Scan

The skill's description and docs claim a full RAG memory system, but the package is internally inconsistent (missing script implementations, mismatched model dims, and undocumented credential requirements), so it appears incomplete or sloppy and should be inspected before use.

Purpose & Capability

The SKILL.md and config claim integration with Edgefn (BAAI/bge-m3 and bge-reranker) and many runtime commands, but the repository does not include most referenced script files (e.g., loader, searcher, enhancer, retriever, integrator, monitor, optimizer, backup, restore, cleaner). package.json and SKILL.md advertise many commands/features that cannot run because those implementations are missing. Additionally, model vector dimensionality is inconsistent across files: SKILL.md and config mention 1024 dimensions while init.js (initial index) and CHANGELOG.md reference 384 — a clear mismatch.

Instruction Scope

SKILL.md instructs altering OpenClaw configuration (adding Edgefn model provider and context compression settings) and copying the skill into ~/.openclaw/skills/. The init script writes config and initial index into ~/.openclaw/workspace, but there is no code that actually modifies OpenClaw's central config or 'auto-applies' the advertised global settings. The docs also ask the user to provide an Edgefn API key, but the skill metadata declares no required environment variables — a gap between instructions and declared runtime requirements.

Install Mechanism

There is no formal install spec in the registry entry (instruction-only), but the package contains code and package.json lists clawhub install_hook and uninstall_hook pointing to scripts/install.js and scripts/uninstall.js which are not present. That means automated install hooks are referenced but missing. The installation instructions in SKILL.md rely on cloning or clawhub; with missing scripts and hooks the install may be incomplete or fail.

Credentials

SKILL.md explicitly requires an 'Edgefn API 密钥' for the embedding and reranker models, but the skill metadata declares no required environment variables or primary credential. Requesting an API key for a model provider is expected for this functionality, but the omission from metadata is a discrepancy that can hide the need to supply sensitive credentials. Also the skill references networked model providers (edgefn, qwen-portal) in config, which justifies credential needs but those needs are not declared formally.

Persistence & Privilege

The skill does not request 'always: true' and uses normal user-level paths under the user's home (~/.openclaw/...). The init script creates directories and copies config into ~/.openclaw/workspace/config — this is consistent with an ordinary skill installing itself into the user's OpenClaw workspace. However SKILL.md's language implying automatic application of global OpenClaw settings is stronger than the actual code (which only writes files to the workspace), so verify what will be changed before proceeding.

What to consider before installing

This package looks like an unfinished or poorly packaged skill rather than outright malicious code, but there are multiple red flags you should address before installing: (1) Missing implementations — many scripts referenced in index.js/package.json are not present, so commands will fail. (2) Inconsistent model settings — vector dimensionality differs between files (1024 vs 384); verify the correct model and dims before indexing. (3) Undeclared credentials — SKILL.md asks for an Edgefn API key but the skill metadata does not declare required env vars; do not provide credentials until you confirm where they will be used and stored. (4) Missing install hooks — package.json references install/uninstall scripts that don't exist. Recommended actions: inspect the upstream repository (request a canonical source URL), ask the author to provide the missing scripts and clarify credential usage, run the init and other operations in a sandbox or non-privileged account first, and avoid supplying API keys or broad permissions until the code is complete and reviewed. If you cannot validate the repository and author, treat this as untrusted and do not install on production systems.

🧠 Smart Memory System - 检索增强智能记忆系统

概述

基于检索增强（RAG）技术的智能记忆系统，为 OpenClaw 提供语义搜索、记忆优化和对话增强能力。

功能特性

🔍 智能检索

• 语义搜索取代关键词搜索
• 80% token 消耗减少
• 基于相关性的记忆提取

🏗️ 记忆优化

• 自动聚类相似记忆
• 重要性评分系统
• 过期记忆清理

⚡ 实时增强

• 对话上下文智能扩展
• 相关历史自动注入
• 个性化响应生成

技术架构

🛠️ 核心组件

1. 向量化引擎: BAAI/bge-m3 embedding 模型 (1024维向量)
2. 重排序模块: bge-reranker-v2-m3
3. 向量存储: 本地 JSON + 语义缓存
4. 相似度算法: 余弦相似度 + 自定义权重

📁 系统结构

smart-memory-skill/
├── SKILL.md              # 技能文档
├── config/               # 配置文件
│   ├── smart_memory.json   # 主配置
│   └── models.json         # 模型配置
├── scripts/              # 核心脚本
│   ├── vectorizer.js       # 向量化引擎
│   ├── retriever.js        # 检索引擎
│   ├── integrator.js       # OpenClaw集成
│   └── monitor.js          # 进度监控
├── templates/            # 模板文件
│   ├── memory_chunk.md     # 记忆分块模板
│   └── progress_report.md  # 进度报告模板
└── examples/             # 使用示例
    ├── basic_usage.md      # 基础用法
    └── advanced_integration.md # 高级集成

安装配置

1. 前置条件

• OpenClaw 已安装并运行
• Edgefn API 密钥（用于 BAAl/bge-m3 和 reranker 模型）
• Node.js 环境

2. 安装步骤

# 使用 ClawHub 安装
clawhub install smart-memory-system

# 或手动安装
git clone <repository>
cp -r smart-memory-skill ~/.openclaw/skills/

3. 配置模型

确保在 OpenClaw 配置中添加：

{
  "models": {
    "providers": {
      "edgefn": {
        "models": [
          {
            "id": "BAAI/bge-m3",
            "name": "BAAI bge-m3 Embedding",
            "api": "openai-completions",
            "embedding_dimensions": 1024
          },
          {
            "id": "bge-reranker-v2-m3", 
            "name": "BGE Reranker v2 m3",
            "api": "openai-completions"
          }
        ]
      }
    }
  }
}

使用方法

🔧 基础命令

# 初始化系统
openclaw skill smart-memory init

# 加载现有记忆
openclaw skill smart-memory load

# 语义搜索
openclaw skill smart-memory search "OpenClaw配置优化"

# 对话增强
openclaw skill smart-memory enhance "如何设置模型？"

# 系统状态
openclaw skill smart-memory status

⚙️ OpenClaw 集成

// 在 OpenClaw 配置中启用
{
  "skills": {
    "entries": {
      "smart-memory": {
        "enabled": true,
        "autoEnhance": true,
        "maxContextTokens": 2000
      }
    }
  }
}

🚀 高级功能

# 批量处理记忆文件
openclaw skill smart-memory batch-process ~/documents/

# 生成记忆报告
openclaw skill smart-memory report --format=html

# 优化索引
openclaw skill smart-memory optimize --aggressive

# 监控模式
openclaw skill smart-memory monitor --interval=5

性能指标

智能记忆系统优化

指标	改进前	改进后	提升
Token 消耗	8k-16k	1k-3k	-80%
检索准确率	60%	95%	+35%
响应相关性	70%	95%	+25%
记忆覆盖率	50%	90%	+40%

结合上下文压缩功能

系统已配置 OpenClaw 上下文压缩功能，提供双重优化：

上下文压缩配置

{
  "mode": "cache-ttl",
  "ttl": "5m",
  "keepLastAssistants": 3,
  "softTrimRatio": 0.3,
  "hardClearRatio": 0.5,
  "minPrunableToolChars": 50000,
  "softTrim": { "headChars": 1500, "tailChars": 1500 },
  "hardClear": { "enabled": true, "placeholder": "[旧工具结果内容已清理]" },
  "tools": { "deny": ["browser", "canvas"] }
}

双重优化效果

优化方式	Token 节省	实现机制
智能记忆系统	80%	语义检索替代完整历史
上下文压缩	70%	清理工具调用结果
双重优化	90%+	两者结合，全面优化

压缩触发条件

• 软修剪: 上下文使用率 > 30% (保留头尾1500字符)
• 硬清理: 上下文使用率 > 50% 且可修剪内容 > 50,000字符
• 保护机制: 保留最近3次助手回复和重要工具结果

使用场景

💼 个人助手

• 智能记住用户偏好和习惯
• 跨会话记忆延续
• 个性化建议生成

🏢 团队协作

• 共享知识库检索
• 项目历史追溯
• 决策依据存档

🔬 研究分析

• 文献智能检索
• 研究笔记整理
• 洞察发现支持

💻 开发支持

• 代码库语义搜索
• 技术文档检索
• 错误解决方案匹配

配置选项

主配置 (config/smart_memory.json)

{
  "embedding_model": "edgefn/BAAI/bge-m3",
  "reranker_model": "edgefn/bge-reranker-v2-m3",
  "chunk_size": 500,
  "overlap": 50,
  "top_k_results": 5,
  "min_similarity": 0.6,
  "cache_ttl_hours": 168,
  "auto_enhance": true,
  "max_context_tokens": 2000,
  "importance_scoring": {
    "age_weight": 0.2,
    "frequency_weight": 0.3,
    "relevance_weight": 0.5
  }
}

扩展开发

🔌 插件系统

// 自定义记忆处理器
class CustomMemoryProcessor {
  async process(memory) {
    // 自定义处理逻辑
    return enhancedMemory;
  }
}

// 注册插件
smartMemorySystem.registerPlugin('custom-processor', new CustomMemoryProcessor());

🎨 主题模板

// 自定义记忆模板
---
title: "{{title}}"
date: "{{date}}"
tags: ["{{tags}}"]
importance: {{importance}}
summary: "{{summary}}"
---

🔄 数据导出

支持多种格式导出：

• JSON（结构化数据）
• Markdown（可读文档）
• CSV（数据分析）
• HTML（可视化报告）

故障排除

🐛 常见问题

1. 向量化失败: 检查 Edgefn API 密钥和网络连接
2. 检索慢: 调整 chunk_size 和 top_k_results 参数
3. 内存占用高: 启用缓存清理或减少索引大小
4. 集成问题: 检查 OpenClaw 配置和权限

📋 日志查看

# 查看系统日志
tail -f ~/.openclaw/logs/smart-memory.log

# 查看调试信息
openclaw skill smart-memory debug --verbose

🛠️ 维护命令

# 清理缓存
openclaw skill smart-memory cleanup

# 重建索引
openclaw skill smart-memory reindex

# 备份数据
openclaw skill smart-memory backup ~/backup/

# 恢复系统
openclaw skill smart-memory restore ~/backup/latest/

路线图

🎯 近期计划

• 多语言支持
• 实时协作功能
• 移动端适配
• 更多导出格式

🔮 长期愿景

• 分布式记忆网络
• 预测性记忆推送
• 情感分析集成
• 跨平台同步

贡献指南

👥 开发贡献

1. Fork 项目仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

📝 文档贡献

• 完善使用示例
• 添加多语言文档
• 创建教程视频
• 翻译文档内容

🐛 问题反馈

在 GitHub Issues 中报告问题，包括：

1. 问题描述
2. 重现步骤
3. 预期行为
4. 实际行为
5. 环境信息

许可证

MIT License - 详见 LICENSE 文件

支持

• 📧 邮箱: [e-mail]
• 💬 Discord: 加入社区
• 📖 文档: 在线文档
• 🐛 Issues: GitHub Issues

---

🎉 欢迎使用检索增强智能记忆系统，让您的 OpenClaw 更智能、更高效！