swmm-rag-memory

name	swmm-rag-memory
description	Retrieve relevant Agentic SWMM modeling memory from audited runs, modeling-memory summaries, and Obsidian-compatible notes at query time. Use when a user asks for RAG, similar past runs, evidence-linked memory retrieval, historical QA/failure patterns, or memory-grounded answers.

SWMM RAG Memory

What this skill provides

• Query-time retrieval over Agentic SWMM audited run memory.
• A lightweight keyword/tag retriever that works without embeddings or a vector database.
• A local hybrid retriever that combines keyword matches, deterministic SWMM tags, metadata weighting, and hashed token/character n-gram embeddings.
• RAG context packs that can be passed to Codex, OpenClaw, Hermes, or another LLM.
• Source citations for each retrieved memory item, including run id, project key, source file, failure patterns, diagnostics, and matched terms.
• Retrieval-grounded failure_advice.{json,md} for failed or warning runs, without modifying model files.
• Explicit resolution_memory.json for human-reviewed and benchmark-verified repairs.
• Obsidian-compatible Markdown output for saved retrieval notes.

This skill reads existing audit and modeling-memory artifacts. It does not run SWMM, modify model inputs, rewrite skills, or claim that retrieved memory proves a modeling conclusion.

Relationship to swmm-modeling-memory

swmm-modeling-memory summarizes audited runs after experiments have been recorded.

swmm-rag-memory retrieves the most relevant historical memory for a current question.

The intended loop is:

1. Run SWMM or attempt a workflow.
2. Audit the run.
3. Refresh swmm-modeling-memory.
4. Ask a current modeling question.
5. Retrieve relevant historical memory with swmm-rag-memory.
6. Answer with explicit source boundaries and citations.

Output contract

The corpus builder writes these files to the selected RAG-memory output directory:

• corpus.jsonl
• keyword_index.json
• embedding_index.json

The retriever writes JSON results by default and can also write a Markdown context pack. Failure advice writes failure_advice.json and failure_advice.md into the run directory. Verified repairs can be recorded as resolution_memory.json.

CLI

Build a corpus from existing memory and audited runs:

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

Retrieve relevant memory:

python3 skills/swmm-rag-memory/scripts/retrieve_memory.py \
  --query "peak flow parsing is missing" \
  --memory-dir memory/modeling-memory \
  --runs-dir runs \
  --top-k 5

Hybrid retrieval:

python3 skills/swmm-rag-memory/scripts/retrieve_memory.py \
  --query "peak flow was not parsed from the report" \
  --index-dir memory/rag-memory \
  --retriever hybrid \
  --top-k 5

Generate an LLM-ready context pack:

python3 skills/swmm-rag-memory/scripts/answer_with_memory.py \
  --query "Why does high continuity error keep recurring?" \
  --memory-dir memory/modeling-memory \
  --runs-dir runs \
  --retriever hybrid \
  --top-k 6 \
  --format markdown

Optional Obsidian export:

python3 skills/swmm-rag-memory/scripts/answer_with_memory.py \
  --query "How should I investigate missing peak-flow parsing?" \
  --memory-dir memory/modeling-memory \
  --runs-dir runs \
  --obsidian-dir "$HOME/Documents/Agentic-SWMM-Obsidian-Vault/10_Memory_Layer/RAG Queries"

Generate advice after a failed, partial, or warning run:

python3 skills/swmm-rag-memory/scripts/generate_failure_advice.py \
  --run-dir runs/<case> \
  --index-dir memory/rag-memory \
  --retriever hybrid

Record a repair only after review and verification:

python3 skills/swmm-rag-memory/scripts/record_resolution_memory.py \
  --run-dir runs/<case> \
  --action-taken "Updated runner parser to read Node Inflow Summary." \
  --file-changed skills/swmm-runner/scripts/run_swmm.py \
  --verification "python3 -m pytest tests/test_swmm_runner_peak_parser.py" \
  --human-reviewed \
  --benchmark-verified

One-command post-audit refresh:

python3 skills/swmm-rag-memory/scripts/refresh_after_run.py \
  --run-dir runs/<case> \
  --runs-dir runs \
  --memory-dir memory/modeling-memory \
  --rag-dir memory/rag-memory

This rebuilds the RAG corpus, generates failure advice only if trigger conditions are met, and rebuilds the corpus again if advice was written. It does not regenerate curated memory/modeling-memory outputs unless --refresh-modeling-memory is provided.

Safety rules

• Read existing memory and audit artifacts only.
• Keep retrieval evidence-linked: every result must include a source path.
• Distinguish retrieved audit evidence from inference.
• Prefer deterministic tags such as failure patterns and diagnostic ids over unsupported free-text interpretation.
• Do not mutate runs/, memory/modeling-memory/, or existing SKILL.md files.
• Do not treat failure_advice.md as accepted knowledge. It is only retrieval-grounded advice.
• Treat resolution_memory.json as reusable repair memory only when human_reviewed=true and benchmark_verified=true.
• Obsidian export is optional and writes only retrieval notes.