# Dump > 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//memory/. - Skill: `emaballarin/dump` (Agent Skill) - Install (CLI): `npx skillmds@latest add emaballarin/dump` - Raw SKILL.md: https://api.skillmd.com/api/skills/emaballarin/dump/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: emaballarin (https://skillmd.com/u/emaballarin) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/emaballarin/dump --- # /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 Claude Code's auto-memory system lives at `~/.claude/projects//memory/` where `` is the project's absolute path with every `/` replaced by `-`. ```bash bash -c 'echo ~/.claude/projects/$(echo "$PWD" | sed "s|/|-|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 (these are set up by `/mf:prime`; under 0.3.0+ they're real committed files, under older versions they may be symlinks — either counts). 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.md` (the index) and the most recently modified files: ```bash ls -lt /*.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: `_.md` (e.g. `project_state.md`, `results_full_sweep.md`, `feedback_offline_vs_online.md`, `reference_wandb.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 `references/ledger.md` — read it if you have not this session. In short, each line is one JSON object: ```json { "id": "", "ts": "", "kind": "claim|decision|learning", "status": "guaranteed|observed|given|user-inferred|agent-inferred|opinion", "text": "", "sources": ["", "", ""], "supersedes": "", "key": "" } ``` 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@` 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 is the same `` path as the Markdown files; timestamp via `date -u +%Y-%m-%dT%H:%M:%SZ`): ```bash LEDGER=~/.claude/projects/$(echo "$PWD" | sed "s|/|-|g")/memory/ledger.jsonl cat >> "$LEDGER" <<'JSON' {"id":"20260101-1","ts":"2026-01-01T00:00:00Z","kind":"claim","status":"observed","text":"...","sources":["..."]} JSON ``` 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.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/instructions.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. - **Budget**: 0 proposals in the common case, 1 every 5–10 dumps at most. - **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/instructions.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, ≤ 15 lines: ``` Memory dir: Updated: - — Created: - — Index (MEMORY.md): refreshed | unchanged Ledger (ledger.jsonl): +N entries | unchanged Proposed SOUL.md / AGENTS.md / USER.md edits: none | ``` 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__.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:** The slug transformation doesn't match Claude Code's internal convention on this host. **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//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 propose SOUL.md / AGENTS.md / USER.md edits routinely.** Once every few dumps at most, or if really needed. - **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.