claw_lance_memory

基于 LanceDB 向量数据库的长期记忆与语义检索系统，支持自动抽取、分类和跨会话存储，快速响应集成 OpenClaw。

Security Scan

The skill mostly does what its description says (LanceDB-based memory + embedding), but there are internal inconsistencies (undeclared required API key, mismatched venv paths, scripts that modify shell rc and run at agent bootstrap) that warrant caution before installing.

Purpose & Capability

The code and documentation implement a LanceDB-based long-term memory using an external embedding service (智谱 AI / Zhipu). That aligns with the skill's name and description. However registry metadata claims no required environment variables or primary credential, while the code (ZhipuEmbedding) requires ZHIPU_API_KEY and will raise if it's missing — an inconsistency between declared requirements and actual needs.

Instruction Scope

SKILL.md and enable.sh instruct enabling a hook that calls a Python script at agent bootstrap. enable.sh writes the ZHIPU_API_KEY into ~/.bashrc (persistence), and the hook's handler.js execSyncs a Python script in the agent bootstrap path to produce a virtual USER_MEMORY.md injected into the agent's system prompt. These runtime instructions cause the agent environment to execute local code during bootstrap and to send user text to the external embedding API — both legitimate for a memory skill but sensitive (privacy/exfiltration) and broader than a purely local-only helper.

Install Mechanism

There is no remote ad-hoc download URL; installation is via pip (requirements.txt) and a local enable.sh that creates a venv and installs packages. Dependencies are public PyPI packages (lancedb, pyarrow, langchain, zhipuai, numpy). This is a standard but non-trivial install (networked pip installs). No evidence of obscure external downloads or archive extraction from unknown personal servers.

Credentials

The skill requires an embedding API key (ZHIPU_API_KEY) to function, which is proportional to using an external embedding service, but the registry metadata omitted this requirement. enable.sh suggests persistently writing the API key to ~/.bashrc (creates persistent secret in shell RC). The hook also reads OPENCLAW_USER_ID and uses HOME/~/.openclaw paths. The undeclared required env var and the suggested persistence of the API key are problematic and should be explicit and considered before use.

Persistence & Privilege

The skill does not request always:true and is user-invocable. However enabling the provided hook gives it the ability to execute at each agent bootstrap (handler.js runs session_start.py via execSync). That is an expected capability for a memory hook but increases blast radius: on bootstrap it will run local Python and call the embedding API and inject USER_MEMORY.md into the agent's system prompt. Users should be aware enabling the hook grants automatic execution at bootstrap until disabled.

What to consider before installing

Key things to consider before installing: - The code requires a ZHIPU_API_KEY even though the registry metadata didn't declare it; review and be sure you trust the embedding provider. Embedding calls will send text to the external service (智谱 AI), so do not store or send highly sensitive data (passwords, private keys, secrets) to this skill. - enable.sh suggests adding your API key to ~/.bashrc (persistent secret). Prefer setting the env var in a more controlled place (or use a temporary env) and avoid storing secrets in plaintext shell files if you care about confidentiality. - The hook (handler.js) will execute a Python script during agent bootstrap and inject a USER_MEMORY.md into the agent system prompt. That means saved memories become part of prompts the agent sees — a privacy surface. If you enable the hook, verify the exact handler path and permissions and test in an isolated environment first. - There are path/venv mismatches: enable.sh creates a venv in the repo (venv), but handler.js expects a venv at ~/.openclaw/workspace/venv-lancedb. Confirm and adjust paths before enabling the hook to avoid unexpected behavior. - The repository/source is listed as unknown with no homepage; prefer installing only from trusted sources. If you don't trust the author or need provenance, ask for a canonical repository or author contact and inspect the code yourself. - Recommended precautions: run the skill in an isolated VM/container, audit/grep the code for any outbound network calls beyond the embedding API, do not import highly sensitive personal data into the memory, and disable the hook (openclaw hooks disable memory-system) if you notice unexpected behavior. If you want, I can point out the exact lines that raise these issues (where ZHIPU_API_KEY is required, where enable.sh writes to ~/.bashrc, and where handler.js execSyncs the Python script), or produce a checklist to safely test this skill in a sandbox.

🧠 OpenClaw LanceDB Memory System

基于 LanceDB 向量数据库的智能记忆系统，为 OpenClaw Agent 提供长期记忆和语义检索能力。

✨ 特性

• 🔍 语义检索 - 理解意思，不只是关键词匹配
• 🧠 自动分类 - preference/fact/task/general 四种记忆类型
• 🤖 自动抽取 - 从对话中自动识别重要信息
• 💾 长期存储 - 持久化存储，跨 session 使用
• ⚡ 毫秒响应 - 向量检索，快速响应
• 🔌 即插即用 - OpenClaw Hook 集成，自动加载

🚀 快速开始

1. 安装依赖

# 克隆仓库
git clone https://github.com/asbinbin/claw_lance.git
cd claw_lance

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

2. 配置 API Key

# 获取智谱 AI API Key: https://open.bigmodel.cn/
export ZHIPU_API_KEY="your-api-key-here"

3. 启用 Hook

# 方法 1: 使用启用脚本
bash enable.sh

# 方法 2: OpenClaw 命令
openclaw hooks enable memory-system

4. 测试

# 查看用户画像
python3 skill.py profile

# 添加记忆
python3 skill.py add --content "我喜欢简洁" --type preference

# 检索记忆
python3 skill.py search --query "项目"

📚 文档

• 安装指南
• 使用手册
• API 参考
• Hook 集成
• 常见问题

🎯 记忆类型

类型	说明	触发词	例子
preference	偏好、习惯	我喜欢/我偏好/我习惯	"我喜欢简洁的汇报风格"
fact	事实、背景	我是/我负责/我擅长	"我负责 POC 项目"
task	任务、待办	我需要/别忘了/明天要	"每周四提交 OKR 周报"
general	其他	-	对话历史、临时信息

🔧 命令行使用

# 查看用户画像
python3 skill.py profile

# 检索记忆
python3 skill.py search --query "项目" --k 5

# 添加记忆
python3 skill.py add --content "我喜欢 Markdown" --type preference

# 自动抽取（从消息中识别记忆）
python3 skill.py auto --message "我负责 POC 项目，喜欢简洁的代码"

# 查看统计信息
python3 skill.py stats

# 清理过期记忆
python3 skill.py cleanup

💻 Python API

from skills.memory.openclaw_integration import OpenClawMemoryIntegration

# 初始化
mem = OpenClawMemoryIntegration(user_id="ou_xxx")

# 生成 system prompt（包含记忆）
prompt = mem.get_session_system_prompt("你是小美式")

# 检索记忆
results = mem.search_memory("项目", k=5)
for r in results:
    print(f"{r['type']}: {r['content']}")

# 添加记忆
mem.add_memory("我喜欢简洁", type="preference", importance=0.8)

# 获取用户画像
profile = mem.get_user_profile()
print(f"偏好：{profile['preferences']}")
print(f"事实：{profile['facts']}")
print(f"任务：{profile['tasks']}")

🏗️ 架构

┌─────────────────────────────────────────┐
│          OpenClaw Agent                  │
│                                          │
│  ┌────────────────────────────────────┐ │
│  │  Memory Hook (handler.js)          │ │
│  │  - 拦截 agent:bootstrap 事件         │ │
│  │  - 调用 Python 脚本                  │ │
│  │  - 注入 USER_MEMORY.md             │ │
│  └────────────────────────────────────┘ │
└─────────────────────────────────────────┘
         ↓
┌─────────────────────────────────────────┐
│       Python 记忆模块                     │
│                                          │
│  ┌────────────────────────────────────┐ │
│  │  openclaw_integration.py           │ │
│  │  - OpenClaw 集成接口                │ │
│  │  - 生成 system prompt              │ │
│  └────────────────────────────────────┘ │
│              ↓                           │
│  ┌────────────────────────────────────┐ │
│  │  lancedb_memory.py                 │ │
│  │  - LanceDB 记忆管理                 │ │
│  │  - 向量检索                        │ │
│  └────────────────────────────────────┘ │
│              ↓                           │
│  ┌────────────────────────────────────┐ │
│  │  auto_memory.py                    │ │
│  │  - 自动记忆抽取                    │ │
│  │  - 模式匹配                        │ │
│  └────────────────────────────────────┘ │
└─────────────────────────────────────────┘
         ↓
┌─────────────────────────────────────────┐
│        LanceDB 向量数据库                │
│        memory_lancedb/                  │
│                                          │
│  - 向量存储（智谱 AI Embedding）         │
│  - 语义检索                             │
│  - 多用户隔离                           │
└─────────────────────────────────────────┘

📊 成本

智谱 AI Embedding:

• 免费额度：100 万 tokens（注册就送）
• 价格：¥0.0005/1K tokens
• 记忆系统用量：~50 tokens/条
• 100 万 tokens ≈ 20,000 条记忆

LanceDB:

• 本地部署，完全免费
• 内存占用：~200MB
• 磁盘占用：~100MB（每 1000 条记忆）

🔒 隐私与安全

• ✅ 本地存储: 所有记忆数据存储在本地
• ✅ API 加密: 使用 HTTPS 调用智谱 AI API
• ✅ 多用户隔离: 不同用户的数据完全隔离
• ✅ 无数据上传: 记忆数据不会上传到任何服务器

🛠️ 开发

项目结构

claw_lance/
├── README.md                 # 项目说明
├── requirements.txt          # Python 依赖
├── enable.sh                 # 启用脚本
├── skill.py                  # 命令行入口
├── hooks/
│   └── memory-system/
│       ├── HOOK.md           # Hook 元数据
│       └── handler.js        # Hook 处理器
├── skills/
│   └── memory/
│       ├── lancedb_memory.py        # LanceDB 核心
│       ├── openclaw_integration.py  # OpenClaw 集成
│       ├── auto_memory.py           # 自动记忆抽取
│       └── session_start.py         # Session 启动脚本
├── docs/                     # 文档目录
│   ├── INSTALL.md
│   ├── USAGE.md
│   ├── API.md
│   ├── HOOK.md
│   └── FAQ.md
└── tests/                    # 测试目录
    └── test_memory.py

运行测试

# 安装测试依赖
pip install pytest

# 运行测试
pytest tests/

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📝 更新日志

v1.0.0 (2026-03-31)

• ✨ 初始版本发布
• 🔍 语义检索功能
• 🧠 自动记忆抽取
• 🔌 OpenClaw Hook 集成
• 📚 完整文档

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• LanceDB - 向量数据库
• 智谱 AI - Embedding 服务
• OpenClaw - Agent 框架

📮 联系方式

• GitHub Issues: 提问
• 项目主页：https://github.com/asbinbin/claw_lance_memory

---

Made with ❤️ by 小美式 ☕