swmm-modeling-memory

name

swmm-modeling-memory

description

Read historical Agentic SWMM experiment audit artifacts and summarize repeated assumptions, QA issues, failures, missing evidence, run-to-run differences, lessons learned, and controlled skill update proposals. Use downstream of swmm-experiment-audit when multiple audited runs exist or when a user asks for modeling memory, failure-pattern extraction, lessons learned, or human-reviewed skill refinement proposals.

SWMM Modeling Memory

Part of Agentic SWMM — install the project first for the executable toolchain (aiswmm CLI, SWMM solver, MCP servers).

What this skill provides

• A downstream memory layer for audited Agentic SWMM runs.
• Deterministic summaries of repeated assumptions, QA issues, failures, missing evidence, and run-to-run differences.
• Run-level memory_summary.json cards that compress audit artifacts into reusable next-run context.
• Project/case-level memory groups that keep Tod Creek, Tecnopolo, TUFLOW, Generate_SWMM_inp, acceptance, and other cases separate.
• Summaries of deterministic SWMM-specific diagnostics when model_diagnostics.json is present.
• Human-readable lessons learned from previous audit records.
• Controlled skill update proposals that require human review and benchmark verification.

This skill does not run SWMM, build SWMM models, modify existing skills, or claim autonomous self-improvement.

Agentic SWMM is not only an automation workflow. It is a memory-informed, verification-first modeling system that can learn from audited modeling history through controlled skill refinement.

When to use this skill

Use this skill after swmm-experiment-audit has produced run-level artifacts such as:

• experiment_provenance.json
• comparison.json
• experiment_note.md
• model_diagnostics.json when available

Use it when:

• multiple audited runs exist,
• the user wants lessons learned across runs,
• the user asks for recurring failure patterns or QA issues,
• the user wants evidence-informed skill refinement proposals.

The proposals may point to relevant workflow skills such as end-to-end orchestration, audit reporting, QA verification, model building, or result parsing. They are not accepted changes.

Output contract

The script writes these files to the selected modeling-memory output directory:

• modeling_memory_index.json
• modeling_memory_index.md
• run_memory_summaries.json
• project_memory_index.md
• projects/<project-key>/project_memory.json
• projects/<project-key>/project_memory.md
• lessons_learned.md
• skill_update_proposals.md
• benchmark_verification_plan.md

The script also writes memory_summary.json beside each audited run by default. The JSON index and run summaries are the machine-readable source. The Markdown files are human-readable and can be copied to Obsidian with --obsidian-dir.

CLI

python3 skills/swmm-modeling-memory/scripts/summarize_memory.py \
  --runs-dir runs \
  --out-dir memory/modeling-memory

To refresh only the aggregate output without writing run-level cards (only available via direct script invocation — aiswmm memory does not expose this flag):

python3 skills/swmm-modeling-memory/scripts/summarize_memory.py \
  --runs-dir runs \
  --out-dir memory/modeling-memory \
  --no-run-summaries

With optional Obsidian export:

python3 skills/swmm-modeling-memory/scripts/summarize_memory.py \
  --runs-dir runs \
  --out-dir memory/modeling-memory \
  --obsidian-dir "/path/to/Obsidian/Agentic SWMM/05_Modeling_Memory"

Safety rules

• Read existing audit artifacts only.
• Tolerate partial and failed runs.
• Do not modify any existing SKILL.md files.
• Do not modify benchmark behavior or audit output formats.
• Do not write outside --out-dir, audited run directories under --runs-dir, or the optional --obsidian-dir.
• Treat SWMM-specific diagnostics as deterministic audit evidence only; do not infer model errors from free-text notes.
• Treat skill update proposals as proposals only.
• Accept real skill refinements only after human review and benchmark verification.

Audit-end auto-trigger (M2)

aiswmm audit fires an auto-trigger after every successful audit that calls summarize_memory.py in the background to refresh lessons_learned.md and (unless --no-rag is given) rebuild the RAG corpus. This means lessons_learned.md can be written by two paths:

1. Automatic — agentic_swmm/memory/audit_hook.py via the M2 hook after aiswmm audit succeeds.
2. Manual — aiswmm memory --runs-dir runs or direct python3 skills/swmm-modeling-memory/scripts/summarize_memory.py.

Set AISWMM_SKIP_MEMORY=1 in the environment to suppress the auto-trigger (useful for CI or benchmark runs where memory mutation is unwanted). Pass --no-memory to aiswmm audit for the same effect on a single run.

The auto-trigger uses add_negative_lesson / NegativeLessonMd.update from agentic_swmm/memory/negative_lessons_markdown.py, which increments evidence_count and updates last_seen_utc on duplicate lesson names rather than clobbering the existing entry. Manual summarize_memory.py runs use the same merge logic.

Relationship to swmm-experiment-audit

swmm-experiment-audit records evidence for one run.

swmm-modeling-memory reads many audited runs and turns repeated evidence patterns into reusable project memory.

The intended controlled loop is:

1. Run SWMM or attempt a workflow.
2. Audit the run (aiswmm audit); the M2 hook refreshes lessons_learned.md automatically.
3. Preserve an Obsidian-compatible experiment note.
4. Summarize modeling memory across audited runs (manual aiswmm memory call when a full refresh is needed).
5. Extract recurring failure patterns.
6. Generate a skill update proposal.
7. Review the proposal as a human.
8. Verify with existing benchmarks before accepting any skill change.