Refactor Legacy Code with Agent Memory That Remembers

You can refactor legacy code over weeks without re-explaining the constraints every session. Seed the brief once in agent memory, make every session recall before it edits, and record each verified decision as the work lands.

Why long refactors lose their reasoning between sessions

A legacy refactor that spans weeks lives in more sessions than any context window holds. Each new terminal starts blank: the agent sees the files you point it at and nothing you told last week's session. It is why conventions vanish between sessions — context stays in closed chat history unless you store it outside the conversation.

Compaction and session resets do the rest of the damage. When a long session compacts, the summary keeps recent edits and drops the rationale behind them. When you run /clear or open a fresh terminal, even the summary is gone — and a different agent next week never saw any of it. The fix for Claude Code context compaction explains why only recall from outside the conversation survives these resets.

So the same questions get re-decided. The agent proposes renaming the boundary you agreed to keep, re-tries the migration order that failed in week two, or re-verifies a build sequence from scratch. When you refactor legacy code across calendar time, you pay for rediscovery in sessions, not in lines changed.

The fix is to keep the reasoning outside the conversation. One project memory holds the brief, the constraints, and each verified decision in retrievable form. Every session searches that memory before touching files, so week-four work starts from week-one reasoning instead of from zero.

What to store: constraints, decisions, verified steps, gotchas

Keep refactor memory small and atomic: one fact per memory, written the way you want it returned. The next session needs the rule plus the reason, not a transcript of the afternoon you found it. Four kinds of facts cover nearly every legacy refactor:

• Constraints — lines the work must not cross: module boundaries that stay public, callers that cannot change, deployment ordering rules.
• Decisions — choices already made: which pattern the new code follows, which scope each week covers, what you deferred.
• Verified steps — commands and sequences that worked: the test invocation for a package, the migration order, the flag combination.
• Gotchas — traps that wasted time: the file that looks dead but loads at runtime, the test that passes alone and fails in the suite, the error that points away from its cause.

For a hypothetical billing-module refactor, that is four separate memories. billing totals module keeps its public function names — three external callers import them states the constraint. week-two scope covers the totals module only, reporting module deferred to week four states the scope. billing tests pass only under the full suite command recorded in the week-two session and billing legacy helper looks unused but is imported at runtime by the nightly job record the verified step and the gotcha.

Leave everything else out. Full diffs, file contents, and logs already live in the repo. Temporary session state, single-session port numbers, and unproven guesses have no reuse value. Never store secrets, tokens, or credentials in memory.

Write each fact the way a future session will search for it. Include the module name, the keyword the next debugger will type, and the one-line reason. A bare rule gets re-litigated; a rule with scope and cause sticks.

Seed the refactor legacy code brief on day one

Day one is the cheapest time to write memory, because the plan is explicit and nothing has been tried yet. Before any file changes, store the brief: what the refactor covers, what it must not break, and the order the work runs in. Later sessions inherit this brief through search instead of reconstructing it from diffs.

Setup follows the same path as any project memory. The agent uses a project key with the ak_ prefix against the data plane at https://api.memory.audaxic.com. The API is mem0-like: POST /add stores, POST /search recalls, GET /list paginated with limit and offset audits, PUT /update corrects, DELETE /delete/{memory_id} removes. The add API docs show the request shape.

Seed the brief with one /add call per fact, not one call holding the whole plan:

curl -X POST https://api.memory.audaxic.com/add \
  -H "Authorization: Bearer ak_YOUR_PROJECT_KEY" \
  -H "X-Api-Version: 2026-09-25" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "messages": [
    "Refactor brief, billing module: totals module first, reporting module deferred to week four.",
    "Constraint: billing totals keeps its public function names — three external callers import them.",
    "Constraint: billing migrations run after the backfill — running before broke the last deploy.",
    "Gotcha: billing legacy helper looks unused but is imported at runtime by the nightly job."
  ]
}
JSON

Each message holds one atomic fact with its scope attached. One /add call that extracts five memories counts as five add requests, so four facts cost four adds against the Hobby tier's 10,000 per month. Pin the date-based X-Api-Version header — the current version is 2026-09-25 — so automation surfaces version drift instead of changing behavior mid-refactor.

Confirm the seed landed before editing starts. Call GET /list with a small limit and check that each brief fact is present and worded for retrieval. This seed pass takes minutes and every later session searches against it.

Session loop: search first, edit second, record third

Every refactor session follows the same three moves. Search memory for the module, the constraint, and the area about to change. Make the edits with the recalled rules in view. Record anything new the session verified — a decision, a passing sequence, a fresh gotcha — before the terminal closes.

The opening search combines module name, area, and intent:

curl -X POST https://api.memory.audaxic.com/search \
  -H "Authorization: Bearer ak_YOUR_PROJECT_KEY" \
  -H "X-Api-Version: 2026-09-25" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "query": "billing totals module public names migration order",
  "limit": 10
}
JSON

That query returns the brief facts the current conversation never saw: the naming constraint, the migration ordering rule, and the deferred scope. The agent now checks instead of guessing — it keeps the public names, runs migrations after the backfill, and leaves the reporting module alone. The search API docs cover recall queries, and the same recall-first ordering helps when you recall past incidents before investigating.

Search again after each failed attempt, not once per session. When a rename breaks a caller or a test order fails, search the failure you just observed: billing nightly job legacy helper import. The second query often surfaces the gotcha the first query missed. Short queries over atomic facts beat pasted stack traces.

Close the session with the write-back. Add one memory per new lesson with the module name in the text, and search first to avoid storing a duplicate. The pass takes minutes. Skip it and the next session pays the same discovery cost you just paid.

Weeks later: update decisions that changed, delete what landed

Refactor memory rots without upkeep, because plans change and finished work stops being relevant. A scope decision from week two misleads in week five if the reporting module moved earlier. An agent follows a stale memory with the same confidence as a fresh one.

Correct with PUT /update when the fact still applies but the detail changed. The deferred module moved into week three, the test command gained a flag, the migration step added a precondition. Update the single memory in place. Do not add a second memory that contradicts the first; competing facts split future recall. The update API docs show the correction shape.

Delete with DELETE /delete/{memory_id} when the fact no longer applies. The totals module already landed, the temporary shim was removed, the freeze on renaming expired. Finished work is noise: every landed fact a search returns takes attention from the facts that still constrain the work. Stale facts hurt more than missing facts because the agent still acts on them.

Run a short GET /list pass at the pace of the refactor: pull 20, scan for duplicates, merge contradictions, delete what landed. Data stays isolated per organization with namespace-scoped vector search, customer data is never used for training, and servers run in the US and EU. The project key therefore returns this refactor's facts and nothing else. Projects are unlimited on every plan from Hobby through Enterprise, so a per-module or per-repo split costs nothing extra and keeps recall precise.

Verify: recall a constraint the agent never re-explored

Verification is a recall test, not a feeling. Open a fresh session — or switch agents — and ask for something only the stored refactor brief could know. If the agent returns the constraint with its reason, the loop works. If it re-derives the answer from the code, the loop is broken.

A concrete check: in a new terminal on the same project key, search for the naming constraint without opening any files. The stored fact should name the totals module, the three external callers, and why renames are off the table. A second check: ask the agent which scope the current week covers before it reads the repo. Totals module only, reporting deferred is a memory answer; anything else means the brief never landed or the agent never searched.

When recall comes back empty, check the mechanics in order. Confirm the agent searched before reading code, confirm it used the right project key — a wrong-project key makes memory look empty — and confirm the fact text contains the keywords the query uses. Retrieves are tiered: the first 10 memories count as one request and each additional 10 as one more, so verification searches with a small limit stay cheap against the Hobby tier's 1,000 monthly retrieves.

Repeat the check after compaction, after /clear, and after switching tools. Recall lives outside the conversation, so it survives all three while chat context does not. The agent that passes all three reads the constraint, applies it, and moves on. That is the payoff: you refactor legacy code once per decision, not once per session.

FAQ

Written by Efe — Oct 11, 2026 · More articles · X @AudaxicTech