Skip to content

[docs] Remove documentation bloat from memory.md #7271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 1 commit into from
Dec 22, 2025
Merged

[docs] Remove documentation bloat from memory.md #7271

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 40 additions & 66 deletions docs/src/content/docs/reference/memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

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

Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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

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

Expand All @@ -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
Expand All @@ -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.

---

Expand Down