Memory Drift Diff

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:

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)

{
  "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.

Errors are not charged

Payment settles only on a successful answer. Any response with status 400 or higher (bad input, not found, upstream failure) is never settled.