Use case: Versioned catalogue

Situation

Your team maintains a growing set of reusable instructions for LLM agents: prompt templates, method descriptions, expertise summaries, tool configurations. Today these live as markdown files in a Git repo, or worse, as copy-pasted snippets across system prompts.

Problems compound quickly:

• No version history per individual artefact. Git tracks file changes, not semantic versions of a skill definition.
• No taxonomy. Skills, expertises and methods are mixed in flat folders.
• No drift detection. When a team member improves a method, other projects using the old version have no way to know.
• No composition. Assembling a profile from multiple skills requires manual concatenation.

---

Solution

Cortex stores every reusable instruction as a bloc — a typed, versioned, queryable artefact in a graph database. Blocs are organized into a taxonomy and composed into profiles.

Five bloc types

Cortex enforces a clear classification:

• skill — a practical capability (“write a deployment runbook”)
• expertise — deep domain knowledge (“GDPR data processing rules”)
• methode — a step-by-step process (“recette-QA in 7 axes”)
• tool — an external tool permission (“SurrealDB MCP server”)
• scope — a boundary declaration (“dev environment only”)

This classification is not cosmetic. Cortex uses it to compute profile DNA dimensions (diversity, methodology, expertise-vs-skill ratio) and to filter the catalogue for relevant injections.

Automatic versioning

Every bloc has a versionSemver and a contentHash. When you update a bloc:

1. Cortex computes the new content hash.
2. If the hash is identical, the update is ignored (idempotent).
3. If the hash differs, a change classifier determines whether it is a patch (wording), minor (additive content) or major (structural change).
4. The version is bumped accordingly.

You never need to manually manage version numbers.

Taxonomy navigation

Blocs belong to familles (top-level categories) and sous-familles (sub-categories). The taxonomy is modeled as graph nodes with belongs_to edges. The UI provides visual navigation; the API supports faceted search.

Drift detection

When a project instantiates a bloc (e.g. assigns skill X to a profile), Cortex takes an immutable snapshot. Later, if skill X is updated in the catalogue, Cortex can compute a drift report showing exactly what changed, field by field.

---

Key concepts involved

• Bloc — the five bloc types
• ATOM — the six-layer structure every bloc inherits
• Versioning — semver, content hashing, drift detection
• HYOS profile — how blocs compose into agent identities
• Divergence — comparing catalogue states across instances

---

Example flow

Scenario: a team managing a compliance catalogue with 50 blocs.

1. Ingestion — The team ingests 50 blocs via the REST API (POST /api/blocs) or MCP (cortex_ingest_bloc). Each bloc is validated against the HyosBlockV1Schema, assigned a content hash and stored at version 1.0.0.

2. Taxonomy — Blocs are organized under familles like “compliance”, “engineering”, “data”. The taxonomy graph enables navigation: “show me all expertises in the compliance famille”.

3. Profile composition — The team creates a “GDPR Auditor” HYOS profile that composes three expertises (GDPR rules, data mapping, breach notification), two methods (audit checklist, evidence collection) and one scope (EU data only). The profile DNA reflects high expertise, high methodology, narrow sector focus.

4. Version bump — A regulation changes. The team updates the “GDPR rules” expertise. Cortex detects a major change (structural content modification), bumps the version to 2.0.0 and records the field-by-field diff.

5. Drift alert — Project A instantiated the “GDPR Auditor” profile last month with expertise version 1.0.0. A drift report now shows that the expertise has diverged. The team decides whether to re-instantiate with the new version or keep the old one for ongoing audits.

6. Cross-pollination — Meanwhile, Project B independently created a similar “breach notification” expertise. Cortex detects a cross-pollination signal (semantic match, confidence 0.87) and recommends promoting the better version to the shared catalogue.