---
name: claude-session-memory-orchestration
description: Project memory shared by gu and Claude Code. Every step of a task (the request, the plan, commands and their results, edits) is saved automatically, so unfinished work can be picked up in either tool. Use when a "Resume" block or memory snapshot appears, when the user asks to continue or resume, when starting work with several steps, and before searching the repository for something memory may already know.
---

# Session memory

Hooks save your work as it happens, in both gu and Claude Code: each request, your plan, every
command with its result, every edit (scripted ones too), and whether the turn finished or was cut
off. **You do not save steps, edits or checkpoints yourself.** Your part is below.

## What you will see

- **`## Resume — task #N (tool, state time)`** at the start of a session, and again when the user
  says "continue" or "resume": the latest unfinished work in this project, from either tool. It
  lists the task, goal, plan (`✓` done, `→` in progress, `○` not started), last command and its
  result, files touched, and the next step. `interrupted` = the turn was cut off; `unfinished` =
  still running elsewhere or closed without finishing.
- **`## Memory snapshot`**: tasks in progress, requirements that match the request, recent edits.

## Rules

1. **Resume block.** If the request carries on that work, or the user says continue/resume, start
   from **Next** (the first step not `✓`) and say so in one line, e.g. *Continuing task #446 from
   "gu commands".* Look at the files it lists before changing them, do not redo `✓` steps, and if
   the last command failed, start by understanding why. If the request is about something else,
   ignore the block and do not mention it.
2. **Keep a plan for work with three or more steps**, and update it as each step starts and
   finishes; that plan is what a resume continues from. If you have a to-do tool, use it: it is
   saved automatically. If you do not, call `save_progress` with the whole plan each time.
3. **Switching task?** Call `update_task` on the task you are moving to (status `in_progress`,
   `process_state` = what you are about to do). The steps after that are filed under it. A task
   named in the user's request (`#N`, `GH #N`) is picked up without this.
4. **Memory before a wide search.** Before searching the whole repository, try
   `find_requirements`, `search_code_changes` and `line_hints`, then open only the files they name.
   Line numbers from memory are hints: check them before you quote them.
5. **Finished a task?** `update_task` with status `done` and a `next_action` for any follow-up.

## Tools (`local-memory-sqlite` MCP server)

| Need | Tool |
| --- | --- |
| The whole resume state: full plan, last commands, files | `resume_task` |
| Save your plan when you have no to-do tool | `save_progress` |
| Requirements and tasks | `find_requirements`, `search_tasks`, `get_task`, `list_tasks` |
| Create or move a task | `save_task`, `update_task` |
| Where something was changed or found before | `search_code_changes`, `recent_code_changes`, `line_hints`, `search_steps` |

`save_step`, `save_code_change` and `save_checkpoint` also exist. The hooks already do their job,
so use them only for something a hook cannot see, such as a decision worth keeping.

If the MCP tools are not connected, say so in one line and carry on: the hooks still save the work.

## Good to know

- Memory lives in `.claude-memory/` at the project root (the git root), one database per project,
  whichever subfolder you are working in.
- Secrets are masked before they are stored, but do not write keys, tokens or passwords into a
  plan, a task or a summary.