Salvor: giving coding agents a memory that lives in the repo

The problem

The code and the git history show what changed. They rarely show why. Which fix was tried and dropped, which rule only exists in someone's head, what was deliberately left for later. A fresh session doesn't have any of that, so it rediscovers it, argues with it, or quietly breaks it.

What Salvor is

Salvor is a repo-native knowledge layer for coding agents, released under the MIT license. Everything lives as plain Markdown in a .salvor/ folder, so it gets reviewed in pull requests and versioned with the code. There is no hosted service and no account.

The parts I use most:

• L1: a short note on the project's current state. Every session reads it first.
• L2: the longer record, with reasoning, history and rejected ideas.
• Learned failures: approaches that failed, written down so they aren't retried.
• Decisions and deferred findings: what was chosen and why, and what was parked rather than dropped.

New knowledge is captured with your approval: the agent asks before it writes a decision or a learned failure. Setup creates entry files for Claude Code, Codex and GEMINI.md-compatible clients, so the same memory works when you switch agents.

How I use it

At the start of a session the agent reads L1, then whatever else the task needs. After each milestone I have it update L1 and L2 and commit. When something fails in an instructive way, it goes in as a learned failure with the reason.

The biggest difference shows up in small project rules that never make it into the code. "Every page needs both language versions." "Bump the build number after each change." "This page must link to that one." Without memory, an agent gets these right sometimes. With them written down, it gets them right far more often.

What my tests showed

I ran field trials with the same tasks in three setups: no memory, a short memory file, and full Salvor. I also ran Salvor's own test suite locally. The full numbers are on the Salvor test page. In short:

• Full Salvor won both Codex trials or tied for first.
• It cost more: about 1.5–2× the tokens and 2–4× the time of running with no memory.
• The biggest gains came from rules that exist only in memory, like the ones above.
• On the suite, 186 of 186 unit tests passed.

I also ran blind question tests, planted false memories and tried an agent that was never told about Salvor. Those are in More Salvor tests.

A closer look: the live site trial

One trial ran on a live bilingual static site with games, Turkish and English pages, and ads behind a consent step. Codex worked in local copies of the real repository and nothing was deployed. It got five real tasks: add a new game in both languages, fix a reported layout bug, add a feature to an existing game, write deploy steps, and add an ad slot to a page. I wrote 25 checks before reading any output.

After an independent audit the scores were 17 of 25 with no memory, 19 with short memory and 24.5 with full Salvor. The difference came from things you only know if you've worked on the project before:

• Orphan pages. Without memory, the new game page got no links from the rest of the site, so visitors and search engines couldn't find it. With Salvor it got 16.
• Language leaks. Both setups without full memory loaded Turkish scripts on the English page. In one, the consent notice showed up in Turkish. Salvor used the English versions.
• Version numbers. The site needs a version bump after each change. No memory never bumped it. Short memory guessed. Salvor followed the project's own rule.
• Honesty about checks. None of the setups could open a browser, so none could see the layout bug. All three said "fixed", but only Salvor said it couldn't verify. It turned out the bug had already been fixed weeks earlier, so all three "fixed" a bug none of them had seen.

Two things temper this. Full Salvor took 17.8 minutes and 342k tokens, against 8 minutes and 209k with no memory. And the ranking depends on how the version-number checks are graded: read strictly by the letter of the rubric, the scores were 19, 22.5 and 20.5.

Where it falls short

• Reading a failure isn't the same as avoiding it. One task failed in every setup, even though the failure was written down.
• Agents edit the record. In 3 of 5 runs the agent changed an approved learned-failure entry to match its own change, without marking that it had.
• The state note goes stale. If L1 says "version 176" while version 177 is live, the next session starts with wrong information. I now run a small check at session start that compares L1's claims with reality and flags the stale ones.

Who it's for

If you work with agents on the same project across many sessions, it's worth trying. Start by writing down three rules your agents keep breaking. For one-off scripts it's more structure than you need.