Metadata

name: hawk-bridge
description: OpenClaw Hook Bridge + context-hawk Python Memory Engine. Auto-capture memories on every reply, auto-inject relevant memories before each response. Supports 4-tier decay, hybrid vector + BM25 search, and Markdown import.
metadata: {"openclaw":{"emoji":"🦅","requires":{"anyBins":["node","python3.12"]},"install":[{"id":"node-deps","kind":"npm","package":"@lancedb/lancedb","label":"Install LanceDB (npm)"},{"id":"python-deps","kind":"pip","package":"lancedb openai rank-bm25","label":"Install Python deps"}]}}

hawk-bridge — OpenClaw 记忆系统 Skill

OpenClaw Hook Bridge + context-hawk Python Memory Engine 单一 Skill，同时解决：自动记忆捕获 + 自动记忆检索 + 四层衰减 + 向量搜索 + Markdown兼容

核心能力

能力	说明
autoCapture Hook	每次回复后，自动用 LLM 提取对话内容 → 存入 LanceDB
autoRecall Hook	每次回复前，自动检索相关记忆 → 注入上下文
四层记忆衰减	Working → Short → Long → Archive，自动淘汰低价值记忆
混合检索	向量 + BM25 + RRF融合 + 噪声过滤 + 交叉编码重排
6大检索优化	Query扩展 · MMR多样性 · 置信度过滤 · 分域加权BM25 · 会话感知 · 结果压缩
Markdown兼容	一键导入用户已有 `.md` 记忆文件
零配置	默认 Jina 免费 Embedding API，装完就能用，无需任何 API Key
28条文本清洗	Markdown/URL/标点/时间戳/Emoji/HTML/调试日志等自动清理
敏感信息安全	API Key/电话/邮箱/身份证/信用卡自动脱敏后存储
TTL 过期	记忆默认30天自动过期，节省存储空间
Recall 阈值门控	relevance score < minScore 的记忆不注入上下文
审计日志	所有 capture/skip/reject/recall 事件记录到 `~/.hawk/audit.log`
有害内容过滤	暴力/欺诈/黑客/CSAM 等内容在 capture 阶段直接拒绝
多模态记忆	支持 text / audio / video 三种来源，统一存储统一检索

多模态记忆

hawk-bridge v1.2+ 支持多模态记忆，统一存储 text、audio、video 类型的记忆。

记忆来源类型

source_type	说明	典型场景
`text`	文本对话（默认）	聊天记录、文档内容
`audio`	音频记忆	通话录音、会议录音、语音消息
`video`	视频记忆	会议录像、课程视频、演示文稿

数据模型

所有记忆统一存储在 hawk_memories 表，通过 source_type 字段区分：

interface MemoryEntry {
  id: string;
  text: string;              // ASR 转录文本 / 视频描述
  vector: number[];          // 文本嵌入向量
  category: string;          // fact | preference | decision | entity
  scope: string;
  importance: number;
  timestamp: number;
  expiresAt: number;
  metadata: Record<string, unknown>;  // 类型特有元数据
  source_type: 'text' | 'audio' | 'video';  // 记忆来源
}

metadata 结构

// audio 记忆
metadata: {
  audio: {
    path: "/path/to/audio.mp3",
    duration_ms: 180000,           // 180秒
    speaker: "张三",
    emotion: "neutral",
    transcript_segments: [
      { start: 0, end: 5000, text: "大家好..." },
      { start: 5000, end: 12000, text: "今天讨论..." }
    ]
  }
}

// video 记忆
metadata: {
  video: {
    path: "/path/to/video.mp4",
    duration_ms: 300000,
    description: "产品发布会演示文稿讲解",
    keyframes: [
      { timestamp: 10000, description: "开场白" },
      { timestamp: 60000, description: "产品介绍" }
    ]
  }
}

检索示例

// 检索所有记忆（默认 text only）
const results = await retriever.search("用户偏好");

// 检索 text + audio
const results = await retriever.search("上周那个客户电话说了什么", 5, undefined, ["text", "audio"]);

// 检索所有类型
const results = await retriever.search("那个演示文稿", 5, undefined, ["text", "audio", "video"]);

架构

OpenClaw Gateway (TypeScript Hooks)
    │
    ├── agent:bootstrap → hawk-recall hook
    │       → HybridRetriever
    │       ┌─────────────────────────────────────────────────────┐
    │       │ 1. Query Expansion (查询扩展成多个相关表述)          │
    │       │ 2. Multi-query Vector+BM25 (每个查询独立检索)        │
    │       │ 3. RRF Fusion (结果融合)                           │
    │       │ 4. Noise Filter (去除"好的""收到"等噪声)          │
    │       │ 5. Cross-encoder Rerank (重排)                     │
    │       │ 6. Confidence Threshold (置信度过滤)                │
    │       │ 7. MMR Diversity (多样性排序)                       │
    │       │ 8. Layer Penalty (低层级降权)                      │
    │       │ 9. Result Compression (长文本压缩)                  │
    │       └─────────────────────────────────────────────────────┘
    │       → 记忆注入上下文 🦅
    │
    └── message:sent → hawk-capture hook
            → Python LLM 智能提取（fact/preference/decision/entity/other）
            → 存入 LanceDB
            → Governance 日志

Python Core (hawk_memory/)
    ├── memory.py       — MemoryManager 四层衰减
    ├── compressor.py   — ContextCompressor 上下文压缩
    ├── self_improving.py — 自我反思学习
    ├── extractor.py    — LLM 6类分类提取
    ├── governance.py   — 系统巡检指标
    ├── vector_retriever.py — 向量检索
    └── markdown_importer.py — .md 文件导入

安装

方式1：OpenClaw Skill（推荐）

openclaw skills install https://github.com/relunctance/hawk-bridge

方式2：手动安装

git clone git@github.com:relunctance/hawk-bridge.git /path/to/hawk-bridge
cd /path/to/hawk-bridge
npm install
pip install lancedb openai rank_bm25

注册到 openclaw.json

{
  "plugins": {
    "load": {
      "paths": ["/absolute/path/to/hawk-bridge"]
    },
    "allow": ["hawk-bridge"]
  }
}

自动配置（零额外Key）

embedding + LLM 默认使用 OpenClaw 已配置的 provider（minimax 等）：

配置项	来源	说明
embedding provider	openclaw.json `models.providers`	自动检测
LLM provider	openclaw.json `models.providers`	自动检测
API Key	openclaw.json `auth.profiles`	自动透传

环境变量覆盖（可选）：

export MINIMAX_API_KEY="your-key"        # Minimax API Key
export MINIMAX_BASE_URL="https://..."     # 自定义端点
export MINIMAX_MODEL="MiniMax-M2.7"      # 指定模型
export OLLAMA_BASE_URL="http://localhost:11434"  # Ollama本地（免费）
export LLM_PROVIDER="groq"               # 切换LLM后端

配置项（openclaw.json）

大部分情况不需要配置——装完默认 Jina 免费 API 就能跑。

如需定制，在 openclaw.json 的 plugins.entries.hawk-bridge.config 下添加：

{
  "plugins": {
    "entries": {
      "hawk-bridge": {
        "enabled": true,
        "config": {
          "embedding": {
            "provider": "jina",
            "apiKey": "",          // jina 免费，无需填
            "model": "jina-embeddings-v5-small",
            "dimensions": 1024
          },
          "llm": {
            "provider": "groq",
            "apiKey": "",          // groq 免费，无需填
            "model": "llama-3.3-70b-versatile"
          },
          "recall": {
            "topK": 5,
            "minScore": 0.6,
            "injectEmoji": "🦅"
          },
          "capture": {
            "enabled": true,
            "maxChunks": 3,
            "importanceThreshold": 0.5,
            "ttlMs": 2592000000,
            "maxChunkSize": 2000,
            "minChunkSize": 20,
            "dedupSimilarity": 0.95
          },
          "audit": {
            "enabled": true
          },
          "python": {
            "pythonPath": "python3.12",
            "hawkDir": "~/.openclaw/hawk"
          },
          "optimizer": {
            "queryExpansionEnabled": true,
            "queryExpansionCount": 3,
            "mmrEnabled": true,
            "mmrLambda": 0.5,
            "confidenceThresholdEnabled": true,
            "confidenceThreshold": 0.3,
            "fieldWeightedBm25Enabled": true,
            "compressionEnabled": true,
            "compressionMaxChars": 200
          }
        }
      }
    }
  }
}

Python API

四层记忆 + 衰减

from hawk_memory import MemoryManager

mm = MemoryManager()
mm.store("用户偏好：喜欢简洁的回复风格", category="preference")
results = mm.recall("用户的沟通风格是什么")
print(results)

向量检索

from hawk_memory.vector_retriever import VectorRetriever

retriever = VectorRetriever(top_k=5)
chunks = retriever.recall("老板之前部署过哪些服务")
print(retriever.format_for_context(chunks))

Markdown 导入

from hawk_memory.markdown_importer import MarkdownImporter

importer = MarkdownImporter(memory_dir="~/.openclaw/memory")
result = importer.import_all()  # 增量导入，已导入的打标签跳过
print(f"导入 {result['files']} 个文件, {result['chunks']} 个块")

上下文压缩

from hawk_memory.compressor import ContextCompressor

compressor = ContextCompressor(max_tokens=4000)
compressed = compressor.compress(conversation_history)

自我反思

from hawk_memory.self_improving import SelfImproving

si = SelfImproving()
si.learn_from_error("记忆提取返回空", context={"query": "..."})
stats = si.get_stats()

6 大检索优化策略

1. Query Expansion（查询扩展）

将用户的一个问题扩展成 3-4 个语义相关的表述，分别检索再合并。

query = "openclaw 架构"
// 扩展为：
// ["openclaw 架构", "openclaw design", "openclaw 底层原理", "openclaw 系统概览"]
// 各查询独立检索 → RRF 合并 → 解决"措辞不一致"导致的漏召回

触发： optimizerConfig.queryExpansionEnabled = true（默认开启）

2. MMR Diversity（最大边际相关性）

在选择最终 topK 时，故意选一些"和已有结果不太一样"的内容，保证多样性。

// MMR 公式：λ × 相关性 - (1-λ) × 与已选结果的最大相似度
while (results.length < topK) {
  next = max(λ × rerankScore - (1-λ) × maxSimilarityToSelected)
}

λ 值	效果
0.0	只顾相关性，和原 RRF 一样
0.5（默认）	平衡相关性和多样性
1.0	最高多样性

触发： optimizerConfig.mmrEnabled = true, mmrLambda = 0.5（默认开启）

3. Confidence Threshold（置信度过滤）

重排后设一个最低分数阈值，低于阈值的直接丢弃，不进入最终结果。

// 低于 0.3 分的记忆直接丢弃
.filter(r => r.rerankScore >= 0.3)

触发： optimizerConfig.confidenceThresholdEnabled = true（默认开启，阈值 0.3）

4. Field-weighted BM25（分域加权）

对 text、category、scope 三个字段分别 BM25 检索，给 category 和 scope 更高权重。

// 公式：score = bm25(text)×1.0 + bm25(category)×2.0 + bm25(scope)×1.5
// category 命中（如 "fact"）比普通文本匹配权重更高

触发： optimizerConfig.fieldWeightedBm25Enabled = true（默认开启）

5. Session Context Awareness（会话上下文感知）

把最近 1-3 轮对话的摘要拼入 query，让检索理解当前话题。

// 从 session messages 中提取最近 user queries，构建 conversationSummary
// "openclaw 架构 | openclaw 底层原理"  → 组合查询
sessionContext = {
  recentQueries: ["openclaw 底层原理", "openclaw 架构"],
  conversationSummary: "openclaw 底层原理 | openclaw 架构"
}

触发： 自动注入（从 sessionEntry.messages 中提取）

6. Result Compression（结果压缩）

对超过 200 字符的记忆文本，在注入上下文前截断到句子边界。

// 超过 maxChars 的文本，截断到最后一个句号或换行符
compressText(text, maxChars = 200)
// "这是很长的记忆文本..." → "这是很长的记忆文本。"（自然断句）

触发： optimizerConfig.compressionEnabled = true（默认开启，200字符）

CLI 工具

# 导入 Markdown 记忆文件
python3.12 -m hawk_memory.markdown_importer --dry-run  # 预览
python3.12 -m hawk_memory.markdown_importer            # 实际导入

# 记忆提取（LLM 6类分类）
echo "对话内容..." | python3.12 -m hawk_memory.extractor --provider openclaw

# 查看记忆数量
python3.12 -c "from hawk_memory import MemoryManager; print(MemoryManager().count())"

# 查看治理指标
python3.12 -c "from hawk_memory.governance import Governance; print(Governance().get_stats(24))"

与 context-hawk 的关系

不要单独装 context-hawk！ hawk-bridge 安装脚本会自动克隆 context-hawk 到 ~/.openclaw/workspace/context-hawk，并通过符号链接 ~/.openclaw/hawk 指向它。

	hawk-bridge	context-hawk
安装方式	`openclaw plugins install` 或 `clawhub install`	由 hawk-bridge 自动管理
手动安装 context-hawk？	❌ 不要	会造成双份记忆数据
独立使用？	❌ 不支持，必须配合 OpenClaw	✅ 可以，Python 库方式单独使用

正确的安装流程：

# 方式1：clawhub（推荐）
clawhub install hawk-bridge

# 方式2：直接安装脚本（自动处理一切）
bash <(curl -fsSL https://raw.githubusercontent.com/relunctance/hawk-bridge/master/install.sh)

卸载：

openclaw plugins uninstall hawk-bridge   # 移除插件
rm -rf ~/.openclaw/hawk ~/.hawk         # 清除记忆数据（不可恢复！）
rm -rf ~/.openclaw/workspace/context-hawk

目录结构

hawk-bridge/                          ← OpenClaw 插件（TypeScript）
├── SKILL.md
├── install.sh                        ← 一键安装脚本
├── openclaw.plugin.json              ← 插件元数据 + 配置schema
├── manifest.json                     ← Hook 注册信息
├── package.json
└── src/
    ├── index.ts                     # 插件入口
    ├── config.ts                    # 自动读取 openclaw.json 配置
    ├── lancedb.ts                   # LanceDB 封装
    ├── embeddings.ts                # 向量化（多后端）
    ├── retriever.ts                 # 混合检索管线
    ├── constants.ts                 # 所有可调参数
    └── hooks/
        ├── hawk-recall/
        │   ├── handler.ts           # autoRecall handler
        │   └── HOOK.md
        └── hawk-capture/
            ├── handler.ts           # autoCapture handler（含 normalize）
            └── HOOK.md

~/.openclaw/workspace/context-hawk/  ← Python 记忆引擎（安装脚本自动克隆）
└── hawk/
    ├── memory.py                    # 四层记忆管理
    ├── normalize.py                 # 28条文本清洗（与 TypeScript 层同步）
    ├── extractor.py                  # LLM 6类提取
    ├── vector_retriever.py           # 向量检索
    ├── compressor.py                 # 上下文压缩
    ├── self_improving.py            # 自我反思
    ├── governance.py                 # 治理指标
    └── markdown_importer.py          # Markdown 导入

~/.openclaw/hawk → ~/.openclaw/workspace/context-hawk/hawk  ← 符号链接
~/.hawk/                                             ← LanceDB 数据目录
~/.hawk/audit.log                                    ← 审计日志

依赖

npm: npm install

@lancedb/lancedb ≥ 0.26.2
openai ≥ 6.21.0
rank_bm25 ≥ 1.2.0

Python: pip install

lancedb
openai
rank_bm25

Hawk Bridge

安装技能