Skip to content

[docs] docs: remove repetitive structural overhead from MemoryOps guide #17796

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

Closed
github-actions wants to merge 1 commit into from
Closed

[docs] docs: remove repetitive structural overhead from MemoryOps guide #17796

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
110 changes: 31 additions & 79 deletions docs/src/content/docs/guides/memoryops.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,22 +11,7 @@ Use MemoryOps for incremental processing, trend analysis, multi-step tasks, and

## How to Use These Patterns

> [!TIP]
> **Let the AI Agent Do the Work**
>
> When using these patterns, **state your high-level goal** in the workflow prompt and let the AI agent generate the concrete implementation. The patterns below are conceptual guides - you don't need to write the detailed code yourself.
>
> **Example approach:**
>
> ```markdown
> # Process All Open Issues
>
> Analyze all open issues in the repository. Use cache-memory to track which
> issues you've already processed so you can resume if interrupted. For each
> issue, extract sentiment and priority, then generate a summary report.
> ```
>
> The agent will see the cache-memory configuration in your frontmatter and implement the todo/done tracking pattern automatically based on your goal.
State your high-level goal in the workflow prompt — the agent generates the concrete implementation based on your memory configuration. The patterns below are conceptual guides, not code you write yourself.

## Memory Types

Expand Down Expand Up @@ -59,20 +44,16 @@ tools:

## Pattern 1: Exhaustive Processing

Track progress through large datasets with todo/done lists to ensure complete coverage across multiple runs.
Track progress through large datasets with todo/done lists to ensure complete coverage across multiple runs. Example prompt:

**Your goal**: "Process all items in a collection, tracking which ones are done so I can resume if interrupted."

**How to state it in your workflow**:
```markdown
Analyze all open issues in the repository. Track your progress in cache-memory
so you can resume if the workflow times out. Mark each issue as done after
Analyze all open issues in the repository. Track your progress in cache-memory
so you can resume if the workflow times out. Mark each issue as done after
processing it. Generate a final report with statistics.
```

**What the agent will implement**: Maintain a state file with items to process (`todo`) and completed items (`done`). After processing each item, immediately update the state so the workflow can resume if interrupted.
The agent maintains a state file with `todo` and `done` lists, updating after each item so the workflow can resume if interrupted:

**Example structure the agent might use**:
```json
{
"todo": [123, 456, 789],
Expand All @@ -82,24 +63,20 @@ processing it. Generate a final report with statistics.
}
```

**Real examples**: `.github/workflows/repository-quality-improver.md`, `.github/workflows/copilot-agent-analysis.md`
*Examples: `.github/workflows/repository-quality-improver.md`, `.github/workflows/copilot-agent-analysis.md`*

## Pattern 2: State Persistence

Save workflow checkpoints to resume long-running tasks that may timeout.

**Your goal**: "Process data in batches, saving progress so I can continue where I left off in the next run."
Save workflow checkpoints to resume long-running tasks that may timeout. Example prompt:

**How to state it in your workflow**:
```markdown
Migrate 10,000 records from the old format to the new format. Process 500
records per run and save a checkpoint. Each run should resume from the last
Migrate 10,000 records from the old format to the new format. Process 500
records per run and save a checkpoint. Each run should resume from the last
checkpoint until all records are migrated.
```

**What the agent will implement**: Store a checkpoint with the last processed position. Each run loads the checkpoint, processes a batch, then saves the new position.
The agent stores a checkpoint with the last processed position, loading and updating it each run:

**Example checkpoint the agent might use**:
```json
{
"last_processed_id": 1250,
Expand All @@ -109,96 +86,71 @@ checkpoint until all records are migrated.
}
```

**Real examples**: `.github/workflows/daily-news.md`, `.github/workflows/cli-consistency-checker.md`
*Examples: `.github/workflows/daily-news.md`, `.github/workflows/cli-consistency-checker.md`*

## Pattern 3: Shared Information

Share data between workflows using repo-memory branches.

**Your goal**: "Collect data in one workflow and analyze it in other workflows."
Share data between workflows using repo-memory branches. A producer workflow stores data; consumer workflows read and analyze it using the same branch name.

**How to state it in your workflow**:

*Producer workflow:*
*Producer:*
```markdown
Every 6 hours, collect repository metrics (issues, PRs, stars) and store them
Every 6 hours, collect repository metrics (issues, PRs, stars) and store them
in repo-memory so other workflows can analyze the data later.
```

*Consumer workflow:*
*Consumer:*
```markdown
Load the historical metrics from repo-memory and compute weekly trends.
Load the historical metrics from repo-memory and compute weekly trends.
Generate a trend report with visualizations.
```

**What the agent will implement**: One workflow (producer) collects data and stores it in repo-memory. Other workflows (consumers) read and analyze the shared data using the same branch name.
Both workflows use the same branch:

**Configuration both workflows need**:
```yaml
tools:
repo-memory:
branch-name: memory/shared-data # Same branch for producer and consumer
```

**Real examples**: `.github/workflows/metrics-collector.md` (producer), trend analysis workflows (consumers)
*Examples: `.github/workflows/metrics-collector.md` (producer), trend analysis workflows (consumers)*

## Pattern 4: Data Caching

Cache API responses to avoid rate limits and reduce workflow time.

**Your goal**: "Avoid hitting rate limits by caching API responses that don't change frequently."
Cache API responses to avoid rate limits and reduce workflow time. Example prompt:

**How to state it in your workflow**:
```markdown
Fetch repository metadata and contributor lists. Cache the data for 24 hours
to avoid repeated API calls. If the cache is fresh, use it. Otherwise, fetch
Fetch repository metadata and contributor lists. Cache the data for 24 hours
to avoid repeated API calls. If the cache is fresh, use it. Otherwise, fetch
new data and update the cache.
```

**What the agent will implement**: Before making expensive API calls, check if cached data exists and is fresh. If cache is valid (based on TTL), use cached data. Otherwise, fetch fresh data and update cache.

**TTL guidelines to include in your prompt**:
- Repository metadata: 24 hours
- Contributor lists: 12 hours
- Issues/PRs: 1 hour
- Workflow runs: 30 minutes
Suggested TTL values to include: repository metadata (24h), contributor lists (12h), issues/PRs (1h), workflow runs (30min).

**Real examples**: `.github/workflows/daily-news.md`
*Examples: `.github/workflows/daily-news.md`*

## Pattern 5: Trend Computation

Store time-series data and compute trends, moving averages, and statistics.
Store time-series data and compute trends, moving averages, and statistics. The agent appends data points to a JSON Lines history file and generates visualizations. Example prompt:

**Your goal**: "Track metrics over time and identify trends."

**How to state it in your workflow**:
```markdown
Collect daily build times and test times. Store them in repo-memory as
time-series data. Compute 7-day and 30-day moving averages. Generate trend
Collect daily build times and test times. Store them in repo-memory as
time-series data. Compute 7-day and 30-day moving averages. Generate trend
charts showing whether performance is improving or declining over time.
```

**What the agent will implement**: Append new data points to a history file (JSON Lines format). Load historical data to compute trends, moving averages, and generate visualizations using Python.

**Real examples**: `.github/workflows/daily-code-metrics.md`, `.github/workflows/shared/charts-with-trending.md`
*Examples: `.github/workflows/daily-code-metrics.md`, `.github/workflows/shared/charts-with-trending.md`*

## Pattern 6: Multiple Memory Stores

Use multiple memory instances for different purposes and retention policies.

**Your goal**: "Organize data with different lifecycles - temporary session data, historical metrics, configuration, and archived snapshots."

**How to state it in your workflow**:
Use multiple memory instances for different purposes and retention policies. The agent separates hot data (cache-memory) from historical data (repo-memory), using different branches for metrics, configuration, and archives. Example prompt:

```markdown
Use cache-memory for temporary API responses during this run. Store daily
metrics in one repo-memory branch for trend analysis. Keep data schemas in
Use cache-memory for temporary API responses during this run. Store daily
metrics in one repo-memory branch for trend analysis. Keep data schemas in
another branch. Archive full snapshots in a third branch with compression.
```

**What the agent will implement**: Separate hot data (cache-memory) from historical data (repo-memory). Use different repo-memory branches for metrics vs. configuration vs. archives.

**Configuration to include**:
Example configuration:

```yaml
tools:
Expand Down