diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index 258b9e13f6b..466000477f1 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -283,6 +283,38 @@ "source": "Memory Wiki", "target": "Memory Wiki" }, + { + "source": "Memory overview", + "target": "记忆概览" + }, + { + "source": "Active memory", + "target": "主动记忆" + }, + { + "source": "Commitments", + "target": "跟进承诺" + }, + { + "source": "Inferred Commitments", + "target": "推断式跟进承诺" + }, + { + "source": "Inferred commitments", + "target": "推断式跟进承诺" + }, + { + "source": "Heartbeat", + "target": "Heartbeat" + }, + { + "source": "Scheduled tasks", + "target": "定时任务" + }, + { + "source": "Configuration reference", + "target": "配置参考" + }, { "source": "wiki", "target": "wiki" diff --git a/docs/automation/index.md b/docs/automation/index.md index 7c4c6306754..613e951836a 100644 --- a/docs/automation/index.md +++ b/docs/automation/index.md @@ -2,12 +2,14 @@ summary: "Overview of automation mechanisms: tasks, cron, hooks, standing orders, and Task Flow" read_when: - Deciding how to automate work with OpenClaw - - Choosing between heartbeat, cron, hooks, and standing orders + - Choosing between heartbeat, cron, commitments, hooks, and standing orders - Looking for the right automation entry point title: "Automation & tasks" --- -OpenClaw runs work in the background through tasks, scheduled jobs, event hooks, and standing instructions. This page helps you choose the right mechanism and understand how they fit together. +OpenClaw runs work in the background through tasks, scheduled jobs, inferred +commitments, event hooks, and standing instructions. This page helps you choose +the right mechanism and understand how they fit together. ## Quick decision guide @@ -18,6 +20,7 @@ flowchart TD START --> Q3{Orchestrate multi-step flows?} START --> Q4{React to lifecycle events?} START --> Q5{Give the agent persistent instructions?} + START --> Q6{Remember a natural follow-up?} Q1 -->|Yes| Q1a{Exact timing or flexible?} Q1a -->|Exact| CRON["Scheduled Tasks (Cron)"] @@ -27,6 +30,7 @@ flowchart TD Q3 -->|Yes| FLOW[Task Flow] Q4 -->|Yes| HOOKS[Hooks] Q5 -->|Yes| SO[Standing Orders] + Q6 -->|Yes| COMMITMENTS[Inferred Commitments] ``` | Use case | Recommended | Why | @@ -36,6 +40,8 @@ flowchart TD | Run weekly deep analysis | Scheduled Tasks (Cron) | Standalone task, can use different model | | Check inbox every 30 min | Heartbeat | Batches with other checks, context-aware | | Monitor calendar for upcoming events | Heartbeat | Natural fit for periodic awareness | +| Check in after a mentioned interview | Inferred Commitments | Memory-like follow-up, no exact reminder request | +| Gentle care check-in after user context | Inferred Commitments | Scoped to the same agent and channel | | Inspect status of a subagent or ACP run | Background Tasks | Tasks ledger tracks all detached work | | Audit what ran and when | Background Tasks | `openclaw tasks list` and `openclaw tasks audit` | | Multi-step research then summarize | Task Flow | Durable orchestration with revision tracking | @@ -69,6 +75,15 @@ The background task ledger tracks all detached work: ACP runs, subagent spawns, See [Background Tasks](/automation/tasks). +### Inferred commitments + +Commitments are opt-in, short-lived follow-up memories. OpenClaw infers them +from normal conversations, scopes them to the same agent and channel, and +delivers due check-ins through heartbeat. Exact user-requested reminders still +belong to cron. + +See [Inferred Commitments](/concepts/commitments). + ### Task Flow Task Flow is the flow orchestration substrate above background tasks. It manages durable multi-step flows with managed and mirrored sync modes, revision tracking, and `openclaw tasks flow list|show|cancel` for inspection. @@ -109,6 +124,7 @@ See [Heartbeat](/gateway/heartbeat). ## Related - [Scheduled Tasks](/automation/cron-jobs) — precise scheduling and one-shot reminders +- [Inferred Commitments](/concepts/commitments) — memory-like follow-up check-ins - [Background Tasks](/automation/tasks) — task ledger for all detached work - [Task Flow](/automation/taskflow) — durable multi-step flow orchestration - [Hooks](/automation/hooks) — event-driven lifecycle scripts diff --git a/docs/cli/commitments.md b/docs/cli/commitments.md new file mode 100644 index 00000000000..9d04be64eeb --- /dev/null +++ b/docs/cli/commitments.md @@ -0,0 +1,90 @@ +--- +summary: "CLI reference for `openclaw commitments` (inspect and dismiss inferred follow-ups)" +read_when: + - You want to inspect inferred follow-up commitments + - You want to dismiss pending check-ins + - You are auditing what heartbeat may deliver +title: "`openclaw commitments`" +--- + +List and manage inferred follow-up commitments. + +Commitments are opt-in, short-lived follow-up memories created from +conversation context. See [Inferred commitments](/concepts/commitments) for the +conceptual guide. + +With no subcommand, `openclaw commitments` lists pending commitments. + +## Usage + +```bash +openclaw commitments [--all] [--agent ] [--status ] [--json] +openclaw commitments list [--all] [--agent ] [--status ] [--json] +openclaw commitments dismiss [--json] +``` + +## Options + +- `--all`: show all statuses instead of only pending commitments. +- `--agent `: filter to one agent id. +- `--status `: filter by status. Values: `pending`, `sent`, + `dismissed`, `snoozed`, or `expired`. +- `--json`: output machine-readable JSON. + +## Examples + +List pending commitments: + +```bash +openclaw commitments +``` + +List every stored commitment: + +```bash +openclaw commitments --all +``` + +Filter to one agent: + +```bash +openclaw commitments --agent main +``` + +Find snoozed commitments: + +```bash +openclaw commitments --status snoozed +``` + +Dismiss one or more commitments: + +```bash +openclaw commitments dismiss cm_abc123 cm_def456 +``` + +Export as JSON: + +```bash +openclaw commitments --all --json +``` + +## Output + +Text output includes: + +- commitment id +- status +- kind +- earliest due time +- scope +- suggested check-in text + +JSON output also includes the commitment store path and full stored records. + +## Related + +- [Inferred commitments](/concepts/commitments) +- [Memory overview](/concepts/memory) +- [Heartbeat](/gateway/heartbeat) +- [Scheduled tasks](/automation/cron-jobs) diff --git a/docs/cli/index.md b/docs/cli/index.md index ca034ccbad9..3ff71cc2ac3 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -20,7 +20,7 @@ apply across the CLI. | Messaging and agents | [`message`](/cli/message) · [`agent`](/cli/agent) · [`agents`](/cli/agents) · [`acp`](/cli/acp) · [`mcp`](/cli/mcp) | | Health and sessions | [`status`](/cli/status) · [`health`](/cli/health) · [`sessions`](/cli/sessions) | | Gateway and logs | [`gateway`](/cli/gateway) · [`logs`](/cli/logs) · [`system`](/cli/system) | -| Models and inference | [`models`](/cli/models) · [`infer`](/cli/infer) · `capability` (alias for [`infer`](/cli/infer)) · [`memory`](/cli/memory) · [`wiki`](/cli/wiki) | +| Models and inference | [`models`](/cli/models) · [`infer`](/cli/infer) · `capability` (alias for [`infer`](/cli/infer)) · [`memory`](/cli/memory) · [`commitments`](/cli/commitments) · [`wiki`](/cli/wiki) | | Network and nodes | [`directory`](/cli/directory) · [`nodes`](/cli/nodes) · [`devices`](/cli/devices) · [`node`](/cli/node) | | Runtime and sandbox | [`approvals`](/cli/approvals) · `exec-policy` (see [`approvals`](/cli/approvals)) · [`sandbox`](/cli/sandbox) · [`tui`](/cli/tui) · `chat`/`terminal` (aliases for [`tui --local`](/cli/tui)) · [`browser`](/cli/browser) | | Automation | [`cron`](/cli/cron) · [`tasks`](/cli/tasks) · [`hooks`](/cli/hooks) · [`webhooks`](/cli/webhooks) | @@ -121,6 +121,9 @@ openclaw [--dev] [--profile ] status index search + commitments + list + dismiss wiki status doctor diff --git a/docs/concepts/commitments.md b/docs/concepts/commitments.md new file mode 100644 index 00000000000..d04d908dc5e --- /dev/null +++ b/docs/concepts/commitments.md @@ -0,0 +1,146 @@ +--- +summary: "Inferred follow-up memory for check-ins that are not exact reminders" +title: "Inferred commitments" +sidebarTitle: "Commitments" +read_when: + - You want OpenClaw to remember natural follow-ups + - You want to understand how inferred check-ins differ from reminders + - You want to review or dismiss follow-up commitments +--- + +Commitments are short-lived follow-up memories. When enabled, OpenClaw can +notice that a conversation created a future check-in opportunity and remember +to bring it back later. + +Examples: + +- You mention an interview tomorrow. OpenClaw may check in afterward. +- You say you are exhausted. OpenClaw may ask later whether you slept. +- The agent says it will follow up after something changes. OpenClaw may track + that open loop. + +Commitments are not durable facts like `MEMORY.md`, and they are not exact +reminders. They sit between memory and automation: OpenClaw remembers a +conversation-bound obligation, then heartbeat delivers it when it is due. + +## Enable commitments + +Commitments are off by default. Enable them in config: + +```bash +openclaw config set commitments.enabled true +openclaw config set commitments.maxPerDay 3 +``` + +Equivalent `openclaw.json`: + +```json +{ + "commitments": { + "enabled": true, + "maxPerDay": 3 + } +} +``` + +`commitments.maxPerDay` limits how many inferred follow-ups can be delivered +per agent session in a rolling day. The default is `3`. + +## How it works + +After an agent reply, OpenClaw may run a hidden background extraction pass in a +separate context. That pass looks only for inferred follow-up commitments. It +does not write into the visible conversation and it does not ask the main agent +to reason about the extraction. + +When it finds a high-confidence candidate, OpenClaw stores a commitment with: + +- the agent id +- the session key +- the original channel and delivery target +- a due window +- a short suggested check-in +- enough source context for heartbeat to decide whether to send it + +Delivery happens through heartbeat. When a commitment becomes due, heartbeat +adds the commitment to the heartbeat turn for the same agent and channel scope. +The model can send one natural check-in or reply `HEARTBEAT_OK` to dismiss it. + +OpenClaw never delivers an inferred commitment immediately after writing it. +The due time is clamped to at least one heartbeat interval after the commitment +is created, so the follow-up cannot echo back in the same moment it was +inferred. + +## Scope + +Commitments are scoped to the exact agent and channel context where they were +created. A follow-up inferred while talking to one agent in Discord is not +delivered by another agent, another channel, or an unrelated session. + +This scope is part of the feature. Natural check-ins should feel like the same +conversation continuing, not like a global reminder system. + +## Commitments vs reminders + +| Need | Use | +| ----------------------------------------------- | ---------------------------------------- | +| "Remind me at 3 PM" | [Scheduled tasks](/automation/cron-jobs) | +| "Ping me in 20 minutes" | [Scheduled tasks](/automation/cron-jobs) | +| "Run this report every weekday" | [Scheduled tasks](/automation/cron-jobs) | +| "I have an interview tomorrow" | Commitments | +| "I was up all night" | Commitments | +| "Follow up if I do not answer this open thread" | Commitments | + +Exact user requests already belong to the scheduler path. Commitments are only +for inferred follow-ups: the moments where the user did not ask for a reminder, +but the conversation clearly created a useful future check-in. + +## Manage commitments + +Use the CLI to inspect and clear stored commitments: + +```bash +openclaw commitments +openclaw commitments --all +openclaw commitments --agent main +openclaw commitments --status snoozed +openclaw commitments dismiss cm_abc123 +``` + +See [`openclaw commitments`](/cli/commitments) for the command reference. + +## Privacy and cost + +Commitment extraction uses an LLM pass, so enabling it adds background model +usage after eligible turns. The pass is hidden from the user-visible +conversation, but it can read the recent exchange needed to decide whether a +follow-up exists. + +Stored commitments are local OpenClaw state. They are operational memory, not +long-term memory. Disable the feature with: + +```bash +openclaw config set commitments.enabled false +``` + +## Troubleshooting + +If expected follow-ups are not appearing: + +- Confirm `commitments.enabled` is `true`. +- Check `openclaw commitments --all` for pending, dismissed, snoozed, or expired + records. +- Make sure heartbeat is running for the agent. +- Check whether `commitments.maxPerDay` has already been reached for that + agent session. +- Remember that exact reminders are skipped by commitment extraction and should + appear under [scheduled tasks](/automation/cron-jobs) instead. + +## Related + +- [Memory overview](/concepts/memory) +- [Active memory](/concepts/active-memory) +- [Heartbeat](/gateway/heartbeat) +- [Scheduled tasks](/automation/cron-jobs) +- [`openclaw commitments`](/cli/commitments) +- [Configuration reference](/gateway/configuration-reference#commitments) diff --git a/docs/concepts/memory.md b/docs/concepts/memory.md index c7a7079a497..276be53c8cf 100644 --- a/docs/concepts/memory.md +++ b/docs/concepts/memory.md @@ -28,6 +28,17 @@ If you want your agent to remember something, just ask it: "Remember that I prefer TypeScript." It will write it to the appropriate file. +## Inferred commitments + +Some future follow-ups are not durable facts. If you mention an interview +tomorrow, the useful memory may be "check in after the interview," not "store +this forever in `MEMORY.md`." + +[Commitments](/concepts/commitments) are opt-in, short-lived follow-up memories +for that case. OpenClaw infers them in a hidden background pass, scopes them to +the same agent and channel, and delivers due check-ins through heartbeat. +Explicit reminders still use [scheduled tasks](/automation/cron-jobs). + ## Memory tools The agent has two tools for working with memory: @@ -217,3 +228,4 @@ openclaw memory index --force # Rebuild the index - [Builtin memory engine](/concepts/memory-builtin) - [Honcho memory](/concepts/memory-honcho) - [Memory LanceDB](/plugins/memory-lancedb) +- [Commitments](/concepts/commitments) diff --git a/docs/docs.json b/docs/docs.json index 76f372d280f..2a2fa35c0a2 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1142,6 +1142,7 @@ "concepts/memory-honcho", "concepts/memory-search", "concepts/active-memory", + "concepts/commitments", "concepts/dreaming" ] }, @@ -1590,6 +1591,7 @@ "cli/hooks", "cli/infer", "cli/memory", + "cli/commitments", "cli/message", "cli/models", "cli/sessions",