diff --git a/docs/concepts/delegate-architecture.md b/docs/concepts/delegate-architecture.md index b9259128ec7..ae26a46bdd6 100644 --- a/docs/concepts/delegate-architecture.md +++ b/docs/concepts/delegate-architecture.md @@ -70,11 +70,15 @@ The delegate operates **autonomously** on a schedule, executing standing orders This tier combines Tier 2 permissions with [Cron Jobs](/automation/cron-jobs) and [Standing Orders](/automation/standing-orders). -> **Security warning**: Tier 3 requires careful configuration of hard blocks — actions the agent must never take regardless of instruction. Complete the prerequisites below before granting any identity provider permissions. + +Tier 3 requires careful configuration of hard blocks: actions the agent must never take regardless of instruction. Complete the prerequisites below before granting any identity provider permissions. + ## Prerequisites: isolation and hardening -> **Do this first.** Before you grant any credentials or identity provider access, lock down the delegate's boundaries. The steps in this section define what the agent **cannot** do — establish these constraints before giving it the ability to do anything. + +**Do this first.** Before you grant any credentials or identity provider access, lock down the delegate's boundaries. The steps in this section define what the agent **cannot** do. Establish these constraints before giving it the ability to do anything. + ### Hard blocks (non-negotiable) @@ -180,7 +184,9 @@ New-ApplicationAccessPolicy ` -AccessRight RestrictAccess ``` -> **Security warning**: without an application access policy, `Mail.Read` application permission grants access to **every mailbox in the tenant**. Always create the access policy before the application reads any mail. Test by confirming the app returns `403` for mailboxes outside the security group. + +Without an application access policy, `Mail.Read` application permission grants access to **every mailbox in the tenant**. Always create the access policy before the application reads any mail. Test by confirming the app returns `403` for mailboxes outside the security group. + #### Google Workspace @@ -196,7 +202,9 @@ https://www.googleapis.com/auth/calendar # Tier 2 The service account impersonates the delegate user (not the principal), preserving the "on behalf of" model. -> **Security warning**: domain-wide delegation allows the service account to impersonate **any user in the entire domain**. Restrict the scopes to the minimum required, and limit the service account's client ID to only the scopes listed above in the Admin Console (Security > API controls > Domain-wide delegation). A leaked service account key with broad scopes grants full access to every mailbox and calendar in the organization. Rotate keys on a schedule and monitor the Admin Console audit log for unexpected impersonation events. + +Domain-wide delegation allows the service account to impersonate **any user in the entire domain**. Restrict the scopes to the minimum required, and limit the service account's client ID to only the scopes listed above in the Admin Console (Security > API controls > Domain-wide delegation). A leaked service account key with broad scopes grants full access to every mailbox and calendar in the organization. Rotate keys on a schedule and monitor the Admin Console audit log for unexpected impersonation events. + ### 3. Bind the delegate to channels diff --git a/docs/concepts/memory.md b/docs/concepts/memory.md index d2c55583845..b02d8f1bdce 100644 --- a/docs/concepts/memory.md +++ b/docs/concepts/memory.md @@ -7,18 +7,18 @@ read_when: --- OpenClaw remembers things by writing **plain Markdown files** in your agent's -workspace. The model only "remembers" what gets saved to disk -- there is no +workspace. The model only "remembers" what gets saved to disk — there is no hidden state. ## How it works Your agent has three memory-related files: -- **`MEMORY.md`** -- long-term memory. Durable facts, preferences, and +- **`MEMORY.md`** — long-term memory. Durable facts, preferences, and decisions. Loaded at the start of every DM session. -- **`memory/YYYY-MM-DD.md`** -- daily notes. Running context and observations. +- **`memory/YYYY-MM-DD.md`** — daily notes. Running context and observations. Today and yesterday's notes are loaded automatically. -- **`DREAMS.md`** (optional) -- Dream Diary and dreaming sweep +- **`DREAMS.md`** (optional) — Dream Diary and dreaming sweep summaries for human review, including grounded historical backfill entries. These files live in the agent workspace (default `~/.openclaw/workspace`). @@ -32,9 +32,9 @@ prefer TypeScript." It will write it to the appropriate file. The agent has two tools for working with memory: -- **`memory_search`** -- finds relevant notes using semantic search, even when +- **`memory_search`** — finds relevant notes using semantic search, even when the wording differs from the original. -- **`memory_get`** -- reads a specific memory file or line range. +- **`memory_get`** — reads a specific memory file or line range. Both tools are provided by the active memory plugin (default: `memory-core`). @@ -61,7 +61,7 @@ See [Memory Wiki](/plugins/memory-wiki). ## Memory search When an embedding provider is configured, `memory_search` uses **hybrid -search** -- combining vector similarity (semantic meaning) with keyword matching +search** — combining vector similarity (semantic meaning) with keyword matching (exact terms like IDs and code symbols). This works out of the box once you have an API key for any supported provider. @@ -104,7 +104,7 @@ dashboards, bridge mode, and Obsidian-friendly workflows. Before [compaction](/concepts/compaction) summarizes your conversation, OpenClaw runs a silent turn that reminds the agent to save important context to memory -files. This is on by default -- you do not need to configure anything. +files. This is on by default — you do not need to configure anything. The memory flush prevents context loss during compaction. If your agent has @@ -176,16 +176,14 @@ openclaw memory index --force # Rebuild the index ## Further reading -- [Builtin Memory Engine](/concepts/memory-builtin) -- default SQLite backend -- [QMD Memory Engine](/concepts/memory-qmd) -- advanced local-first sidecar -- [Honcho Memory](/concepts/memory-honcho) -- AI-native cross-session memory -- [Memory Wiki](/plugins/memory-wiki) -- compiled knowledge vault and wiki-native tools -- [Memory Search](/concepts/memory-search) -- search pipeline, providers, and - tuning -- [Dreaming](/concepts/dreaming) -- background promotion - from short-term recall to long-term memory -- [Memory configuration reference](/reference/memory-config) -- all config knobs -- [Compaction](/concepts/compaction) -- how compaction interacts with memory +- [Builtin memory engine](/concepts/memory-builtin): default SQLite backend. +- [QMD memory engine](/concepts/memory-qmd): advanced local-first sidecar. +- [Honcho memory](/concepts/memory-honcho): AI-native cross-session memory. +- [Memory Wiki](/plugins/memory-wiki): compiled knowledge vault and wiki-native tools. +- [Memory search](/concepts/memory-search): search pipeline, providers, and tuning. +- [Dreaming](/concepts/dreaming): background promotion from short-term recall to long-term memory. +- [Memory configuration reference](/reference/memory-config): all config knobs. +- [Compaction](/concepts/compaction): how compaction interacts with memory. ## Related diff --git a/docs/concepts/messages.md b/docs/concepts/messages.md index 8aac5a0cf4b..98fa9e73589 100644 --- a/docs/concepts/messages.md +++ b/docs/concepts/messages.md @@ -7,8 +7,7 @@ read_when: title: "Messages" --- -This page ties together how OpenClaw handles inbound messages, sessions, queueing, -streaming, and reasoning visibility. +OpenClaw handles inbound messages through a pipeline of session resolution, queueing, streaming, tool execution, and reasoning visibility. This page maps the path from inbound message to reply. ## Message flow (high level) diff --git a/docs/concepts/system-prompt.md b/docs/concepts/system-prompt.md index 660632f82b9..5c9acd52027 100644 --- a/docs/concepts/system-prompt.md +++ b/docs/concepts/system-prompt.md @@ -116,12 +116,9 @@ heartbeats are disabled for the default agent or files concise — especially `MEMORY.md`, which can grow over time and lead to unexpectedly high context usage and more frequent compaction. -> **Note:** `memory/*.md` daily files are **not** part of the normal bootstrap -> Project Context. On ordinary turns they are accessed on demand via the -> `memory_search` and `memory_get` tools, so they do not count against the -> context window unless the model explicitly reads them. Bare `/new` and -> `/reset` turns are the exception: the runtime can prepend recent daily memory -> as a one-shot startup-context block for that first turn. + +`memory/*.md` daily files are **not** part of the normal bootstrap Project Context. On ordinary turns they are accessed on demand via the `memory_search` and `memory_get` tools, so they do not count against the context window unless the model explicitly reads them. Bare `/new` and `/reset` turns are the exception: the runtime can prepend recent daily memory as a one-shot startup-context block for that first turn. + Large files are truncated with a marker. The max per-file size is controlled by `agents.defaults.bootstrapMaxChars` (default: 12000). Total injected bootstrap