Dump

---
name: dump
description: Consolidate the current session's progress into the project's auto-memory directory — the "log everything, update state, prepare for resumption" drill. Use when the user says "log everything", "checkpoint", "save progress", "update memory", "dump state", or autonomously when a long session is approaching context saturation, a natural checkpoint has been reached, or substantial non-derivable state has accumulated that would be lost on session end. Works on any project primed with /mf:prime; writes to the Claude Code auto-memory dir under ~/.claude/projects/<slug>/memory/.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash]
---

# /mf:dump — session → project memory

Write the current session's non-derivable state to the project's auto-memory directory so a future session can resume cleanly. Idempotent: can run mid-session, at a natural checkpoint, or at end-of-session.

## Important

1. **Never proliferate files.** Update existing memory first; create new files only when a topic genuinely deserves its own dossier.
2. **Only log non-derivable signal.** Facts recoverable from `git log`, current code, or `AGENTS.md` / `PROJECT.md` do not belong in memory.
3. **SOUL.md and the user-global AGENTS.md are sacred.** Propose edits, never apply silently, and only when the insight is genuinely general. The user-global AGENTS.md lives at `~/.mindfunnel/AGENTS.md` (reached via `~/.claude/CLAUDE.md`); the per-project `./AGENTS.md` is a small project-scoped stub owned by the project — don't treat them as the same file.
4. **Convert every "today" / "tomorrow" to an absolute date** before writing. Run `date -I` if uncertain.
5. **Append atomic assertions to the ledger, don't narrate them.** Claims, decisions, and learnings that carry a trust level and provenance go to `ledger.jsonl` (Step 5b); the narrative stays in Markdown. Never double-log one as the other — cross-reference.

## Instructions

### Step 1: Locate the memory directory

Use the auto-memory directory Claude Code names in its system prompt. Without one, derive it: `~/.claude/projects/<slug>/memory/`, where `<slug>` is the repository root — shared by its subdirectories and worktrees; `$PWD` outside git — with every non-alphanumeric character replaced by `-`. An `autoMemoryDirectory` setting or `CLAUDE_CODE_PROJECT_DIR_NAME` overrides the derivation.

```bash
bash -c 'g=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) && r=$(dirname "$g") || r=$PWD; echo ~/.claude/projects/$(printf %s "$r" | sed "s/[^A-Za-z0-9]/-/g")/memory'
```

The directory is usually already created by Claude Code. If not, create it before writing.

### Step 2: Verify the project is primed

Confirm `AGENTS.md` and `PROJECT.md` exist in the project root (set up by `/mf:prime`; a regular file or a symlink both count). If either is missing:

- **Flag it** and offer to run `/mf:prime` from the project root.
- **Do not run `/mf:prime` silently** — pre-existing files with the same name matter.
- **Proceed with the dump anyway**, noting the priming gap in the final report.

### Step 3: Survey existing memory

Read `<memory_dir>/MEMORY.md` (the index) and the most recently modified files:

```bash
ls -lt <memory_dir>/*.md 2>/dev/null | head -10
```

Decide for each signal you want to log: does it belong in an **existing file** (preferred) or a **new file** (rare)?

### Step 4: Extract signal from the conversation

Identify, in priority order:

1. **Results + numbers** — experiment outcomes, benchmarks, sweep tables. Always keep the actual numbers, never just "it worked".
2. **Decisions + rationale** — especially tradeoffs. The _why_ is more durable than the _what_.
3. **Load-bearing code changes** — structural shifts, new entry points, architectural moves. Not trivial edits.
4. **Open threads** — pending experiments, unresolved questions, "run this next" commands.
5. **Surprises and corrections** — failed hypotheses, midcourse reversals, negative results.

Skip anything derivable from `git log`, the current code, or the primed config files.

### Step 5: Write using the auto-memory type taxonomy

Every memory file has YAML frontmatter with `name`, `description`, `type`. The four types:

- **`project`** — ongoing work state, results, decisions, deadlines, pending experiments. High churn.
- **`feedback`** — behavioural guidance (both corrections _and_ validated choices). Each entry: rule + **Why:** + **How to apply:**. Moderate churn.
- **`user`** — durable facts about the user's role, expertise, responsibilities. Low churn.
- **`reference`** — pointers to external systems (issue trackers, experiment trackers, dashboards, buckets). Low churn.

Filename convention: `<type>_<topic>.md` (e.g. `project_state.md`, `feedback_offline_vs_online.md`, `reference_wandb.md`); a large results dossier of type `project` may be named `results_<topic>.md`.

### Step 5b: Append atomic entries to the ledger

Alongside the narrative Markdown, append **atomic** claims / decisions / learnings to the append-only ledger. This is where trust and provenance live, so a future session can tell a measured result from an inferred guess — and check whether it has since gone stale.

The full schema, trust ladder, and semantics are in `${CLAUDE_PLUGIN_ROOT}/references/ledger.md` — read it if you have not this session. In short, each line is one JSON object:

```json
{
    "id": "<unique>",
    "ts": "<ISO-8601 UTC>",
    "kind": "claim|decision|learning",
    "status": "guaranteed|observed|given|user-inferred|agent-inferred|opinion",
    "text": "<one sentence>",
    "sources": ["<path>", "<path@sha>", "<run-id>"],
    "supersedes": "<id?>",
    "key": "<optional>"
}
```

Rules:

- **Append only.** Never rewrite or delete a line. To revise, append a new entry whose `supersedes` names the old `id`.
- **Pick the honest trust rung.** `guaranteed` > `observed` > `given` > `user-inferred` > `agent-inferred`; `opinion` for a taste call with no truth claim. Do not inflate an inference to `observed`.
- **Record provenance.** Put the grounding paths (commit-pinned as `path@<sha>`, with `<sha>` = `git rev-parse HEAD` at dump time, when the claim is tied to specific code), run-ids, or URLs in `sources`. Omit for a bare preference.
- **Ledger-worthy only.** One-sentence assertions that carry trust or provenance — a benchmark number, a settled decision, a durable gotcha. Prose state stays in Markdown; do not double-log.

Append with a shell heredoc (the memory dir from Step 1; timestamp via `date -u +%Y-%m-%dT%H:%M:%SZ`):

```bash
LEDGER="<memory dir from Step 1>/ledger.jsonl"
cat >> "$LEDGER" <<'JSON'
{"id":"20260101-1","ts":"2026-01-01T00:00:00Z","kind":"claim","status":"observed","text":"...","sources":["..."]}
JSON
```

Correct what has gone stale: when an entry's source changed — including drift a `/mf:spinup` brief flagged this session — append a corrected entry that `supersedes` it.

If there are no atomic assertions worth pinning this dump, skip — the ledger is not a log of everything.

### Step 6: Refresh the index

Update `<memory_dir>/MEMORY.md` with one line per entry:

```markdown
- [Title](file.md) — one-line hook, under ~150 characters.
```

`MEMORY.md` has no frontmatter — it's an index, not a memory. For any file you updated or created, re-word its hook if the content shifted substantively.

### Step 7: Cross-check, then write

Before writing: for any file you're about to modify, read it first to preserve load-bearing context. Duplication is a smell — if the same fact appears in two files, pick one canonical home and cross-reference.

### Step 8: (Rare) Propose user-global SOUL.md / AGENTS.md / USER.md edits

If the session surfaced a **general** guideline or preference worth propagating to every future session on any project, propose an edit to one of the user-global files:

- `~/.mindfunnel/SOUL.md` — user traits, collaboration style, communication preferences.
- `~/.mindfunnel/AGENTS.md` — general, agent-neutral engineering guidelines. This is the maintainer's user-global AGENTS.md, auto-loaded via `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`. It is not the per-project `./AGENTS.md` (which is a small project-scoped stub owned by the project).
- `~/.mindfunnel/USER.md` — per-machine user preferences: shell, Python defaults, formatter paths, multi-agent hook bridges.

**Guardrails:**

- **Propose, never apply silently.** Show the proposed passage, explain _why_ it's general, wait for explicit approval, then apply.
- **Rare by design**: most dumps propose nothing; propose only when an insight meets all three conditions below.
- **Three conditions must all hold**: genuinely general (applies to any project), stable (not contradicted elsewhere), actionable (a concrete rule, not a vibe).
- **Write to `~/.mindfunnel/` directly** — never to the per-project `./AGENTS.md` or to the symlink aliases (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`). The user-global content has one canonical home.
- **Pick the right file.** Agent-neutral engineering style → AGENTS.md. Personal style / who the user is → SOUL.md. Machine-specific tooling → USER.md.

If in doubt, skip. User-global file churn creates noise.

### Step 9: Report

End with a concise summary:

```
Memory dir: <path>
Updated:
  - <file> — <one-line reason>
Created:
  - <file> — <one-line reason>
Index (MEMORY.md): refreshed | unchanged
Ledger (ledger.jsonl): +N entries | unchanged
Proposed SOUL.md / AGENTS.md / USER.md edits: none | <one-line summary, pending approval>
```

If nothing was worth logging, say "no new signal; memory is current" and do nothing.

## Examples

### Example 1: Mid-sweep checkpoint after a production run

**User says:** "Log everything, the sweep results just came in."

**Actions:**

1. Compute memory dir via the sed snippet; confirm `MEMORY.md` exists; read it.
2. Read the most recent `project_state.md` and `results_*.md` files.
3. From the conversation, extract: sweep numbers (per-seed, aggregate), the decision made ("v3 recipe wins cleanly"), any flagged concerns.
4. Update `project_state.md` with the new "where we are + next action".
5. Create `results_<experiment>_<date>.md` if the sweep is a major dossier; otherwise append to an existing results file.
6. Refresh `MEMORY.md` one-liner for each touched file.
7. No SOUL.md / AGENTS.md / USER.md proposals.

**Result:** One report block listing what was updated, memory ready for the next session.

### Example 2: End-of-session cleanup with no new findings

**User says:** "Dump before I close."

**Actions:**

1. Scan the conversation for signal. Finds: only tool invocations and small Q&A, no new results or decisions.
2. Skip the dump entirely.
3. Report: "no new signal since the last dump; memory is current."

### Example 3: General guideline surfaces, worth a user-global AGENTS.md proposal

**User says:** "Log everything. That lesson about always verifying memory claims before citing them is something I want to keep."

**Actions:**

1. Update `project_state.md` and any `results_*.md` as usual.
2. Draft a one-paragraph addition to `~/.mindfunnel/AGENTS.md` under "Handling Existing Code" or "Autonomy and Asking".
3. Show the proposed diff to the user.
4. **Wait for approval.** Do not apply.
5. On approval: apply the edit, confirm, and note it in the dump report.

## Troubleshooting

### Error: Memory directory path seems wrong

**Symptom:** Files land at an unexpected location, or Claude Code complains about an unknown memory dir.

**Cause:** An `autoMemoryDirectory` setting or `CLAUDE_CODE_PROJECT_DIR_NAME` moved the directory, or Step 1's derivation missed a case (a git submodule, git older than 2.31).

**Solution:** Check with `ls ~/.claude/projects/` — the current project's dir should appear. If absent, Claude Code hasn't indexed this project yet; create the dir manually with `mkdir -p ~/.claude/projects/<slug>/memory` and Claude Code will adopt it.

### Error: Conflicting facts between memory files

**Symptom:** Two memory files disagree on a number or decision.

**Cause:** A previous dump duplicated content instead of cross-referencing.

**Solution:** Pick the **newer** or **more specific** statement as canonical. Edit the other file to cross-reference the canonical one (`See [results_foo.md](results_foo.md) for current numbers.`). Note the consolidation in the final dump report.

### Error: Memory churn — dumping too often with too little signal

**Symptom:** `git log` of the memory dir shows many small updates, many of them trivial.

**Cause:** The empty-dump guard is being skipped.

**Solution:** Skip the dump when the conversation contains only tool noise / small Q&A. Say "no new signal; memory is current" and do nothing. Memory is not a commit log.

### Error: Proposed a SOUL.md / AGENTS.md / USER.md edit that was rejected

**Symptom:** The user said "no" to a proposed general-guideline edit.

**Cause:** The insight wasn't actually general, or was contradicted by other contexts.

**Solution:** Accept the rejection, do **not** re-propose in the same session, and move the insight into a **project-level `feedback_*.md`** instead if it's still useful at the project scope.

## Anti-patterns

- **Don't dump verbatim tool output** — summarise signal, cite key numbers only.
- **Don't log bug-fix recipes** — the fix is in the code, its context is in the commit. Log _why_ the bug existed if non-obvious.
- **Don't overwrite** existing content without reading first.
- **Don't create a new file** when an existing one can absorb the update.
- **Don't list every tool call you made** — memory is for signal, not process.
- **Don't re-run experiments or verify against current code** — that's spinup's job. Dump is mostly write.
- **Don't include ephemeral task details** (current conversation turn, in-progress tool output) — those live in the conversation.
- **Don't create TODO lists in memory.** Pending actions belong in `project_state.md` under a "Next actions" section, tied to a concrete command or decision.