Help your agent keep track of the conversations that matter

personal-hooks helps an OpenClaw agent keep track of the conversations that should not be dropped. Instead of treating every message as memory, it helps the agent distinguish between ordinary chat and topics that are worth following up on later.

When a user mentions something that should be continued later — a task, an ongoing situation, or something emotionally important — personal-hooks keeps hold of that thread so the agent can return to it naturally when the timing is right.

This repository contains the V1 continuity and follow-up skill for OpenClaw. V1 focuses on thread tracking, carryover, closure, suppression, and guardrails. More proactive companionship-style behavior belongs to later versions and is not part of the shipped V1 scope.

For reviewer-oriented project status and file map, see AUDIT.md.

V1 includes

• casual_chat / staged_memory / tracked_followup routing
• four event types:
  • parked_topic
  • watchful_state
  • delegated_task
  • sensitive_event
• incremental event_chain updates
• candidate -> incident -> hook flow
• /new carryover
• active hook / closure lifecycle
• sleep/rest suppress
• dedupe / cooldown / dispatch cap
• frontstage guard
• structured trace
• regression harness
• live QA runbook

V1 does not include

• companionship rhythm/nudge as a default capability
• user-configured idle chat frequency
• proactive chatting with no tracked continuity source
• Telegram delivery/network reliability fixes

Package layout

• SKILL.md: trigger rules and runtime boundary
• scripts/: runtime script and verification helpers
• docs/: call flow, harness usage, live QA, V2 blueprint
• examples/: sample config and sample report
• config.schema.json: public config schema
• LICENSE: package license

Quick install

This package is designed for users who already have an OpenClaw environment.

It is close to drop-in for an existing OpenClaw workspace, but it is not a fully standalone one-click app.

Recommended OpenClaw layout:

openclaw-workspace/
  skills/
    personal-hooks/

Copy install:

cp -R /path/to/personal-hooks /path/to/openclaw-workspace/skills/personal-hooks

Symlink install:

ln -s /path/to/personal-hooks /path/to/openclaw-workspace/skills/personal-hooks

Or use the helper script:

bash scripts/install_local.sh /path/to/openclaw-workspace/skills link

Quick start:

python3 /path/to/openclaw-workspace/skills/personal-hooks/scripts/personal_hooks.py init
python3 /path/to/openclaw-workspace/skills/personal-hooks/scripts/personal_hooks.py capability-state-show

Minimal verification:

python3 /path/to/openclaw-workspace/skills/personal-hooks/scripts/followup_skill_harness.py --absence-minutes 3

Browser/local-gateway first:

• the core skill works through the ordinary OpenClaw reply pipeline
• browser/local gateway usage is supported
• Telegram is not required for the core skill package

Installation

Copy or symlink this folder into an OpenClaw workspace skill directory, then point runtime state env vars at a writable data directory.

Typical layout:

workspace/
  skills/
    personal-hooks/
      SKILL.md
      scripts/
      docs/

Runtime script:

python3 /path/to/personal-hooks/scripts/personal_hooks.py init

Optional env overrides:

• PERSONAL_HOOKS_DATA_DIR
• PERSONAL_HOOKS_MEMORY_DIR
• PERSONAL_HOOKS_SESSIONS_INDEX_PATH
• PERSONAL_HOOKS_JOBS_PATH
• PERSONAL_HOOKS_OPENCLAW_CONFIG_PATH
• PERSONAL_HOOKS_SETTINGS_PATH
• PERSONAL_HOOKS_EMBEDDER_ROOT
• PERSONAL_HOOKS_PRIMARY_SESSION_KEY
• PERSONAL_HOOKS_TARGET_TO

Browser / local gateway usage

The package is designed for OpenClaw’s ordinary reply pipeline.

• build_runtime_context() builds continuity context for web/browser and Telegram paths that share the same ordinary reply chain.
• personal_hooks.py owns staged/tracked state and hook lifecycle.
• scripts/web_live_runner.mjs is an optional near-live browser runner for local gateway testing. It is not a Telegram network validator, and it requires PERSONAL_HOOKS_OPENCLAW_ROOT so the release package never hard-binds to a live workspace.

See docs/install.md for a browser/local-gateway-first installation walkthrough.

Settings you will most likely change

The most common V1 settings live in:

• examples/settings.sample.json
• config.schema.json

Minimum usable V1 settings are already reflected in the sample:

• followup.enabled
• sleep_rest_suppress.enabled
• sleep_rest_suppress.duration_hours
• carryover.enabled
• carryover.max_turns
• carryover.top_summary_only
• dispatch.cooldown_minutes
• dispatch.cap
• closure.auto_close_on_user_reply

Important:

• experimental.rhythm_nudge.enabled defaults to false
• public V1 does not depend on rhythm/nudge
• you can keep the sample settings as-is for a minimal V1 setup

Testing

Minimal reproducible verification:

python3 /path/to/personal-hooks/scripts/followup_skill_harness.py --absence-minutes 3

See docs/harness.md for sandbox override details.

Known limits

• Telegram polling/send reliability is out of scope for V1.
• V1 does not ship companionship rhythm/nudge as a public default.
• Frontstage warmth/personality still depends on the host agent’s own soul/persona/model.
• Carryover is intentionally short; it is not full transcript replay.

Future install path

This repository may later grow toward a ClawHub/install-flow friendly package shape, but the current release is intentionally optimized for manual local installation in an existing OpenClaw environment.