Hooks & Tools

The @keyoku/openclaw plugin registers five hook handlers and seven LLM-callable tools. This page documents every hook, its priority, and what it does — plus the full tool reference.

Hooks

The plugin uses two OpenClaw lifecycle hooks: before_prompt_build for injection and stashing, and agent_end for capture and dedup recording. Priority determines execution order (lower runs first).

before_prompt_build · priority -10

Capture stash

Stashes the user's current message for later pairing.

No API call is made at this point — the plugin waits for the agent to respond so it can capture the full user-agent exchange.

before_prompt_build · priority 0

Auto-recall

Searches Keyoku for relevant memories using the user's message as the query.

Injects up to topK results into the prompt as a <your-memories> block. The LLM sees them as natural context.

before_prompt_build · priority 0

Heartbeat path

Detects the HEARTBEAT marker in the incoming prompt.

Calls the engine's /api/v1/heartbeat/check and /api/v1/heartbeat/context endpoints. If should_act is true, injects a <heartbeat-signals> block with urgency tier, action brief, and recommended response.

agent_end · priority 0

Incremental capture

Pairs the stashed user message with the agent's response into a combined exchange.

Sends the pair to /api/v1/remember for structured memory extraction. One atomic capture per turn — the engine handles deduplication.

agent_end · priority 10

Heartbeat record

Logs the response fingerprint after a heartbeat-triggered response.

Calls recordHeartbeatMessage() to enable deduplication — the same signal will not trigger an identical response within the cooldown window.

Hook execution order

On a normal user message, hooks fire in this sequence:

1. before_prompt_build (priority -10) → Stash user message
2. before_prompt_build (priority  0)  → Search memories → inject <your-memories>
3. LLM generates response
4. agent_end            (priority  0)  → Pair stashed message + response → /remember

On a heartbeat prompt, the sequence changes:

1. before_prompt_build (priority  0)  → Detect HEARTBEAT marker
2. before_prompt_build (priority  0)  → Call /heartbeat/check → inject <heartbeat-signals>
3. LLM generates heartbeat response
4. agent_end            (priority 10)  → Record heartbeat fingerprint for dedup

Tools

Seven tools are registered with OpenClaw and made available to the LLM. Auto-capture handles most memory operations — these tools give the LLM direct control when it needs it.

memory_search

Semantic search over stored memories.

Uses three-tier retrieval: LRU cache, HNSW approximate nearest neighbor, and SQLite full-text fallback. Parameters: query (string), maxResults (number, optional), minScore (number, optional).

memory_get

Fetch a specific memory by its ID or by keyword.

Returns the full memory object including content, type, importance, confidence, timestamps, and decay state. Parameters: path (string), from (number, optional), lines (number, optional).

memory_store

Explicitly save information as a memory.

Use when the LLM decides something is important enough to remember without waiting for auto-capture. The engine runs deduplication on ingest. Parameters: text (string).

memory_forget

Delete a memory by its ID.

Permanently removes the memory from storage. Use when the user explicitly asks to forget something or when correcting incorrect information. Parameters: memory_id (string).

memory_stats

View memory statistics for an entity.

Returns total memory count, breakdown by type, health metrics (decay distribution, conflict count), and storage size. Parameters: none.

schedule_create

Create a cron-based reminder or recurring task.

Stores a memory with a cron expression that the heartbeat scan checks on each tick. When the cron fires, the scheduled signal is emitted. Parameters: content (string), cron_tag (string).

schedule_list

List all active scheduled reminders for an entity.

Returns each schedule's content, cron expression, next fire time, and creation timestamp. Parameters: none.

SKILL.md

The setup wizard installs a SKILL.md file that teaches the LLM how to use the memory system. This file is loaded into the LLM's system prompt by OpenClaw. It instructs the LLM to:

Use recalled memories naturally in conversation — never say "according to my records" or reference the memory system directly.
Follow the configured autonomy mode: observe (silent), suggest (surface to user), or act (execute automatically).
Never mention infrastructure details like Keyoku, the engine, or memory storage to the user.
Handle heartbeat signals gracefully — weave proactive insights into natural conversation flow.
Use explicit memory tools (memory_store, memory_forget) when the user asks to remember or forget something.
Respect memory confidence levels — high-confidence facts can be stated directly, low-confidence facts should be hedged.

The SKILL.md file is installed to your OpenClaw skills directory during installation (Step 9). You can customize it to adjust LLM behavior.

See Configuration to control which hooks are active (autoRecall, autoCapture, heartbeat), or Overview for the full plugin architecture.