agent's clause extraction silently used the cached version - the counterparty re-uploaded and the agent never...

TL;DR The counterparty re-uploaded the contract under the same filename and the agent happily analyzed the cached old version, never re-parsing. Key your extraction cache on a content hash of the file bytes, not the filename, verify the hash at extraction time, and invalidate the cache on every upload event. Same name does not mean same document.

The symptom in your logs:

extraction complete in 0.4s using cached parse (hash check skipped)

Steps

1. Confirm you are reading stale data. Hash the file on disk and compare it to the hash stored with the cached parse.

Command: compute a SHA-256 of the uploaded file and compare it against the cached record's hash. Expected: the hashes differ, proving the file changed while the cache key, the filename, stayed the same.

1. Change the cache key from filename to content hash. Store parses under the SHA-256 of the file bytes so a re-uploaded file can never collide with the old parse.

Expected: the re-uploaded contract misses the cache and gets parsed fresh.

1. Add a verification step at extraction time: re-hash the file right before reading the cache and refuse to use a cached parse on a hash mismatch, logging the invalidation.

Expected: any future re-upload triggers a fresh parse with a log line saying the cache was invalidated, never a silent reuse.

1. Wire cache invalidation to the upload event itself, so the old parse is dropped the moment a new file lands, before any agent touches it.

Expected: uploading a new version immediately clears the old parse, and the next extraction starts clean.

Use this when

• Re-uploaded documents produce identical extraction results despite known changes
• Extraction of a new version finishes suspiciously fast
• Your cache key is a filename, path, or document title
• Multiple versions of a contract share a filename like Contract_FINAL.pdf

Not for this skill when

• The file truly did not change, verify the hash before assuming staleness
• The wrong document was uploaded, that is an intake problem, not a cache problem
• Your pipeline has no cache and re-parses every time, look at the parser instead
• The parse is fresh but wrong, which is an extraction quality issue

Variant phrasings

• agent used the cached version after the counterparty re-uploaded
• extraction cache keyed on filename served stale contract text
• how to invalidate document parse cache on re-upload
• agent never re-parsed the new contract version
• stale cache making the agent analyze the old agreement

Why it happens

Filenames are not identities. "ContractFINALv2.pdf" gets overwritten by "ContractFINALv2.pdf" constantly, and a cache keyed on the name cannot tell the two apart. The agent asks for a parse, the cache says it already has one for that name, and the new bytes are never read. Everything downstream is then correct analysis of the wrong document, which is worse than an error because nothing looks broken.

Edge cases

• Two uploads with identical bytes legitimately share a parse, content-hash keys handle this correctly by hitting the cache.
• Metadata-only changes, like a new upload timestamp, should not invalidate the parse, hash the file bytes, not the file record.
• Concurrent uploads of different versions need per-version cache entries, key on hash and keep both parses until the old version is retired.
• If your storage layer deduplicates by hash already, you may get this behavior free, verify rather than assume.
• Log every cache invalidation with both hashes so you can audit which version was actually analyzed for any given extraction run.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_MhkDEceEloMMH--kppgioA