From 458570502a4441c540d3ec9ab03f42c5ce32a4dd Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 30 Mar 2026 03:55:52 +0000 Subject: [PATCH] docs: unbloat memoryops guide by removing repetitive pattern labels MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Each of the 6 patterns repeated the same "Your goal" / "How to state it in your workflow" / "What the agent will implement" label structure. Removed these labels and condensed prose — content and examples unchanged. Also tightened the tip box and security considerations section. 301 → 244 lines (−19%). Co-Authored-By: Claude Sonnet 4.6 --- docs/src/content/docs/guides/memoryops.md | 117 ++++++---------------- 1 file changed, 30 insertions(+), 87 deletions(-) diff --git a/docs/src/content/docs/guides/memoryops.md b/docs/src/content/docs/guides/memoryops.md index 1c260969f12..9df7166c4cd 100644 --- a/docs/src/content/docs/guides/memoryops.md +++ b/docs/src/content/docs/guides/memoryops.md @@ -12,21 +12,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 and let the AI agent handle the implementation. The examples below are prompts you'd write — the agent generates the code automatically based on your memory configuration. ## Memory Types @@ -61,18 +47,14 @@ tools: Track progress through large datasets with todo/done lists to ensure complete coverage across multiple runs. -**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 items to process and completed items, updating it after each item so the workflow can resume if interrupted: -**Example structure the agent might use**: ```json { "todo": [123, 456, 789], @@ -82,24 +64,20 @@ processing it. Generate a final report with statistics. } ``` -**Real examples**: `.github/workflows/repository-quality-improver.md`, `.github/workflows/copilot-agent-analysis.md` +Real 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." - -**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 and resumes from it each run: -**Example checkpoint the agent might use**: ```json { "last_processed_id": 1250, @@ -109,109 +87,80 @@ checkpoint until all records are migrated. } ``` -**Real examples**: `.github/workflows/daily-news.md`, `.github/workflows/cli-consistency-checker.md` +Real 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." - -**How to state it in your workflow**: +Share data between workflows using repo-memory branches. A producer workflow stores data; consumers read it using the same branch name. *Producer workflow:* ```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:* ```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 reference the same branch: -**Configuration both workflows need**: ```yaml tools: repo-memory: - branch-name: memory/shared-data # Same branch for producer and consumer + branch-name: memory/shared-data ``` -**Real examples**: `.github/workflows/metrics-collector.md` (producer), trend analysis workflows (consumers) +Real 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. The agent checks for fresh cached data before making API calls, using suggested TTLs: repository metadata (24h), contributor lists (12h), issues/PRs (1h), workflow runs (30m). -**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 - -**Real examples**: `.github/workflows/daily-news.md` +Real 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 new data points to a JSON Lines history file and computes trends using Python. -**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` +Real 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 lifecycles — cache-memory for temporary session data, separate repo-memory branches for metrics, configuration, and archives. ```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**: - ```yaml tools: cache-memory: key: session-data # Fast, temporary - + repo-memory: - id: metrics branch-name: memory/metrics # Time-series data - + - id: config branch-name: memory/config # Schema and metadata - + - id: archive branch-name: memory/archive # Compressed backups ``` @@ -267,13 +216,7 @@ fi ## Security Considerations -Memory stores are visible to anyone with repository access: - -- **Never store**: Credentials, API tokens, PII, secrets -- **Store only**: Aggregate statistics, anonymized data -- Consider encryption for sensitive but non-secret data - -**Safe practices**: +Memory stores are visible to anyone with repository access. Never store credentials, API tokens, PII, or secrets — only aggregate statistics and anonymized data. ```bash # ✅ GOOD - Aggregate statistics