Memory Keeper

Skill: Memory Keeper

Invocation

/chip-design-infrastructure:memory-keeper [--domain <name>] [--all] [--min-records <n>] [--init]

• --domain <name> — distil a single domain (e.g. synthesis, sta, pd)
• --all — distil every domain that has an experiences.jsonl with enough records
• --min-records <n> — minimum record count to proceed (default: 5); skip domains below threshold
• --init — resolve and seed the central memory root, migrating any repo-local runtime data (runs memory_root.py --init); no distillation. Use once after install or to inspect the location.

If neither --domain nor --all nor --init is given, prompt the user to choose.

Memory Root Resolution

Memory does not live at a fixed relative memory/ path. The active root is resolved by memory_root.py (the single source of truth that distill.py and tools/qor_trends.py import), in this priority order:

1. an explicit --memory-root PATH argument
2. the $CHIP_DESIGN_MEMORY_ROOT environment variable
3. the central default ${XDG_DATA_HOME:-$HOME/.local/share}/chip-design-agents/digital/memory (Windows: %LOCALAPPDATA%\chip-design-agents\digital\memory)
4. the in-repo memory/ tree as a seed fallback (used only if the central root is unwritable)

The in-repo memory/ tree is the version-controlled seed: on first resolution each <domain>/knowledge.md is copied into the central root if absent (never overwriting accumulated data; runtime experiences.jsonl/run_state.md are never seeded). Orchestrators resolve this same root at session start and use it as <MEM> for every read/write. To print the resolved path:

python3 plugins/infrastructure/skills/memory-keeper/memory_root.py        # prints the root
python3 plugins/infrastructure/skills/memory-keeper/memory_root.py --init  # seed + migrate + report

Per-project scoping (opt-out of the central store): export CHIP_DESIGN_MEMORY_ROOT="$PWD/memory" (or pass --memory-root ./memory to the scripts).

Purpose

Orchestrators write one JSON record to memory/<domain>/experiences.jsonl after every run. Over time those records accumulate issue descriptions, applied fixes, metric ranges, and tool-flag observations. This skill reads that evidence and merges the new learnings into memory/<domain>/knowledge.md — the Tier-2 summary that every orchestrator reads at session start. Without periodic distillation, knowledge.md drifts stale while the evidence log grows.

Domains

Valid domain names match the subdirectories under memory/:

Stage: load_experiences

Domain Rules

1. Read memory/<domain>/experiences.jsonl (one JSON object per line).
2. Count valid records. If count < --min-records (default 5), print a skip notice and stop — not enough signal to distil.
3. If the file does not exist or is empty, skip with the same notice.
4. Parse every record into an in-memory list. Ignore malformed lines (log a warning).
5. Group records along three axes for the analysis stage:
   • Issues + fixes: collect all issues_encountered and fixes_applied strings
   • Tool flags: scan notes and fixes_applied for explicit flag/command patterns (lines containing -, --, or backtick-quoted commands)
   • Metric ranges: for each numeric field in key_metrics, collect the list of values across all records; compute min, max, median, and the most recent value

QoR Metrics to Evaluate

• records_read: total valid JSONL records parsed (target ≥ min-records threshold)
• records_skipped: malformed lines ignored (target: 0)
• signoff_rate: fraction of records where signoff_achieved: true (informational)

Output

Structured summary object (in-memory) passed to distil_knowledge:

{
  "domain": "<domain>",
  "record_count": "<n>",
  "date_range": ["<oldest ISO-8601>", "<newest ISO-8601>"],
  "signoff_rate": "<fraction>",
  "issue_fix_pairs": [{"issue": "...", "fix": "...", "count": "<n>"}],
  "tool_flag_candidates": ["<flag or command fragment>"],
  "metric_ranges": {
    "<metric_field>": {"min": "x", "max": "y", "median": "z", "latest": "w"}
  },
  "free_notes": ["<note string>"]
}

Stage: distil_knowledge

Domain Rules

1. Read the existing memory/<domain>/knowledge.md in full.
2. Using the structured summary from load_experiences, identify new evidence that is not already captured in the current knowledge.md:
   • New issue/fix pairs not yet present under Known Failure Patterns
   • New successful flags not yet under Successful Tool Flags
   • PDK or tool quirks mentioned in notes not yet under PDK / Tool Quirks
3. For each new finding, draft a concise bullet following the style of existing entries:
   • Lead with the symptom or scenario in bold
   • Follow with the cause and the fix in plain prose
   • Keep each entry to 2–4 sentences maximum
4. Merge new entries below existing entries in the relevant section — never delete or overwrite an existing entry unless it directly contradicts new evidence (note the contradiction explicitly).
5. If the signoff rate across records is < 50%, add a note in the Notes section flagging common failure modes that did not reach signoff.
6. Update the ## Notes section with a distillation timestamp: _Last distilled: <ISO-8601 date> from <n> experience records._ Replace any previous such line.
7. Write the updated content back to memory/<domain>/knowledge.md.