vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 13:20:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs: document inferred commitments

Browse Source
This commit is contained in:
Vignesh Natarajan
2026-04-29 14:28:04 -07:00
parent 21e2168b8f
commit d51af16fab
7 changed files with 304 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/.i18n/glossary.zh-CN.json
View File

@@ -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"

20
docs/automation/index.md
View File

@@ -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

90
docs/cli/commitments.md Normal file
View File

@@ -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 <id>] [--status <status>] [--json]
openclaw commitments list [--all] [--agent <id>] [--status <status>] [--json]
openclaw commitments dismiss <id...> [--json]
```
## Options
- `--all`: show all statuses instead of only pending commitments.
- `--agent <id>`: filter to one agent id.
- `--status <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)

5
docs/cli/index.md
View File

@@ -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 <name>] <command>
status
index
search
commitments
list
dismiss
wiki
status
doctor

146
docs/concepts/commitments.md Normal file
View File

@@ -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)

12
docs/concepts/memory.md
View File

@@ -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.
</Tip>
## 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)

2
docs/docs.json
View File

@@ -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",