Skip to content

Provenance and currency

Cortex contains authored records, private source material, and generated indexes with different trust and freshness properties. Treating them as one layer would make a plausible query result look more authoritative than it is.

Provenance layers

Layer Example Authority Currency signal
Source publication A paper PDF identified by DOI and drive_id The publication DOI and source file
Reviewed Cortex record A summary with status: reviewed Repository review at a Git commit Commit history and status
Draft Cortex record A stub or draft summary Work in progress Status and open review
Derived retrieval state Kuzu graph, vector index, document chunks The ingestion run Source commit, run time, flags, and model configuration
Generated answer Output from graph or ask No independent authority The exact local store and query invocation

The durable citation target is the source publication. The reviewed Cortex summary explains its ecosystem relevance. The derived layers help discovery; they do not upgrade a draft or generated statement into reviewed guidance.

What reviewed means

reviewed records have moved beyond a generated template and draft editing. Their bibliographic identity, substantive summary, limitations, and relevance have been checked through repository review. The status does not claim that the paper itself is correct, that every graph relationship is exhaustive, or that the record will remain current indefinitely.

Both the index entry and summary frontmatter carry a status. They should agree. The validator checks each value but currently does not enforce equality, so the review diff remains the final gate.

Recording a reproducible refresh

A useful ingestion record states:

  • the HSSMCortex commit used as input;
  • the selected COGNEE_DATA_PATH or default store;
  • whether PDFs were included;
  • any paper filter, reset, or lightweight-graph flags; and
  • when the run completed.

Without that context, a user can establish that a local query works but not which revision of the research record it represents.

Public-site boundary

The documentation site publishes operating guidance and contracts. It does not publish private PDFs, local database files, proposal histories, unreviewed paper content, internal implementation plans, or unfinished taxonomy and curated-guide stubs. Publication is an explicit documentation decision, not a side effect of placing a file somewhere in the repository.