Upgrade Dependencies Safely with Recallable Agent Notes

You can upgrade dependencies safely when each bump starts with recall: your agent searches project memory for breaking changes, verified flags, and workarounds before it touches a version range. Store the lesson once, prune provisional holds after merge, and the next upgrade starts informed.

Why upgrade lessons vanish between sessions

Every upgrade session starts with an empty context window. Your agent sees the current manifest, the version you asked about, and the error on screen. It does not see the flag rename that broke the last bump, the workaround a teammate verified in March, or the test order that caught a silent behavior change.

That blank start is why the same dependency costs you twice. You bump a router from 4.x to 5.x, discover a renamed option, find the replacement flag, and merge. Three months later a different session bumps an adjacent package, hits the same renamed option through a shared plugin, and re-derives the same fix from changelogs. The lesson existed; it just lived in a closed conversation.

The mechanism matches why your coding agent forgets conventions: conversation context lasts only for its own lifetime. Compaction rewrites it to fit the window, /clear discards it, and a new terminal never had it. A verified workaround that lives only in chat history stays invisible to the next upgrade.

Rotation makes the loss worse. The engineer who handled the test-framework major moves to another service, the next bump runs under a different agent, and the peer-version constraint gets rediscovered by trial and error. Changelogs do not record what you verified.

The fix is to treat upgrades as recall-first work. One project memory holds breaking changes, verified flags, and workarounds as small retrievable facts. The next session searches that memory before it reads release notes, so it starts with your repo-specific answers instead of a blank terminal. The pattern mirrors shared team memory: store the lesson once, recall it every time the symptom returns.

The upgrade note shape: package, version range, breaking change, verified fix

Keep upgrade memory atomic: one fact per memory, scoped to the package and range it affects. A future session searches by package name and symptom, so each stored fact must answer one question without unrelated bumps.

Use four fields in the text itself. Name the package, name the version range, state the breaking change, and record the verified fix. Include the exact flag, config key, or command your repo used, plus the check that proved it. A note without the verification step reads like a rumor; a note with the check reads like an instruction.

Three hypothetical stored memories show the shape: example-router 4.x to 5.x drops the wildcard flag; use the new route pattern documented in the upgrade PR and verify with the router test suite. Or: example-test-runner 2.x requires the worker flag on this repo; without it the parallel suite flakes. Or: example-auth-helper 3.1 to 3.4 changes the token refresh default; pin to 3.0 until the refresh path is retested. Each is a retrievable memory, not a file your repo maintains.

Write for the query you will run later. Include the package name, the old flag, and the new flag in the same memory, because a future search may use any of the three terms. Add the one-line reason when you pinned on judgment so the next session does not unpin blindly.

Leave everything else out. Full changelogs, diffs, and log output already live in the repo history or the upstream release page. Do not store transcripts, one-off shell state, or credentials. The add API docs show the store shape.

Recall first to upgrade dependencies safely: search before research

To upgrade dependencies safely, change the order: recall first, then research. Before your agent opens release notes, it searches project memory for the package, the current range, and the symptom you fear. That search returns what your repo already verified, which upstream docs cannot know.

Setup follows the same path as any project memory. Your 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 to store, POST /search to recall, GET /list paginated with limit and offset to audit, PUT /update to correct, DELETE /delete/{memory_id} to remove. Pin the date-based X-Api-Version header on every call; the current version is 2026-09-25.

Take a hypothetical walkthrough. You plan to move example-router from 4.x to 5.x. The upgrade agent starts with one search combining package, range, and risk area:

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": "example-router 4.x 5.x wildcard flag route 404",
  "limit": 10
}
JSON

That query returns the stored breaking change and the verified replacement pattern from the prior bump. The agent verifies instead of discovering: it checks the range, applies the stored pattern, and runs the stored check before reading the full changelog.

Search twice when the first pass looks thin. Start with package plus range: example-router 5.x breaking change. Then add the flag or symptom: example-router wildcard 404 replacement. Short queries match atomic facts; pasted changelog paragraphs match nothing. If recall comes back empty, confirm the agent used the right project key — a wrong-project key makes memory look empty even when the notes exist.

Verify the habit the way you verify any agent memory. Ask for something only a prior upgrade could know, or call GET /list with a small limit and confirm the pin note is present. The list API docs cover that audit call.

Store the constraint, not the transcript

Store what the next bump needs, not how this bump felt. After your agent verifies a fix, distill it to the four-field shape and save each fact separately. A transcript-style memory that mixes three packages, two guesses, and one verified flag forces every future search to return the bundle and leaves the agent guessing which part still applies.

Write one memory per decision. A hypothetical bump to example-test-runner might produce three memories: the worker-flag requirement, the suite that verified it, and the peer-range conflict that blocks unpinning. Each states package, range, and evidence in one or two lines.

Send them with POST /add against the same project key your agents share:

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": "example-router 4.x to 5.x: wildcard flag removed, routes return 404. Use the new route pattern from the merged upgrade PR. Verified with the router test suite."
}
JSON

Keep provisional notes labeled as provisional inside the text. When you pin while waiting on upstream, say so: pinned to 3.0 pending upstream refresh fix; retest after 3.5. When a workaround is branch-specific, say which branch verified it. The label tells the next session whether the constraint is permanent or a temporary hold it should retest.

Count the habit so it stays cheap. One /add call that extracts five memories counts as five adds, and retrieve counting is tiered so the first 10 memories count as one request. Small atomic facts plus narrow limit values keep both counters low. To upgrade dependencies safely across many small bumps, you want many small facts, not a few long essays.

After the PR merges: update or delete provisional notes

Upgrade memory rots without upkeep. Upstream ships the fix you waited for, a major stabilizes, a temporary pin becomes the permanent floor. An agent that follows a stale pin trusts it with the same confidence as a fresh breaking-change warning, so maintenance is correctness work.

Correct with PUT /update when the fact still applies but the detail moved. The replacement flag gained a shorter form, the required peer minimum rose, the verification command changed packages, the hold version lifted from 3.0 to 3.5. Update the single memory in place. Do not add a second memory that contradicts the first; competing facts split future recall and push the choice onto an agent mid-bump.

Delete with DELETE /delete/{memory_id} when the note no longer applies. The upstream refresh fix shipped and you retested, the temporary pin merged and the range moved, the workaround branch closed. Stale pins hurt more than missing pins because the agent still obeys them and holds back a bump that is now safe. Removal is the fix. The delete API docs show the removal shape; prefer selective deletes over a full wipe so good constraints survive while expired holds go.

Run a short audit with GET /list after each merged upgrade PR. Pull the first page with limit=20, scan for the package you just touched, and resolve duplicates on the spot. Merge two memories that state the same flag in different words. Delete the provisional hold the merge just resolved. Confirm the surviving facts still name the right range. Have the review agent check upgrade PRs against the same memory so repeat findings get flagged before merge.

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. Inside that boundary the project is the scope, so one repo gets its own upgrade notes. Projects are unlimited on every plan, so a per-repo split keeps package recall precise.

A repeatable upgrade checklist

Use the same loop for every bump so recall compounds. Each step maps to a memory operation your agent already has.

1. Search memory for package plus current range before reading release notes.
2. Search again with flag or symptom terms if the first pass looks thin.
3. Note the stored breaking changes and verified checks in the session plan.
4. Run the bump and the stored check; record any new breaking change the same day.
5. Store each new fact atomically with package, range, change, and verified fix.
6. Mark temporary pins as provisional with the retest condition in the text.
7. After merge, update changed facts and delete expired holds, then re-list to confirm.

Adapt the checklist to bump size without skipping recall. A patch bump still gets steps one and two; a two-line search costs less than a revert. A major bump gets the full loop plus a second pass on the stored notes.

Close each upgrade by confirming three things: the suite result, the stored facts match the merged range, and each provisional note names its retest version.

FAQ

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