Memori 扩展技能

使用 Memori Python 库实现记忆增强与大语言模型（LLM）调用拦截，并可选集成 Zhipu AI API。

概述

该技能基于 Memori Python 库，提供记忆增强与 LLM 调用拦截能力。它使智能体能够从本地记忆数据库中检索相关知识，并将这些信息注入对话上下文中。

安全与隐私声明

⚠️ 重要提示：本技能执行以下操作：

文件操作（始终启用）

• 读取/写入：本地 SQLite 数据库（默认路径：./memori.db）
• 读取/写入：可选的技术术语配置文件（默认路径：./config/tech_terms.txt）
• 所有文件操作均在本地完成，不会向外部传输任何数据。

外部 API 调用（可选 — 需显式配置）

• 触发条件：仅当设置了环境变量 ZHIPUAI_API_KEY 时生效
• 传输数据：对话文本（包括用户消息、系统提示词及助手响应）将发送至 Zhipu AI 服务器进行分析与增强
• 用途：利用 Zhipu AI 的语言模型提升对话理解能力
• 控制机制：若未设置 ZHIPUAI_API_KEY，该技能将 100% 在本地运行，不发起任何外部网络请求

使用建议

1. 优先本地测试：首次使用时请勿设置 ZHIPUAI_API_KEY，以验证本地功能是否正常
2. 明确授权：仅在您明确同意将对话内容发送至外部服务的前提下，才设置 ZHIPUAI_API_KEY
3. 审慎评估数据范围：启用外部 API 功能前，请确认您愿意传输的对话数据类型与范围
4. 沙箱环境先行验证：如需提供 API 密钥，请先在 sandbox 环境中测试，以充分理解数据流向

依赖项

本技能需安装以下 Python 包：

pip install memori

memori 库采用 Apache License Version 2.0 许可协议。

可选依赖项

如需启用 Zhipu AI API 增强功能（可选）：

pip install zhipuai

警告：安装 zhipuai 并配置 ZHIPUAI_API_KEY 后，对话内容将被发送至外部服务器。

环境变量

全部支持的环境变量

隐私与数据流向说明：

• ⚠️ 外部 API：仅 ZHIPUAI_API_KEY 变量会触发外部网络请求；其余变量仅控制本地文件操作。
• ✅ 纯本地模式：若不设置 ZHIPUAI_API_KEY，该技能将完全在本地运行，不对外传输任何数据。
• 📁 文件操作：该技能会读写数据库文件（memori.db），并可选地读写技术术语文件（tech_terms.txt）。所有文件均保存于您的本地文件系统中。
• 🔒 最佳实践：建议初始部署时不设置 ZHIPUAI_API_KEY，先验证本地功能；仅在确有增强需求且已接受对应数据传输条款时，再启用外部 API。

配置示例

系统环境变量配置：

# 可选：启用 Zhipu API 增强功能
export ZHIPUAI_API_KEY="your-api-key"
export ZHIPUAI_MODEL="glm-4.7"

# 可选：自定义技术术语
export MEMORI_TECH_TERMS="FFI,Rust,Linux,kernel,spinlock"

# 可选：指定自定义数据库路径
export MEMORI_DB_PATH="/path/to/memori.db"

OpenClaw 配置（openclaw.json）：

{
  "skills": {
    "entries": {
      "memori-extension": {
        "enabled": true,
        "env": {
          "ZHIPUAI_API_KEY": "your-api-key",
          "ZHIPUAI_MODEL": "glm-4.7",
          "MEMORI_TECH_TERMS": "FFI,Rust,Linux,kernel",
          "MEMORI_DB_PATH": "./memori.db"
        }
      }
    }
  }
}

技术术语文件（可选）：

# 创建配置目录
mkdir -p config

# 创建术语文件
cat > config/tech_terms.txt << EOF
FFI
Rust
Linux
kernel
spinlock
mutex
unsafe
EOF

# 设置环境变量
export MEMORI_TECH_TERMS_FILE="config/tech_terms.txt"

快速开始

方法 1：直接使用 Memori 库（推荐）

from memori import Memori

memori = Memori(
    db_path="memori.db",
    entity_id="knowledge-base"
)

# 检索记忆
memories = memori.search("query", limit=5)

# 增强查询
context = memori.augment("如何处理自旋锁冲突？", limit=3)

# 存储新记忆
memory_id = memori.store("新内容")

# 获取统计信息
stats = memori.get_stats()

# 关闭连接
memori.close()

方法 2：技能便捷 API

from skills.memori_extension import search, augment, intercept_llm

# 检索
memories = search("FFI 绑定", limit=5)

# 增强
enhanced = augment("如何处理自旋锁冲突？")
if enhanced:
    print(enhanced)

# 拦截 LLM 调用
messages = [{"role": "user", "content": "FFI 相关问题"}]
enhanced = intercept_llm(messages)

API 参考文档

Memori 类

__init__(db_path, entity_id)

初始化 Memori 实例。

参数：

• db_path（str | Path，可选）：数据库路径
• entity_id（str，可选）：实体 ID，默认为 "default"

search(query, limit, entity_id)

检索相关记忆。

返回值：List[Memory]

augment(query, limit, entity_id)

使用检索到的记忆增强原始查询。

返回值：AugmentedContext

store(content, entity_id, metadata)

存储一条新记忆。

返回值：int —— 记忆 ID

get_stats(entity_id)

获取统计信息。

返回值：dict

close()

关闭数据库连接。

Memory 类

记忆对象包含以下属性：

• id（int）：记忆 ID
• entity_id（str）：所属实体 ID
• content（str）：记忆内容
• created_at（str）：创建时间戳
• metadata（dict，可选）：元数据

AugmentedContext 类

增强后的上下文对象包含以下字段：

• original_query（str）：原始查询
• retrieved_memories（List[Memory]）：检索到的记忆列表
• enhanced_prompt（str）：增强后的提示词
• has_memories（bool）：是否成功检索到记忆
• memories_count（int）：检索到的记忆数量

配置说明

数据库

默认数据库路径：./memori.db

该技能将执行以下操作：

• ✅ 读取：从数据库中检索已存储的记忆
• ✅ 写入：向数据库中存储新的记忆
• ✅ 创建：若数据库文件不存在，则自动创建

技术术语

该技能使用可配置的技术术语来实现 LLM 调用拦截。您可通过以下方式自定义术语：

1. 环境变量方式（逗号分隔）：

export MEMORI_TECH_TERMS="FFI,Rust,Linux,kernel,spinlock,mutex,unsafe"

2. 配置文件方式（每行一个术语）：

# 创建配置文件
mkdir -p config
cat > config/tech_terms.txt << EOF
FFI
Rust
Linux
kernel
spinlock
mutex
unsafe
EOF

# 设置环境变量
export MEMORI_TECH_TERMS_FILE="config/tech_terms.txt"

注意：若未通过任一方式配置技术术语，该技能仍可正常运行，但对技术类查询的拦截效果可能下降。

安全注意事项

文件操作

该技能执行如下文件操作：

外部 API 调用

⚠️ 重要提示：若设置了 ZHIPUAI_API_KEY，该技能可能会将对话文本发送至 Zhipu AI 服务器进行增强处理。

禁用外部 API 调用的方法：

• 不设置 ZHIPUAI_API_KEY 环境变量即可
• 此时技能将仅依赖本地记忆检索，正常运行

使用建议

1. 启用前审查代码：在启用外部 API 功能前，请务必审阅相关源码
2. 沙箱环境先行验证：如需提供 API 密钥，请先在 sandbox 环境中测试
3. 合理设置文件权限：通过操作系统文件权限机制保护数据库与配置文件
4. 按需启用功能：仅启用您实际需要的功能模块

文件结构

skills/memori_extension/
├── __init__.py               # 技能入口文件
├── memori_extension.py       # 技能实现逻辑
├── SKILL.md                  # 本文档
└── README.md                 # 快速入门指南

许可证

本技能采用 Apache License Version 2.0 许可协议。

本技能所依赖的 memori Python 库同样采用 Apache License Version 2.0 许可协议。

归属声明

本技能集成了 Memori Python 库，该库遵循 Apache License 2.0 协议。
完整许可文本请参见 LICENSE 文件。

Memori 库相关信息：

• 版权所有 © 2025 Memori Team
• 许可证：Apache License 2.0
• 代码仓库：https://github.com/MemoriLabs/Memori