Serena refresh

Serena Refresh

Keep Serena's memory layer honest. The symbol index does not need refreshing: find_symbol and find_referencing_symbols read current files through the language server, so navigation already reflects new code. What goes stale is the human/agent-authored markdown under .serena/memories/ — the execution_path note still describing the old flow after a refactor, the structure note that never heard about a new package. Because the activate hook reloads those into every session, a stale memory is worse than a missing one: it is confidently wrong, every session, until corrected. This skill finds the drift and rewrites only the affected memories.

The engine is git. Scope the work to what changed since the last refresh, rather than re-reading the whole repo (which would just be onboarding again).

Step 0: Preconditions

1. Serena loaded? Confirm mcp__serena__* tools exist this session. If not, Serena isn't connected — point the user at setup (serena-onboard).
2. Onboarded? check_onboarding_performed, or confirm .serena/memories/ has .md files. If the project was never onboarded, this is the wrong skill — hand off to serena-onboard for a first pass.

Step 1: Scope the refresh against git

Run from the repo root:

bash scripts/refresh_scope.sh

It resolves a baseline ref (the .serena/last_refresh marker if present, else it asks you to pass one), diffs it against HEAD ignoring .serena/ itself, and prints: changed files, changed top-level areas, manifest/dependency changes, the current memory list, and a heuristic shortlist of memories that mention a changed area.

If there's no marker, pass a sensible baseline explicitly — the last release tag, the onboarding commit, or a date ref:

bash scripts/refresh_scope.sh <sha-or-tag>
bash scripts/refresh_scope.sh 'HEAD@{2 weeks ago}'

If the script reports no commits since the baseline, the memories are current; stop and say so (don't invent work).

Step 2: Confirm and rewrite only what drifted

The shortlist is a heuristic, not a verdict. For each candidate, and for the always-worth-checking execution_path and structure memories:

1. Read the current memory (read_memory).
2. Check current reality for the changed area using Serena symbol tools (get_symbols_overview, find_symbol, find_referencing_symbols), not grep. For dependency/manifest changes, read the manifest to update tech_stack.
3. If the memory is now inaccurate, rewrite it (write_memory overwrites). Keep it tight; don't pad. If it's still accurate, leave it untouched — needless churn erodes trust in the layer.

See references/refresh-playbook.md for the path-to-memory mapping and the handling of the trickier cases below.

Step 3: Handle new, removed, and renamed subsystems

• New subsystem (a new package/service/module that no memory covers): add a focused memory for it and add a one-line pointer from core and structure.
• Removed code: if a memory describes something now deleted, fix the memory or remove it (delete_memory). A memory pointing at code that no longer exists is a trap.
• Renamed/moved: update names and paths in every memory that referenced the old location. The diff's R/D/A status lines flag these.

Step 4: Advance the marker

Once the affected memories are correct, move the baseline forward so the next refresh is scoped from here:

git rev-parse HEAD > .serena/last_refresh

Step 5: Optional — restart the language server

Rarely needed, but after a branch switch or a dependency bump the language server can serve stale or empty symbol results. If navigation looks plainly wrong (known symbols not found, references missing), call Serena's restart_language_server tool, then re-verify. Don't do this routinely; it costs a cold re-index.

Step 6: Report

Summarise: the baseline and HEAD you compared, which memories you changed and why, any added/removed, and confirmation the marker advanced. Be explicit about what you deliberately left unchanged so the user can sanity-check your scoping.

Notes

• Surgical by design. If you find yourself rewriting most memories, either the baseline was too old (huge diff) or the codebase genuinely turned over — say so, rather than silently doing a full re-onboard under a refresh label.
• The marker may be gitignored. .serena/ is usually untracked, so the marker is local state. That's fine; it only needs to persist on this machine.
• No marker and no obvious baseline? Ask the user when they last onboarded or which release to compare against, rather than guessing a ref.