Swmm Modeling Memory

SKILL.md

---
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](https://github.com/Zhonghao1995/agentic-swmm-workflow) — 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

```bash
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):

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

With optional Obsidian export:

```bash
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.