memory_save
Save learned patterns like test commands and failure diagnostics to persistent memory for future project runs, preventing duplicate entries to maintain efficiency.
Instructions
Persist a learned pattern to forge's project or global memory for future recall. Patterns are stored as JSONL entries with category, pattern text, confidence, and timestamp. Duplicate patterns (same category + same text, case-insensitive) are rejected on write to prevent memory bloat from repeatedly saving the same lesson across runs.
Behaviour:
MUTATION. Appends a new JSON line to
.forge/memory/<scope>.jsonl. Dedup check reads the existing file first; if a matching(category, pattern)already exists, the save is skipped and a "duplicate skipped" message is returned.Idempotent on
(category, pattern): calling twice with the same values produces one entry, not two.No authentication, no network, no rate limits.
Appends are atomic on POSIX filesystems, so parallel workers can save concurrently without corrupting the file.
Use when:
Phase 5 (Learn) at the end of a forge run — the orchestrator records test commands that worked, conventions discovered by the planner, and failure patterns surfaced by the debugger.
A debugger agent has diagnosed a non-obvious root cause and wants to make sure the next run doesn't re-learn it from scratch.
A reviewer agent has identified a convention (naming, file layout, test framework) the project consistently follows and wants future workers to match it automatically.
Do NOT use for:
Ephemeral session state — use
session_stateinstead. Memory is for knowledge that should outlive the run.Module retry history — that is tracked automatically by
iteration_stateandvalidate.Run-specific commentary or event logs — those belong in
forge_logs, which is written automatically on every tool call.Huge blobs of text (>1 KB) — memory entries are meant to be compact lessons, not dumps.
Returns: Confirmation string — either "Saved to memory []: " on new insert, or "Duplicate pattern already in memory, skipped." on dedup hit.
Example: memory_save({ pattern: "pnpm vitest --run for CI; watch mode hangs", category: "test_command", scope: "project", confidence: 0.9 }) → "Saved to project memory [test_command]: pnpm vitest --run..."
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | Yes | The pattern or learning to save | |
| category | Yes | Category of the learning. `success_pattern` is used by orchestrator Phase 5 to record run-shape calibration data (module count, tier depth, total time) for future planning. | |
| confidence | No | Confidence level 0-1 (default: 0.7) | |
| scope | No | Save to project memory (this project only) or global (all projects). Default: project |