diff --git a/docs/src/content/docs/reference/memory.md b/docs/src/content/docs/reference/memory.md
index 69d5291b00..f1d6f2ec27 100644
--- a/docs/src/content/docs/reference/memory.md
+++ b/docs/src/content/docs/reference/memory.md
@@ -5,15 +5,11 @@ sidebar:
   order: 1500
 ---
 
-Agentic workflows can maintain persistent memory through GitHub Issues/Discussions/files, **cache-memory** (GitHub Actions cache with 7-day retention), or **repo-memory** (Git branches with unlimited retention).
-
-This guide covers cache-memory and repo-memory configuration.
+Agentic workflows maintain persistent memory through **cache-memory** (GitHub Actions cache, 7-day retention) or **repo-memory** (Git branches, unlimited retention).
 
 ## Cache Memory
 
-Enables persistent file storage across workflow runs using GitHub Actions cache. When enabled, the compiler automatically sets up the cache directory, restore/save operations, and progressive fallback keys.
-
-Storage locations: `/tmp/gh-aw/cache-memory/` (default) or `/tmp/gh-aw/cache-memory-{id}/` (additional caches).
+Provides persistent file storage across workflow runs via GitHub Actions cache. The compiler automatically configures the cache directory, restore/save operations, and progressive fallback keys at `/tmp/gh-aw/cache-memory/` (default) or `/tmp/gh-aw/cache-memory-{id}/` (additional caches).
 
 ## Enabling Cache Memory
 
@@ -24,11 +20,7 @@ tools:
 ---
 ```
 
-Uses default key `memory-${{ github.workflow }}-${{ github.run_id }}` and stores files at `/tmp/gh-aw/cache-memory/`.
-
-## Using the Cache Folder
-
-Store and retrieve information using standard file operations. Organize files as JSON/YAML (structured data), text files (notes/logs), or subdirectories.
+Stores files at `/tmp/gh-aw/cache-memory/` using default key `memory-${{ github.workflow }}-${{ github.run_id }}`. Use standard file operations to store/retrieve JSON/YAML, text files, or subdirectories.
 
 ## Advanced Configuration
 
@@ -37,12 +29,10 @@ Store and retrieve information using standard file operations. Organize files as
 tools:
   cache-memory:
     key: custom-memory-${{ github.workflow }}-${{ github.run_id }}
-    retention-days: 30  # 1-90 days, defaults to repo setting
+    retention-days: 30  # 1-90 days, extends access beyond cache expiration
 ---
 ```
 
-The `retention-days` controls artifact retention, providing access beyond the 7-day cache expiration.
-
 ## Multiple Cache Configurations
 
 ```aw wrap
@@ -58,12 +48,10 @@ tools:
 ---
 ```
 
-Each cache mounts at `/tmp/gh-aw/cache-memory/` (default) or `/tmp/gh-aw/cache-memory-{id}/` (others). The `id` field is required and determines the folder name. If `key` is omitted, defaults to `memory-{id}-${{ github.workflow }}-${{ github.run_id }}`.
+Mounts at `/tmp/gh-aw/cache-memory/` (default) or `/tmp/gh-aw/cache-memory-{id}/`. The `id` determines folder name; `key` defaults to `memory-{id}-${{ github.workflow }}-${{ github.run_id }}`.
 
 ## Cache Merging from Shared Workflows
 
-Import cache-memory configurations from shared workflow files:
-
 ```aw wrap
 ---
 imports:
@@ -73,43 +61,37 @@ tools:
 ---
 ```
 
-Merge rules: **Single to Single** (local overrides imported), **Single to Multiple** (local converted to array and merged), **Multiple to Multiple** (merged by `id`, local takes precedence).
+Merge rules: **Single→Single** (local overrides), **Single→Multiple** (local converts to array), **Multiple→Multiple** (merge by `id`, local wins).
 
-## Cache Behavior and GitHub Actions Integration
+## Cache Behavior
 
-Uses GitHub Actions cache with 7-day retention, 10GB per repository limit, and LRU eviction. With `retention-days`, cache data uploads as artifacts (1-90 days) for long-term access.
+GitHub Actions cache: 7-day retention, 10GB per repo, LRU eviction. Add `retention-days` to upload artifacts (1-90 days) for extended access.
 
-Caches are accessible across branches with unique per-run keys. Custom keys automatically append `-${{ github.run_id }}`. Progressive restore keys split on dashes (e.g., `custom-memory-project-v1-${{ github.run_id }}` tries `custom-memory-project-v1-`, `custom-memory-project-`, `custom-memory-`, `custom-`).
+Caches accessible across branches with unique per-run keys. Custom keys auto-append `-${{ github.run_id }}`. Progressive restore splits on dashes: `custom-memory-project-v1-${{ github.run_id }}` tries `custom-memory-project-v1-`, `custom-memory-project-`, `custom-memory-`, `custom-`.
 
 ## Best Practices
 
-Organize files with descriptive names and directories. Use hierarchical cache keys like `project-${{ github.repository_owner }}-${{ github.workflow }}`. Choose appropriate scope (workflow-specific by default, or repository/user-wide by including identifiers in keys). Monitor growth and respect the 10GB limit.
+Use descriptive file/directory names, hierarchical cache keys (`project-${{ github.repository_owner }}-${{ github.workflow }}`), and appropriate scope (workflow-specific default or repository/user-wide). Monitor growth within 10GB limit.
 
 ## Troubleshooting
 
-**Files Not Persisting**: Check cache key consistency and workflow logs for restore/save messages.
-
-**File Access Issues**: Create subdirectories before use, verify permissions, use absolute paths.
-
-**Cache Size Issues**: Track growth, clear periodically, or use time-based keys for auto-expiration.
+**Files not persisting**: Check cache key consistency and logs for restore/save messages.
+**File access issues**: Create subdirectories first, verify permissions, use absolute paths.
+**Cache size issues**: Track growth, clear periodically, or use time-based keys for auto-expiration.
 
-## Security Considerations
+## Security
 
-Avoid storing sensitive data in cache files. Cache follows repository permissions and logs access in workflow logs. Files use standard runner permissions in temporary directories.
-
-With [threat detection](/gh-aw/reference/safe-outputs/#threat-detection) enabled, cache updates defer until validation completes: restored via `actions/cache/restore`, modified by agent, uploaded as artifacts, validated, then saved via `actions/cache/save` only if detection succeeds. Without threat detection, updates occur automatically via standard cache post-action.
+Don't store sensitive data. Cache follows repository permissions, logs access. With [threat detection](/gh-aw/reference/safe-outputs/#threat-detection), cache saves only after validation succeeds (restore→modify→upload artifact→validate→save).
 
 ## Examples
 
-Basic usage with `cache-memory: true`, project-specific with custom keys, or multiple caches with different retention. See [Grumpy Code Reviewer](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/grumpy-reviewer.md) for tracking PR review history.
+See [Grumpy Code Reviewer](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/grumpy-reviewer.md) for tracking PR review history.
 
 ---
 
 # Repo Memory
 
-Enables persistent file storage using Git branches with unlimited retention. When enabled, the compiler automatically clones/creates the branch, provides file access at `/tmp/gh-aw/repo-memory-{id}/memory/{id}/`, commits and pushes changes, and handles merge conflicts (your changes win).
-
-Default: branch `memory/default` at `/tmp/gh-aw/repo-memory-default/memory/default/`.
+Persistent file storage via Git branches with unlimited retention. The compiler auto-configures branch cloning/creation, file access at `/tmp/gh-aw/repo-memory-{id}/memory/{id}/`, commits/pushes, and merge conflict resolution (your changes win).
 
 ## Enabling Repo Memory
 
@@ -120,7 +102,7 @@ tools:
 ---
 ```
 
-Creates branch `memory/default` with file access at `/tmp/gh-aw/repo-memory-default/memory/default/`. Files are automatically committed and pushed after workflow completion.
+Creates branch `memory/default` at `/tmp/gh-aw/repo-memory-default/memory/default/`. Files auto-commit/push after workflow completion.
 
 ## Advanced Configuration
 
@@ -129,17 +111,15 @@ Creates branch `memory/default` with file access at `/tmp/gh-aw/repo-memory-defa
 tools:
   repo-memory:
     branch-name: memory/custom-agent
-    description: "Long-term insights and patterns"
+    description: "Long-term insights"
     file-glob: ["*.md", "*.json"]
-    max-file-size: 1048576  # 1MB, default 10KB
+    max-file-size: 1048576  # 1MB (default 10KB)
     max-file-count: 50      # default 100
     target-repo: "owner/repository"
-    create-orphan: true     # default true
+    create-orphan: true     # default
 ---
 ```
 
-Options: `branch-name` (default `memory/default`), `description`, `file-glob`, `max-file-size`, `max-file-count`, `target-repo`, `create-orphan`.
-
 ## Multiple Repo Memory Configurations
 
 ```aw wrap
@@ -155,48 +135,42 @@ tools:
 ---
 ```
 
-Each mounts at `/tmp/gh-aw/repo-memory-{id}/memory/{id}/`. The `id` field is required and determines folder/branch names. If `branch-name` is omitted, defaults to `memory/{id}`.
+Mounts at `/tmp/gh-aw/repo-memory-{id}/memory/{id}/`. Required `id` determines folder/branch names; `branch-name` defaults to `memory/{id}`.
 
-## Behavior and Git Integration
+## Behavior
 
-Branches are auto-created as orphans (if `create-orphan: true`, default) or cloned with `--depth 1`. Changes commit automatically after validation (against `file-glob`, `max-file-size`, `max-file-count`), pull with `-X ours` (your changes win conflicts), and push. Push occurs only if changes detected and threat detection passes (if configured). Automatically adds `contents: write` permission.
+Branches auto-create as orphans (default) or clone with `--depth 1`. Changes auto-commit after validation (`file-glob`, `max-file-size`, `max-file-count`), pull with `-X ours` (your changes win), and push when changes detected and threat detection passes. Auto-adds `contents: write` permission.
 
 ## Best Practices
 
-Organize files with descriptive names and directories. Use hierarchical branch names (`memory/default`, `memory/insights`). Choose scope (workflow-specific default, shared across workflows, or cross-repository with `target-repo`). Set constraints (`file-glob`, `max-file-size`, `max-file-count`) to prevent abuse. Monitor branch size and clean periodically.
+Use descriptive names, hierarchical branches (`memory/insights`), appropriate scope (workflow-specific, shared, or `target-repo` for cross-repository), and constraints to prevent abuse. Monitor branch size, clean periodically.
 
-## Comparing Cache Memory vs Repo Memory
+## Comparison
 
 | Feature | Cache Memory | Repo Memory |
 |---------|--------------|-------------|
-| **Storage** | GitHub Actions Cache | Git Branches |
-| **Retention** | 7 days | Unlimited |
-| **Size Limit** | 10GB/repo | Repository limits |
-| **Version Control** | No | Yes |
-| **Performance** | Fast | Slower |
-| **Best For** | Temporary/sessions | Long-term/history |
-
-Choose cache for fast temporary storage, repo for permanent version-controlled storage.
+| Storage | GitHub Actions Cache | Git Branches |
+| Retention | 7 days | Unlimited |
+| Size Limit | 10GB/repo | Repository limits |
+| Version Control | No | Yes |
+| Performance | Fast | Slower |
+| Best For | Temporary/sessions | Long-term/history |
 
 ## Troubleshooting
 
-**Branch Not Created**: Ensure `create-orphan: true` or create branch manually.
-
-**Permission Denied**: `contents: write` is auto-added by compiler.
-
-**File Validation Failures**: Verify files match `file-glob`, are under `max-file-size` (10KB default), and within `max-file-count` (100 default).
-
-**Changes Not Persisting**: Check correct directory (`/tmp/gh-aw/repo-memory-{id}/memory/{id}/`), successful workflow completion, and push errors in logs.
-
-**Merge Conflicts**: Uses `-X ours`, your changes always win. Read before writing to preserve previous data.
+**Branch not created**: Ensure `create-orphan: true` or create manually.
+**Permission denied**: Compiler auto-adds `contents: write`.
+**Validation failures**: Match `file-glob`, stay under `max-file-size` (10KB default) and `max-file-count` (100 default).
+**Changes not persisting**: Check directory path, workflow completion, push errors in logs.
+**Merge conflicts**: Uses `-X ours` (your changes win). Read before writing to preserve data.
 
-## Security Considerations
+## Security
 
-Memory branches follow repository permissions. Use private repos for sensitive data. Avoid storing secrets. Use `file-glob`, `max-file-size`, and `max-file-count` to restrict files. Consider branch protection rules for production. Use `target-repo` to isolate memory.
+Memory branches follow repository permissions. Use private repos for sensitive data, avoid storing secrets, set constraints (`file-glob`, `max-file-size`, `max-file-count`), consider branch protection, use `target-repo` to isolate.
 
 ## Examples
 
-Basic usage with `repo-memory: true`, custom branches with constraints, multiple memory locations by ID, or cross-repository with `target-repo`. See [Deep Report](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/deep-report.md) and [Daily Firewall Report](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/daily-firewall-report.md) for tracking long-term insights and historical security data.
+See [Deep Report](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/deep-report.md) and [Daily Firewall Report](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/daily-firewall-report.md) for long-term insights and historical data tracking.
 
 ---