OpenClaw Hooks Bridge — HTTP API Client for hawk-memory
License: Apache-2.0 Node.js Version TypeScript
hawk-SecondBrain is the bridge layer between OpenClaw agent hooks and hawk-memory's HTTP API. It transforms local hook handlers into API calls, enabling distributed memory across multiple agents and sessions.
📖 This document is also available in 简体中文.
hawk-SecondBrain implements the OpenClaw hook interface (capture, recall, dream, and more) by forwarding all operations to the hawk-memory HTTP API server. This enables:
- Multi-agent memory sharing: All agents connect to a central hawk-memory server
- Persistence: Memory survives agent restarts and machine reboots
- Scalability: Decouple compute (hooks) from storage (hawk-memory)
- Distributed deployment: Run hawk-memory on a server, hooks on multiple clients
┌─────────────────────────────────────────────────────────────┐
│ OpenClaw Agent │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│ │ Capture │ │ Recall │ │ Dream │ │ Stats │ │
│ │ Hook │ │ Hook │ │ Hook │ │ Hook │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ │
└───────┼───────────────┼───────────────┼─────────────┼───────┘
│ │ │ │
└───────────────┴───────────────┴─────────────┘
│
▼ HTTP API (axios)
│
┌───────────────┐
│ hawk-memory │
│ :18368 │
│ │
│ LanceDB │
│ xinference │
│ Redis │
│ mflow │
└───────────────┘
| Component | Role |
|---|---|
| hawk-SecondBrain | OpenClaw hooks → HTTP API bridge (TypeScript) |
| hawk-memory | Core memory engine: capture, recall, embedding, storage (Go) |
| xinference | Local LLM/embedding inference (bge-m3, qwen2.5) |
| LanceDB | Vector database for semantic memory storage |
| Redis | Short-term cache and working memory |
| mflow | Procedural memory and task flow engine |
- Docker + Docker Compose OR Node.js 20+ + Go 1.21+
- 8GB RAM minimum (16GB recommended)
- Linux x86_64
One-command installation:
curl -sSL https://raw.githubusercontent.com/relunctance/hawk-SecondBrain/main/scripts/install-docker.sh | bashOr manually:
# Clone the repository git clone https://github.com/relunctance/hawk-SecondBrain.git cd hawk-SecondBrain # Run the installer chmod +x scripts/install-docker.sh ./scripts/install-docker.sh
After installation, verify with:
cd ~/.hawk docker compose up -d # Run smoke tests ./scripts/smoke-test.sh
For servers without Docker, use the bare-metal installer:
curl -sSL https://raw.githubusercontent.com/relunctance/hawk-SecondBrain/main/scripts/install-bare-metal.sh | bashManual setup:
# 1. Install dependencies apt install redis-server golang nodejs npm git # 2. Build hawk-memory git clone https://github.com/relunctance/hawk-memory.git ~/repos/hawk-memory cd ~/repos/hawk-memory make build-native # 3. Clone and build hawk-SecondBrain git clone https://github.com/relunctance/hawk-SecondBrain.git ~/repos/hawk-SecondBrain cd ~/repos/hawk-SecondBrain npm install && npm run build # 4. Start hawk-memory systemctl --user start hawk-memory
All API calls are made to the hawk-memory server (default: http://localhost:18368).
curl -X POST http://localhost:18368/v1/capture \ -H "Content-Type: application/json" \ -d '{ "text": "Learned that React hooks depend on call order", "agent_id": "my-agent", "memory_type": "working" }'
Response:
{
"id": "mem_abc123",
"text": "Learned that React hooks depend on call order",
"agent_id": "my-agent",
"created_at": "2026年05月04日T10:00:00Z",
"confidence": 0.95
}curl -X POST http://localhost:18368/v1/recall \ -H "Content-Type: application/json" \ -d '{ "query": "React hooks rules", "agent_id": "my-agent", "top_k": 5 }'
Response:
{
"memories": [
{
"id": "mem_abc123",
"text": "Learned that React hooks depend on call order",
"score": 0.94
}
],
"query": "React hooks rules",
"total": 1
}# List active working memory entries curl "http://localhost:18368/v1/wm/active?agent_id=my-agent" # Resume a task curl -X POST "http://localhost:18368/v1/wm/resume" \ -d '{"agent_id":"my-agent","task_id":"task_123"}' # Complete a task curl -X POST "http://localhost:18368/v1/wm/complete" \ -d '{"agent_id":"my-agent","task_id":"task_123"}'
# Record a belief curl -X POST http://localhost:18368/v1/belief \ -H "Content-Type: application/json" \ -d '{ "agent_id": "my-agent", "text": "I think TypeScript improves code quality" }' # Get belief timeline curl "http://localhost:18368/v1/belief/timeline?agent_id=my-agent"
# Get hygiene report curl "http://localhost:18368/v1/coach/report?agent_id=my-agent" # Run hygiene detection curl -X POST http://localhost:18368/v1/coach/detect \ -d '{"agent_id":"my-agent"}'
# Daily stats curl "http://localhost:18368/v1/stats/daily?agent_id=my-agent" # Weekly report (hawk-SecondBrain generates from daily snapshots)
For complete API documentation, see hawk-memory API docs.
| Variable | Default | Description |
|---|---|---|
HAWK_MEMORY_URL |
http://localhost:18368 |
hawk-memory server URL |
HAWK_MEMORY_API_KEY |
— | API key for authentication |
HAWK_AGENT_ID |
default |
Default agent ID |
LOG_LEVEL |
info |
Log level: debug, info, warn, error |
server: host: "0.0.0.0" port: 18368 storage: lancedb: path: "~/.hawk/data/hawk-memory/lancedb" xai: xinference_url: "http://localhost:9997" embedding_model: "bge-m3" embedding_dim: 1024 llm_model: "qwen2.5-7b-instruct" mflow: url: "http://localhost:8000" dual_write: true redis: url: "redis://localhost:6379"
hawk-SecondBrain/
├── src/
│ ├── client.ts # HawkMemoryClient HTTP wrapper
│ ├── config.ts # Configuration management
│ ├── types.ts # TypeScript type definitions
│ ├── hooks/ # Hook implementations
│ │ ├── capture/ # Capture hook
│ │ ├── recall/ # Recall hook
│ │ ├── dream/ # Dream/night consolidation hook
│ │ ├── stats.ts # Stats collection hook
│ │ ├── til/ # Today I Learned hook
│ │ ├── almost-lost/ # Memory decay detection
│ │ ├── branches/ # Memory branching
│ │ ├── causal/ # Causal memory
│ │ ├── coach/ # Memory hygiene coach
│ │ └── ...
│ ├── report/ # Report generation
│ │ └── weekly-generator.ts
│ ├── skills/ # Skills
│ │ └── daily-summary.ts
│ └── index.ts # Entry point
├── tests/ # Jest test suites
├── scripts/
│ ├── install-docker.sh # Docker installer
│ ├── install-bare-metal.sh # Bare metal installer
│ └── smoke-test.sh # Smoke test suite
├── config/
├── dist/ # Compiled JavaScript (generated)
└── package.json
# Clone git clone https://github.com/relunctance/hawk-SecondBrain.git cd hawk-SecondBrain # Install dependencies npm install # Build npm run build # Run tests npm test
# All tests npm test # Specific test file npx jest tests/hooks/capture.test.ts -v # With coverage npm test -- --coverage
Each hook follows the pattern:
// src/hooks/<feature>/handler.ts import { HawkMemoryClient } from '../../client'; export class FeatureHandler { constructor(private client: HawkMemoryClient) {} async execute(params: FeatureParams): Promise<FeatureResult> { // 1. Call hawk-memory API const result = await this.client.featureAPI(params); // 2. Transform response if needed // 3. Return structured result return result; } }
hawk-SecondBrain exposes 21 memory capabilities through the hawk-memory API:
| # | Feature | Description |
|---|---|---|
| 1 | Working Memory | Short-term task context with resume/complete |
| 2 | Deprecation | Mark outdated information as deprecated |
| 3 | Learning Memory | Extract and store lessons learned |
| 4 | Confidence Calibration | Track confidence signals over time |
| 5 | Memory Chronology | Maintain temporal ordering of events |
| 6 | Belief Timeline | Track beliefs and their evolution |
| 7 | TIL (Today I Learned) | Structured learning capture |
| 8 | Almost Lost | Detect decaying memories at risk of loss |
| 9 | Memory Branching | Create experimental memory branches |
| 10 | Task-Aware Recall | Context-sensitive memory retrieval |
| 11 | Self-Awareness | Track what the agent knows/doesn't know |
| 12 | Memory Prediction | Predict future memory needs |
| 13 | Memory Coach | Hygiene and memory health coaching |
| 14 | Causal Memory | Store cause-effect relationships |
| 15 | Active Memory | High-urgency, high-importance memories |
| 16 | Consensus Memory | Cross-agent shared knowledge |
| 17 | Counterfactual Memory | What-if scenario exploration |
| 18 | Metacognitive Monitor | Monitor memory access patterns |
| 19 | Memory Hygiene Score | Quantify memory ecosystem health |
| 20 | Strategic Memory | Long-term goal and plan storage |
| 21 | Implicit Knowledge | Tacit knowledge extraction |
services: hawk-memory: image: ghcr.io/relunctance/hawk-memory:v0.1.0 ports: - "18368:18368" volumes: - hawk-data:/data/hawk-memory xinference: image: xprobe/xinference:v0.16.0 ports: - "9997:9997" deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] hawk-secondbrain: build: . ports: - "3000:3000" environment: - HAWK_MEMORY_URL=http://hawk-memory:18368
Helm charts available at charts/hawk-secondbrain/.
# Check if service is running curl http://localhost:18368/health # Check logs journalctl --user -u hawk-memory -n 50 # Restart systemctl --user restart hawk-memory
# Wait for FTS index to build (usually 3-5 seconds after capture) sleep 5 curl -X POST http://localhost:18368/v1/recall -d '{"query":"your query","agent_id":"test"}'
# Check xinference status curl http://localhost:9997/v1/models # If empty, launch models via UI at http://localhost:8080 # or API: curl -X POST http://localhost:9997/v1/models \ -d '{"model_name":"bge-m3","model_type":"embedding"}'
Apache License 2.0 — see LICENSE for details.
- 中文文档 — 简体中文版
- hawk-memory — Core memory engine
- hawk-eval — Benchmark system
- hawk-sla — Project tracking
- OpenClaw — Agent framework