StateAssure

Scan millions of Windows records. Map AI memory fast.

13.1 million filesystem records scanned in 58.4 seconds on the v0.2 validation host. That is a measured local result, not a universal benchmark. Storage, filesystem cache, antivirus, access controls, and backend availability all affect runtime.

StateAssure is a high-speed, read-only Windows AI memory scanner written in C++20. The public preview tears through filesystem metadata and turns a Windows user profile or local fixed volumes into an immediate inventory of known agent memory, semantic indexes, session stores, and code knowledge databases. Every result includes its location, logical size, newest observed write time, confidence, and coverage evidence.

Use it for agent memory discovery, a local AI memory audit, migration planning, incident response, storage review, or simply answering: where did all these coding agents put their memory?

What it finds

The embedded detector pack recognizes filesystem layouts for:

• Codex memory catalogs
• Claude Code project memory
• CTX session indexes
• GBrain knowledge indexes and historical backups
• QMD semantic indexes
• Graphify graph indexes
• GitNexus code indexes
• codebase-memory-mcp stores
• MemPalace configuration, conversation memory, and historical stores
• brain.md repository memory
• Headroom session-compression stores
• conservative generic Markdown roots such as memory/MEMORY.md and memories/MEMORY.md

StateAssure identifies these systems from path names, adjacent markers, and filesystem metadata. It does not open their stored prompts, memories, databases, embeddings, or index content. Run stateassure detectors to inspect the exact rules compiled into your executable, or read the detector reference.

Run it now

Download the Windows x64 executable and verify it against the checksum on the latest release. Then open PowerShell in the download directory and scan your Windows user profile:

.\stateassure.exe scan

The live console shows the scan stage, elapsed time, metadata work items, and completed roots or measured stores. It uses an honest activity indicator instead of inventing a percentage before the total filesystem work is known.

Create both machine-readable JSON and a polished Markdown Memory Case in the same pass:

$stamp = Get-Date -Format yyyyMMdd-HHmmss

.\stateassure.exe scan --root $env:USERPROFILE --backend auto `
  --json ".\memory-case-$stamp.json" `
  --markdown ".\memory-case-$stamp.md"

Need the widest local audit? Opt in to every local fixed volume:

.\stateassure.exe scan --all-fixed --backend auto

--all-fixed is never implied. StateAssure scans the current user profile by default and widens its boundary only when you ask.

Scan output

Interactive results are grouped into narrow-friendly location cards. Every detected location keeps these facts together:

• system family and confidence
• full local path
• logical bytes
• file and folder counts
• newest observed filesystem write time
• warnings, access failures, skipped reparse points, and coverage status

JSON schema 1.1 is the authoritative automation format. Markdown Memory Cases are durable human reports for review and handoff. If cancellation occurs before a location is measured, its fields say not measured instead of pretending the value is zero.

Markdown Memory Cases contain sensitive local inventory, including paths, product names, timestamps, and sizes. Review them before sharing. They never contain memory, prompt, database, embedding, or index contents.

Safety by construction

StateAssure is a metadata scanner. It does not:

• read memory, prompt, embedding, database, or index contents
• execute a discovered CLI, service, MCP server, or database
• initialize, synchronize, compact, reindex, move, quarantine, or delete data
• follow directory reparse points
• elevate itself
• scan network shares or WSL filesystems
• create hidden logs, upload reports, or transmit scan results

Reports are written only to an explicit --json FILE or --markdown FILE destination. StateAssure uses create-new semantics and refuses to overwrite an existing report, write through a reparse-point ancestor, or place a report inside a detected memory root.

Access failures and skipped reparse points stay visible. A partial scan is never labeled complete, and incomplete coverage is never treated as proof that a memory system is absent.

Commands

List the detector pack

.\stateassure.exe detectors

This prints the detector families and evidence rules without scanning the filesystem.

Scan selected roots

Repeat --root to scan an exact set of local directories:

.\stateassure.exe scan `
  --root "$env:USERPROFILE\.codex" `
  --root "$env:USERPROFILE\.claude"

--root and --all-fixed are mutually exclusive.

Scan options

Option	Meaning
--root PATH	Scan an explicit local root. Repeat the option to add roots.
--all-fixed	Scan all local fixed volumes. This is an explicit machine-wide opt-in.
--backend auto|mft|recursive	Select discovery. auto tries read-only NTFS MFT enumeration and falls back visibly when unavailable.
--threads N	Set the recursive worker count from 1 through 64.
--json FILE	Create an authoritative JSON report. The command fails if FILE exists.
--json -	Write authoritative JSON to standard output.
--markdown FILE	Create a human-readable Markdown Memory Case. The command fails if FILE exists.
--markdown -	Write the Markdown Memory Case to standard output.
--show-possible	Include lower-confidence candidates that need operator interpretation.
--help	Show command help.
--version	Show the StateAssure version.

For scripts, send one format to standard output:

.\stateassure.exe scan --root $env:USERPROFILE --backend recursive --json -

JSON and Markdown can be produced together, but only one may use standard output and file targets must be different. Report directories must already exist on a local filesystem.

How scanning stays fast

auto first attempts read-only NTFS MFT enumeration, then falls back visibly to the recursive metadata walker when raw-volume access is unavailable. Detector rules and the safety boundary are identical across both backends.

The fallback walker uses a bounded worker pool, per-worker coverage counters, a cheap directory-name prefilter, and avoids constructing paths or running directory-only rules for ordinary files. Its bounded last-in, first-out work queue drains deep branches before wide frontiers can consume unnecessary memory.

StateAssure deliberately does not ship a heuristic cache. Directory timestamps cannot prove that descendants are unchanged, so a shortcut cache could silently miss memory locations. A correct future incremental design requires validated NTFS volume identity and USN-journal continuity, including wrap, reset, rename, and invalidation handling.

Both enumeration paths retain explicit safety bounds. MFT discovery keeps at most 2,000,000 directory nodes. Recursive discovery permits at most 262,144 pending directories. An MFT limit failure triggers a visible recursive fallback. A recursive queue-limit result remains incomplete.

See Architecture, Performance and cache correctness, and the measured v0.2 validation record for the complete engineering detail.

Build from source

Requirements:

• Windows 11 x64
• Visual Studio 2022 Build Tools with the Desktop development with C++ workload
• CMake 3.24 or newer
• Windows SDK from the Build Tools installation

From a Developer PowerShell for Visual Studio:

cmake --preset windows-msvc-debug
cmake --build --preset windows-msvc-debug
ctest --preset windows-msvc-debug

cmake --preset windows-msvc-release
cmake --build --preset windows-msvc-release
ctest --preset windows-msvc-release

The Release executable is written to out\build\release\Release\stateassure.exe.

After tests pass, create a clean local package and SHA-256 checksum:

.\scripts\build-release.ps1

The script writes dist\stateassure.exe, dist\LICENSE, dist\NOTICE, and dist\SHA256SUMS.txt. The checksum file covers every packaged artifact. The script does not sign or publish the package.

Coverage and limitations

• Local Windows filesystems only. Network shares and WSL are outside the current scope.
• StateAssure does not intentionally request cloud-file hydration. Placeholder behavior has not yet been runtime-verified, so the public preview does not guarantee zero hydration.
• Raw-volume MFT access may be unavailable to a normal process. The recursive fallback and warning remain visible.
• No automatic elevation. Access-denied areas remain explicit gaps.
• Reparse points are reported and skipped.
• Detector markers can drift when third-party tools change storage layouts.
• Filesystem presence does not prove that a tool is configured, reachable, current, or semantically healthy.
• Logical size is not allocated size or unique physical storage. Hard-linked files can count more than once; alternate data streams are outside the current scope.
• Performance depends on filesystem type, entry count, storage, cache state, antivirus, access controls, and backend availability.

The v0.2 validation host scanned 13,129,805 user-profile records in 58,359 ms using the recursive fallback. A same-day run of similar scope took 146,187 ms. That variance is exactly why StateAssure publishes measured receipts instead of promising one universal speed. See the v0.2 validation record.

Exit status

Code	Meaning
0	The command completed and requested reports were emitted. Inspect JSON coverage before making an absence claim.
1	StateAssure could not validate or write a requested report.
2	The command line or selected root was invalid or outside the supported scope.
130	The scan was interrupted. Requested reports are still emitted with incomplete coverage.

A successful exit does not mean every root was accessible. Automation must inspect each coverage[].completeness value and the detection completeness flags.

Contributing and issues

Found a missed AI memory layout, a false positive, or a Windows filesystem edge case? Open an issue with the tool name, expected root shape, and metadata markers. Do not attach private scan reports or memory contents.

Focused pull requests are welcome. Build both configurations and run CTest before submitting.

License

StateAssure is licensed under the Apache License 2.0. See NOTICE for the copyright notice.