Skip to content

Architecture

HSSMCortex separates durable, reviewable research records from the local systems that make those records searchable.

papers/index.yaml ─┐
paper summaries ───┼─> cortex-ingest ─> Cognee dataset
Drive PDFs ────────┘                     ├─> vector index
                                        └─> Kuzu graph
                                                │
                     alias registry ────────────┤
                                                v
                            search / graph / summaries / ask

Source records

papers/index.yaml registers each paper and points to its Markdown summary. The summary carries bibliographic, classification, graph, relevance, and review fields. A drive_id can associate the record with a private source PDF without placing that PDF in Git or on the documentation site.

Taxonomies and curated guides are separate authored source areas. They are not automatically public merely because they are tracked; incomplete stubs remain outside the site until reviewed and deliberately incorporated.

Ingestion boundary

cortex-ingest selects index entries, extracts committed summary bodies, and optionally downloads and extracts PDF text. It sends labelled text blocks to a Cognee dataset named hssmcortex.

The current runtime combines:

  • Anthropic for structured graph extraction;
  • FastEmbed for local embeddings;
  • Kuzu as the embedded graph backend; and
  • Cognee's local persistence beneath the selected data root.

The store is derived state. It can be refreshed or rebuilt from a documented source revision, but it is not a substitute for the reviewed Markdown record.

Query boundary

The four query modes expose different derived views:

  • search retrieves semantically similar chunks;
  • summaries retrieves document-level summaries;
  • graph uses extracted graph relationships; and
  • ask combines graph and summary context to answer a question.

All four depend on the content, configuration, and model behavior used when the local store was built. Important claims should be checked against the source paper and reviewed summary.

Entity-resolution boundary

Cognee can extract several surface forms for the same concept. Cortex resolves them after ingestion through exact matching, reviewed fuzzy and semantic proposals, and an alias registry. Graph mutation is isolated behind the GraphBackend protocol; Kuzu is the only implemented provider today.

See Entity resolution for the design and Resolve duplicate entities for the operator procedure.

Capability distribution

The repository also authors capability content for ecosystem agents. The Spine coordinates how that content is materialized into supported editors. This distribution surface is separate from the paper store: installing an agent skill neither populates Cognee nor grants access to private research sources.