Scan history
Every successful rescan archives the graph it replaced, so you can compare architecture over time instead of only inspecting the present. A snapshot is one complete scan; the graph and its evidence describes what it holds. Three tools read the history.
| Tool | CLI | Answers |
|---|---|---|
list_snapshots | list-snapshots | The retained scan history for a project. |
snapshot_diff | snapshot-diff | What changed architecturally between two scans. |
architecture_trends | architecture-trends | How metrics moved, plus generated release notes. |
Retained snapshots
Knossos keeps the active graph in its original normalized tables for fast, compatible reads. Before a successful rescan replaces that graph, it captures the previous active scan as an immutable, versioned JSON fact set in the same transaction.
The default retention is five prior snapshots. Set snapshot_retention from 0 through 20 in knossos.json, or with --snapshot-retention on knossos scan; zero disables history. Activation prunes older archives and their unreferenced completed scan records atomically.
List available metadata with:
knossos list-snapshots project_... --jsonOr call list_snapshots over MCP. Results distinguish the active normalized scan from retained archives (active, retained) and include scanner and config fingerprints, timing, fact_count, byte_size and complete_archive.
Each fact table is capped at 300,000 rows and a complete archive at 600 MB of uncompressed payload. The row cap is what keeps the quality gate, which holds the baseline and the active graph in memory at once, inside the core's 1G. An oversized graph retains an explicit incomplete metadata record instead of silently presenting partial facts as complete. Incomplete snapshots are useful for audit timing and fingerprints but are not eligible for full snapshot diffs.
Snapshot diff
snapshot_diff compares two complete snapshots using stable persisted facts. Either side may be a retained scan ID; active selects the project's current normalized graph.
{
"project_id": "project_...",
"from_snapshot": "scan_...",
"to_snapshot": "active",
"max_changes": 25
}The CLI equivalent is:
knossos snapshot-diff project_... scan_... active --max-changes=25 --jsonThe changelog separates added, removed, changed, and moved components along with relationship, role, boundary, membership, and diagnostic changes. Relationships are matched by kind, source and target rather than by where they are written, so a call that only moved, because a line was inserted above it, is listed under moved with its old and new line instead of as removed and added. A relationship whose confidence, origin or attributes changed is changed; one more or one fewer occurrence of the same relationship is added or removed. It also counts confidence increases and decreases. Every category has deterministic ordering, while max_changes applies a global output cap and reports both the total and reported counts.
A removed component becomes a rename candidate when exactly one added component has the same kind and display name. Candidates are labelled possible and name the heuristic (exact_kind_and_display_name). They are navigation hints that assert no identity.

Only complete archives can be diffed. Oversized or unavailable retained facts return an explicit error instead of silently comparing partial data. Static facts may still miss runtime-generated architecture.
Trends and release notes
architecture_trends reports a bounded chronological series across the active and retained snapshots. Each complete point contains component, relationship, role, boundary, and diagnostic counts plus static cycles, maximum degree, diagnostic severity, and unreferenced-candidate metrics. A loop closed only by type-only imports (a TypeScript import type) is not counted as a cycle, as in dependency_cycles, so metrics.cycles can be lower than a trend computed before that rule, for the same graph.
knossos architecture-trends project_... --limit=10 --jsonAdd --release-from=scan_... to compare that retained baseline with the active graph and include deterministic Markdown release notes:
knossos architecture-trends project_... \
--release-from=scan_... --limit=10 --jsonRelease notes include bounded structured change details alongside counts for components, relationships, moves, and confidence changes. When more than 100 details exist, the Markdown explicitly reports truncation.
The figures of each complete retained snapshot are computed once and cached in the graph database (snapshot_metrics rows, keyed by the archive and the code that computed them), so a trends call is not a pure read: the first call over a snapshot writes its row, and later calls read it instead of decoding the archive. A write that would wait on a running scan is skipped.
Incomplete retained snapshots remain visible as incomplete timeline points but are not interpreted as metric data. Scanner or configuration fingerprint changes are included because they can affect comparability even when source architecture did not change.