# Memory Drift Diff

> "Between these two versions of an agent memory file, what lines and sections changed, how much churn is there, and did anything credential-like change?"

- Status: MCP package (hosted access coming soon)

## The question it answers

"Between these two versions of an agent memory file, what lines and sections changed, how much churn is there, and did anything credential-like change?"

## Use it when

- You keep a `MEMORY.md` or similar notes file for an agent and want a structured diff, not just a text patch.
- You want to spot sections that vanished or heavy rewrites ("high churn").

## Do not use it when

- The text contains secrets you cannot afford to leak. **Redaction is incomplete in this version** (see limits). Remove secrets before sending.
- The files are longer than 5,000 lines. The diff stops at line 5,000 without saying so.
- You need semantic judgement about whether a change is good or bad. It reports line changes and keyword categories only.

## Example call

There is no public HTTP route yet, so no curl example. Locally:
```bash
npx tsx src/cli.ts diff before.md after.md
```
MCP: `memory_diff {"before":"...","after":"...","label":"demo"}`; add `"jsonMode":true` for JSON documents. `memory_snapshot_diff {name, content}` stores a snapshot and diffs against the last one saved under the same name; `memory_list_snapshots` lists names.

## Example response (trimmed; real output from the package's own sample)

```json
{
  "tool": "memory-drift-diff",
  "version": "0.2.0",
  "mode": "text",
  "from": "demo:before",
  "to": "demo:after",
  "identical": false,
  "sha": { "from": "629b5bc7...", "to": "d7c1bd55..." },
  "stats": { "fromLines": 5, "toLines": 6, "added": 2, "removed": 1, "churn": 0.2727, "categories": { "content": 3 } },
  "sections": { "added": [], "removed": [], "changed": ["Memory"], "unchanged": ["(preamble)"] },
  "riskFlags": [],
  "unifiedPatch": "--- demo:before\n+++ demo:after\n # Memory\n - User: Alex\n-- Goal: ship agent tools\n+- Goal: ship agent tools hard this weekend\n ...",
  "changes": [
    { "type": "del", "line": "- Goal: ship agent tools", "oldNo": 3 },
    { "type": "add", "line": "- Goal: ship agent tools hard this weekend", "newNo": 3 }
  ],
  "payment": { "billing": { "sku": "memory_drift", "plannedPriceUsd": 0.02, "x402Enabled": false } }
}
```

## Data sources

None. Only the text you send. No network calls.

## Freshness and caching

Nothing is fetched. Snapshots saved through `memory_snapshot_diff` are kept on the machine running the tool with no expiry and **without redaction**, and are keyed by the `name` you give, so use a name no one else will use.

## Honest limits

- **Silent cut-off:** past 5,000 lines per side the diff is cut. A change at line 6,000 reports as not identical with 0 added and 0 removed. Known issue; a patch is not applied in this version.
- **Redaction gaps:** the patch and `changes` redact simple `key=value` / `key: value` secrets and a few token shapes (`sk-...`, `ghp_...`, `xox?-...`, AWS `AKIA...`). They do **not** catch `Authorization: Bearer <token>`, JSON-style `"apiKey": "..."`, or passwords in `postgres://user:pass@host` URLs. JSON mode returns values unredacted.
- Categories and risk flags are keyword guesses.
- Lines are compared exactly after trimming trailing spaces; a moved block shows as delete plus add.
- Only the first 400 changes (200 in JSON mode) are returned.