Skill: relunctance/hawk-memory-v2 (version 1.0.0)

# 🦅 Context-Hawk — AI 记忆守护者 > **纯 Python 记忆包，零外部依赖，零 API Key，直接 import 就能用** *让任何 Python 项目或 AI Agent 拥有记忆能力——跨会话、跨话题、跨时间。* --- ## 定位 **纯 Python 包，可独立使用** - 不需要 OpenClaw，不需要 API Key - `pip install` 后直接 `from hawk.memory import MemoryManager` - 可嵌入任何 Python 项目（AI Agent、脚本、爬虫等） **配合 hawk-bridge 使用时**，hawk-bridge 负责 autoCapture/autoRecall Hook，context-hawk 提供底层 Python 核心。 --- ## 核心模块 | 模块 | 功能 | API Key | |------|------|---------| | `MemoryManager` | 四层记忆衰减（Working/Short/Long/Archive） | ❌ | | `ContextCompressor` | 上下文压缩，按 token 限制 | ❌ | | `Config` | 配置管理 | ❌ | | `SelfImproving` | 自我反思，错误模式学习 | ❌ | | `VectorRetriever` | 向量语义检索（LanceDB） | ❌* | | `MarkdownImporter` | 导入 .md 记忆文件 | ❌* | | `Extractor` | 记忆提取（6类分类） | ⚠️ 可选 | | `Governance` | 系统巡检指标 | ❌ | *VectorRetriever 和 MarkdownImporter 需要 LanceDB（免费本地）* --- ## 安装 ```bash pip install lancedb ``` 不需要任何 API Key，纯本地运行。 --- ## 快速开始 ```python from hawk.memory import MemoryManager # 创建记忆管理器 mm = MemoryManager() # 存入记忆 mm.store("用户喜欢简洁的回复风格", category="preference") mm.store("公司叫趣近团队", category="entity") mm.store("老板决定用Go语言重构", category="decision") # 检索记忆 results = mm.recall("老板的风格偏好") for r in results: print(f"{r.layer}: {r.text}") # 查看统计 print(mm.get_stats()) # {'working': 2, 'short': 1, 'long': 0, 'archive': 0, 'total': 3, 'avg_importance': 0.65} ``` --- ## MemoryManager — 四层记忆 ``` Working → Short → Long → Archive ↑ ↓ ←──── Weibull 衰减 ←←← ``` ```python from hawk.memory import MemoryManager mm = MemoryManager() # 存入，指定重要程度（0.0-1.0） mm.store("这是重要决策", category="decision", importance=0.9) mm.store("普通信息", category="fact", importance=0.4) # 触发衰减（清理低价值记忆） mm.decay() # 访问记忆（更新计数器，可能触发层级升级） item = mm.access("memory_id") print(f"访问次数: {item.access_count}") ``` --- ## VectorRetriever — 向量语义检索 需要先设置 `OPENAI_API_KEY`（可选，用于 embedding） ```python from hawk.vector_retriever import VectorRetriever retriever = VectorRetriever(top_k=5, min_score=0.6) # 检索相关记忆 chunks = retriever.recall("老板之前部署过哪些服务") print(retriever.format_for_context(chunks)) ``` **输出：** ``` 🦅 [记忆检索结果] [entity] (85%相关): 趣近团队的服务器部署在阿里云 [fact] (72%相关): 生产环境用 Docker Compose 管理 ``` --- ## MarkdownImporter — 导入 .md 记忆文件 一键把已有的 `.md` 记忆文件导入向量库： ```python from hawk.markdown_importer import MarkdownImporter importer = MarkdownImporter(memory_dir="~/.openclaw/memory") # 扫描预览 chunks = importer.scan() print(f"发现 {len(chunks)} 个记忆块") # 一键导入（增量，已导入的打标签跳过） result = importer.import_all() print(f"导入完成: {result['files']} 个文件, {result['chunks']} 个块") ``` **CLI：** ```bash python3.12 -m hawk.markdown_importer --dry-run # 预览 python3.12 -m hawk.markdown_importer # 实际导入 ``` --- ## ContextCompressor — 上下文压缩 按 token 限制压缩对话历史： ```python from hawk.compressor import ContextCompressor compressor = ContextCompressor(max_tokens=4000) conversation = [ {"role": "user", "content": "我们要做XX项目"}, {"role": "assistant", "content": "好的，我来规划"}, # ... 100 轮对话 ] result = compressor.compress(conversation) print(f"压缩率: {result['compression_ratio']}") print(result['compressed']) ``` --- ## Extractor — 记忆提取 **零 API 模式（关键词提取，完全离线）：** ```python from hawk.extractor import extract_memories text = "用户说他喜欢用Go语言，公司叫趣近团队，决定用Docker部署" memories = extract_memories(text, provider="keyword") # 不需要任何 API Key ``` **有 API Key 时（LLM 6类分类，更精准）：** ```python # 设置环境变量 import os os.environ["OPENAI_API_KEY"] = "sk-xxx" # 或 os.environ["MINIMAX_API_KEY"] = "sk-cp-xxx" memories = extract_memories(text, provider="openai") # 或 memories = extract_memories(text, provider="minimax", [REDACTED_SECRET]", model="MiniMax-M2.7", base_url="https://api.minimaxi.com/anthropic") ``` **输出示例：** ```python [ {"text": "喜欢用Go语言", "category": "preference", "importance": 0.8, "abstract": "用户偏好Go", "overview": "[preference] 喜欢用Go语言"}, {"text": "公司叫趣近团队", "category": "entity", "importance": 0.9, "abstract": "公司名称", "overview": "[entity] 公司叫趣近团队"}, {"text": "决定用Docker部署", "category": "decision", "importance": 0.95, "abstract": "部署决策", "overview": "[decision] 决定用Docker部署"} ] ``` --- ## SelfImproving — 自我反思 ```python from hawk.self_improving import SelfImproving si = SelfImproving() # 记录错误 si.learn_from_error( error_type="recall_miss", context={"query": "老板上次说的项目", "results": []}, correction="改进了检索关键词策略" ) # 获取统计 print(si.get_stats()) # {'total': 1, 'resolved': 0, 'unresolved': 1, 'by_type': {'recall_miss': 1}} # 获取未解决的问题 unresolved = si.get_unresolved() for u in unresolved: print(f"待解决: {u.error_type} - {u.context}") ``` --- ## Governance — 系统巡检 ```python from hawk.governance import Governance gov = Governance() # 记录指标 gov.log_extraction(total=10, stored=3, skipped=7) gov.log_noise_filter(filtered_count=2, total=10) gov.log_recall(hits=2, total=5) # 查看24小时统计 stats = gov.get_stats(hours=24) print(stats) # {'extractions': 10, 'noise_filtered': 2, 'recalls': 5, 'recall_hits': 2, ...} ``` --- ## HawkContext — autoCapture + autoRecall 包装器 HawkContext 是一个 Python 上下文管理器，包装 LLM 调用，自动实现： - **autoRecall**：对话开始时自动检索相关记忆并注入上下文 - **autoCapture**：对话结束时自动提取记忆存入 LanceDB ```python from hawk import HawkContext # 初始化（自动从环境变量读取配置） hawk = HawkContext( provider="minimax", # minimax | openai | groq | ollama | keyword [REDACTED_SECRET]", model="MiniMax-M2.7" ) # 对话开始时自动 recall # 对话结束时（with 块退出时）自动 capture with hawk: response = hawk.chat( "老板之前用什么技术栈？", system_prompt="你是一个助手" ) print(response) # 也可以手动控制 hawk.recall("用户的项目偏好") hawk.capture() ``` **自动 recall 机制：** - `hawk.recall()` 在 `hawk.chat()` 内部被调用 - 检索当前用户消息相关的记忆 - 结果自动插入 LLM 消息中 **支持 provider：** | provider | API Key | 说明 | |----------|---------|------| | minimax | 需要 | MiniMax-M2.7（推荐） | | openai | 需要 | GPT-4o 等 | | groq | 不需要 | 免费 Llama-3 | | ollama | 不需要 | 本地模型 | | keyword | 不需要 | 纯规则提取 | **配置优先级：** 1. 显式传参 > 环境变量 > 默认值 --- ## 与 hawk-bridge 的关系 | | context-hawk | hawk-bridge | |---|---|---| | **定位** | 纯 Python 包 | OpenClaw Hook 插件 | | **触发方式** | 手动调用 / 脚本 | 自动 Hook | | **API Key** | 可选（keyword模式不需要） | 需要 | | **用途** | 任何 Python 项目 | OpenClaw 用户 | **推荐组合：** - 独立 Python 项目 → 只装 context-hawk - OpenClaw 用户 → 装 hawk-bridge（内置 context-hawk 核心） --- ## 目录结构 ``` context-hawk/ ├── SKILL.md ← 本文档 ├── hawk/ │ ├── __init__.py │ ├── memory.py ← 四层记忆 + 衰减 │ ├── compressor.py ← 上下文压缩 │ ├── config.py ← 配置管理 │ ├── self_improving.py ← 自我反思 │ ├── vector_retriever.py ← 向量检索 │ ├── markdown_importer.py ← .md 导入 │ ├── extractor.py ← 记忆提取（keyword / LLM） │ └── governance.py ← 巡检指标 └── scripts/ └── install.sh ← 一键安装脚本 ```

path: README.de.md
content: # 🦅 Context-Hawk

> **KI-Kontext-Gedächtnis-Wächter** — Hör auf, den Faden zu verlieren, und fang an, dich an das Wichtige zu erinnern.

*Gib jedem KI-Agenten ein Gedächtnis, das wirklich funktioniert — über Sessions, Themen und Zeit hinweg.*

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![OpenClaw Compatible](https://img.shields.io/badge/OpenClaw-2026.3%2B-brightgreen)](https://github.com/openclaw/openclaw)
[![ClawHub](https://img.shields.io/badge/ClawHub-context--hawk-blue)](https://clawhub.com)

**English** | [中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Français](README.fr.md) | [Español](README.es.md) | [Deutsch](README.de.md) | [Italiano](README.it.md) | [Русский](README.ru.md) | [Português (Brasil)](README.pt-BR.md)

---

## Was es macht

Die meisten KI-Agenten leiden an **Amnesie** — jede neue Sitzung beginnt bei Null. Context-Hawk löst das mit einem produktionsreifen Gedächtnisverwaltungssystem, das automatisch erfasst, was wichtig ist, Rauschen verblassen lässt und die richtige Erinnerung zum richtigen Zeitpunkt abruft.

**Ohne Context-Hawk:**
> "Ich habe es dir schon gesagt — ich mag kurze Antworten!"
> (nächste Sitzung, der Agent vergisst es wieder)

**Mit Context-Hawk:**
> (wendet stillschweigend deine Kommunikationspräferenzen aus Sitzung 1 an)
> ✅ Liefert jedes Mal eine präzise, direkte Antwort

---

## ✨ 10 Kernfunktionen

| # | Funktion | Beschreibung |
|---|---------|-------|
| 1 | **Aufgabenstatus-Persistenz** | `hawk resume` — Status speichern, nach Neustart fortsetzen |
| 2 | **4-stufiges Gedächtnis** | Working → Short → Long → Archive mit Weibull-Abfall |
| 3 | **Strukturiertes JSON** | Wichtigkeitsbewertung (0-10), Kategorie, Ebene, L0/L1/L2-Schichten |
| 4 | **KI-Wichtigkeitsbewertung** | Erinnerungen automatisch bewerten, minderwertige Inhalte verwerfen |
| 5 | **5 Injektionsstrategien** | A(high-imp) / B(aufgabenbezogen) / C(rezent) / D(top5) / E(voll) |
| 6 | **5 Kompressionsstrategien** | summarize / extract / delete / promote / archive |
| 7 | **Selbst-Introspektion** | Prüft Aufgabenklarheit, fehlende Informationen, Schleifenerkennung |
| 8 | **LanceDB-Vektorsuche** | Optional — hybride Vektor + BM25-Suche |
| 9 | **Reines Gedächtnis-Fallback** | Funktioniert ohne LanceDB, JSONL-Datei-Persistenz |
| 10 | **Auto-Deduplizierung** | Führt doppelte Erinnerungen automatisch zusammen |

---

## 🏗️ Architektur

```
┌──────────────────────────────────────────────────────────────┐
│                      Context-Hawk                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  Working Memory  ←── Aktuelle Sitzung (letzte 5-10 Runden)  │
│       ↓ Weibull-Abfall                                        │
│  Short-term      ←── 24h Inhalt, zusammengefasst            │
│       ↓ access_count ≥ 10 + Wichtigkeit ≥ 0.7             │
│  Long-term       ←── Permanentes Wissen, vektorindiziert   │
│       ↓ >90 Tage oder decay_score < 0.15                    │
│  Archive          ←── Historie, bei Bedarf geladen         │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│  Task State Memory  ←── Über Neustarts hinweg persistent (Schlüssel!)│
│  - Aktuelle Aufgabe / nächste Schritte / Fortschritt / Ausgaben│
├──────────────────────────────────────────────────────────────┤
│  Injektions-Engine  ←── Strategie A/B/C/D/E bestimmt Abruf │
│  Selbst-Introspektion ←── Jede Antwort prüft Kontext       │
│  Auto-Trigger        ←── Alle 10 Runden (konfigurierbar)    │
└──────────────────────────────────────────────────────────────┘
```

---

## 📦 Aufgabenstatus-Gedächtnis (Wertvollste Funktion)

Selbst nach Neustart, Stromausfall oder Sitzungswechsel setzt Context-Hawk genau dort fort, wo es aufgehört hat.

```json
// memory/.hawk/task_state.jsonl
{
  "task_id": "task_20260329_001",
  "description": "API-Dokumentation abschließen",
  "status": "in_progress",
  "progress": 65,
  "next_steps": ["Architekturvorlage überprüfen", "Benutzer Bericht erstatten"],
  "outputs": ["SKILL.md", "constitution.md"],
  "constraints": ["Abdeckung muss 98% erreichen", "APIs müssen versioniert sein"],
  "resumed_count": 3
}
```

```bash
hawk task "Dokumentation abschließen"  # Aufgabe erstellen
hawk task --step 1 done             # Schritt als erledigt markieren
hawk resume                           # Nach Neustart fortsetzen ← KERN!
```

---

## 🧠 Strukturiertes Gedächtnis

```json
{
  "id": "mem_20260329_001",
  "type": "task|knowledge|conversation|document|preference|decision",
  "content": "Vollständiger Originalinhalt",
  "summary": "Einzeilige Zusammenfassung",
  "importance": 0.85,
  "tier": "working|short|long|archive",
  "created_at": "2026-03-29T00:00:00+08:00",
  "access_count": 3,
  "decay_score": 0.92
}
```

### Wichtigkeitsbewertung

| Bewertung | Typ | Aktion |
|-------|------|--------|
| 0.9-1.0 | Entscheidungen/Regeln/Fehler | Permanent, langsamster Abfall |
| 0.7-0.9 | Aufgaben/Präferenzen/Wissen | Langzeitgedächtnis |
| 0.4-0.7 | Dialog/Diskussion | Kurzzeit, Abfall zu Archiv |
| 0.0-0.4 | Chat/Begrüßungen | **Verwerfen, niemals speichern** |

---

## 🎯 5 Kontextinjektionsstrategien

| Strategie | Auslöser | Einsparung |
|----------|---------|-----------|
| **A: Hohe Wichtigkeit** | `Wichtigkeit ≥ 0.7` | 60-70% |
| **B: Aufgabenbezogen** | Scope-Treffer | 30-40% ← Standard |
| **C: Aktuell** | letzte 10 Runden | 50% |
| **D: Top5 Abruf** | Top 5 `access_count` | 70% |
| **E: Voll** | kein Filter | 100% |

---

## 🗜️ 5 Kompressionsstrategien

`summarize` · `extract` · `delete` · `promote` · `archive`

---

## 🔔 4-stufiges Alarm-System

| Stufe | Schwellenwert | Aktion |
|-------|---------|--------|
| ✅ Normal | < 60% | Still |
| 🟡 Beobachten | 60-79% | Kompression vorschlagen |
| 🔴 Kritisch | 80-94% | Auto-Schreiben pausieren, Vorschlag erzwingen |
| 🚨 Gefahr | ≥ 95% | Schreiben blockieren, Kompression Pflicht |

---

## 🚀 Schnellstart

```bash
# LanceDB-Plugin installieren (empfohlen)
openclaw plugins install memory-lancedb-pro@beta

# Skill aktivieren
openclaw skills install ./context-hawk.skill

# Initialisieren
hawk init

# Kernbefehle
hawk task "Meine Aufgabe"    # Aufgabe erstellen
hawk resume             # Letzte Aufgabe fortsetzen ← SEHR WICHTIG
hawk status            # Kontextnutzung anzeigen
hawk compress          # Gedächtnis komprimieren
hawk strategy B        # Zum aufgabenbezogenen Modus wechseln
hawk introspect         # Selbst-Introspektionsbericht
```

---

## Auto-Trigger: Alle N Runden

Alle **10 Runden** (Standard, konfigurierbar) führt Context-Hawk automatisch aus:

1. Kontext-Wasserstand prüfen
2. Gedächtniswichtigkeit bewerten
3. Status an Benutzer melden
4. Kompression vorschlagen, wenn nötig

```bash
# Konfiguration (memory/.hawk/config.json)
{
  "auto_check_rounds": 10,          # alle N Runden prüfen
  "keep_recent": 5,                 # letzte N Runden bewahren
  "auto_compress_threshold": 70      # komprimieren wenn > 70%
}
```

---

## Dateistruktur

```
context-hawk/
├── SKILL.md
├── README.md
├── LICENSE
├── scripts/
│   └── hawk               # Python CLI-Werkzeug
└── references/
    ├── memory-system.md           # 4-Ebenen-Architektur
    ├── structured-memory.md      # Gedächtnisformat und Wichtigkeit
    ├── task-state.md           # Aufgabenstatus-Persistenz
    ├── injection-strategies.md  # 5 Injektionsstrategien
    ├── compression-strategies.md # 5 Kompressionsstrategien
    ├── alerting.md             # Alarmsystem
    ├── self-introspection.md   # Selbst-Introspektion
    ├── lancedb-integration.md  # LanceDB-Integration
    └── cli.md                  # CLI-Referenz
```

---

## Technische Daten

- **Persistenz**: JSONL lokale Dateien, keine Datenbank erforderlich
- **Vektorsuche**: LanceDB (optional), automatisches Fallback auf Dateien
- **Cross-Agent**: Universell, keine Geschäftslogik, funktioniert mit jedem KI-Agenten
- **Null-Konfiguration**: Sofort einsatzbereit mit intelligenten Standardwerten
- **Erweiterbar**: Benutzerdefinierte Injektionsstrategien, Kompressionsrichtlinien, Bewertungsregeln

---

## Lizenz

MIT — frei verwendbar, änderbar und verteilbar.


path: hawk/__init__.py
content: """
hawk — context-hawk core modules

Pure Python memory package:
- MemoryManager: 四层记忆 + Weibull衰减
- ContextCompressor: 上下文压缩
- Config: 配置管理
- SelfImproving: 自我反思学习
- VectorRetriever: 向量检索
- MarkdownImporter: Markdown导入
- Extractor: LLM记忆提取（支持keyword/llm模式）
- Governance: 治理指标
- HawkContext: LLM wrapper with autoCapture + autoRecall
"""

from .memory import MemoryManager
from .compressor import ContextCompressor
from .config import Config
from .self_improving import SelfImproving
from .vector_retriever import VectorRetriever, RetrievedChunk
from .markdown_importer import MarkdownImporter
from .governance import Governance
from .extractor import extract_memories
from .wrapper import HawkContext

__all__ = [
    "MemoryManager",
    "ContextCompressor",
    "Config",
    "SelfImproving",
    "VectorRetriever",
    "RetrievedChunk",
    "MarkdownImporter",
    "Governance",
    "extract_memories",
    "HawkContext",
]


path: scripts/install.sh
content: #!/bin/bash
# context-hawk 一键安装脚本
set -e

echo "Installing context-hawk..."

# 1. 检测 Python 版本
PYTHON=$(command -v python3.12 || command -v python3 || command -v python)
echo "Using Python: $PYTHON"

# 2. 安装核心依赖
$PYTHON -m pip install lancedb openai -q

# 3. 验证安装
$PYTHON -c "from hawk.memory import MemoryManager; print('hawk installed OK')"

# 4. 自动导入已有记忆（如有）
if [ -d "$HOME/.openclaw/memory" ]; then
    echo "发现记忆文件，自动导入..."
    $PYTHON -m hawk.markdown_importer --memory-dir "$HOME/.openclaw/memory" 2>/dev/null || true
fi

echo "context-hawk 安装完成！"
echo ""
echo "使用方式："
echo "  python3.12 -c \"from hawk.memory import MemoryManager; print('OK')\""


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)