exocortex-adapter-mintlify

The reference Exocortex Ingestion Protocol adapter: a Mintlify docs site becomes a source of typed graph memories. Authors opt pages in with an exocortex: frontmatter block; the adapter watches the docs git repo and submits signed IngestBatch rows to the Exocortex backend. Deterministic end to end — no LLM anywhere in this code path.

The design invariant: the docs repo is the source of truth for docs. The graph is a derived, structured index of the parts of the docs that map onto the org's ontology — never a copy of the prose.

The frontmatter contract

---
title: "How the auth service calls the policy engine"
exocortex:
  id: "myorg.integration.auth-policy-bridge"   # REQUIRED, stable across renames
  memory_type: "Integration"                   # REQUIRED, from the org's pack
  visibility: "Org"                            # OPTIONAL, default Org
  entities:                                    # OPTIONAL; each becomes a draft
    - { type: Technology, name: "AuthService" }
  relationships:                               # OPTIONAL; edges between entities
    - { from: "AuthService", kind: IntegratesWith, to: "PolicyEngine" }
  references: ["services/auth/handler.py"]     # OPTIONAL; rides content
  tags: ["auth", "policy"]                     # OPTIONAL
  runbook_steps:                               # OPTIONAL; Precedes chain
    - { id: "step-1", name: "Fetch snapshot" }
  deprecates: ["myorg.integration.legacy-auth"] # OPTIONAL; tags the page
---

Pages without an exocortex: block are skipped silently — absence is a valid signal. Everything is validated locally (validate subcommand, below) and re-validated by the kernel, which is the one rulebook.

Run

exocortex-adapter-mintlify \
  --docs-repo-path ~/code/myorg-docs \
  --source-uri mintlify://myorg/docs \
  --org-id myorg \
  --backend-url http://exocortex-node:8080 \
  --hmac-key-path ~/secrets/exocortex-mintlify.key

Every parameter is also env-driven (DOCS_REPO_PATH, SOURCE_URI, ORG_ID, BACKEND_URL, HMAC_KEY_PATH, …) — zero hardcoded org identifiers. --once runs a single poll iteration (cron-friendly); the durable cursor (--cursor-path) holds the last fully-submitted SHA and never advances past unsubmitted pages: transient failures back off and retry, and crash-replays deduplicate server-side on (producer_id, batch_id).

Validate in docs CI

Fail a docs PR before the graph ever sees it:

exocortex-adapter-mintlify validate .   # exit code = number of invalid blocks

Semantics (the load-bearing details)

• Identity is stable across page renames. Each page memory carries ExternalKey { table_uuid: <repo uuid>, logical_pk: <exocortex.id> }; the kernel derives the MemoryId from those coordinates (R-T18a). Renaming a file changes nothing; changing the id creates a new memory and orphans the old one.
• Entities are join points. Declared entities become their own drafts under the declared type (which must be a pack memory type), keyed entity:<type>:<name> — pages sharing an entity converge on the same memory, and declared relationships become edges between them.
• Runbooks become chains. Steps emit Workflow drafts joined by Precedes edges in listed order.
• Deletions close, never erase. A deleted page resubmits its identity with valid_until set — bi-temporal history survives.
• Snapshots are commits. snapshot_id is the git SHA; schema_hash is the BLAKE3 of the frontmatter schema version, so a schema bump forces a full re-ingest server-side.

Documented deviations from the PRD (v1)

• references ride the memory's content text (the wire draft has no files-involved field; the server-side extractor picks file paths out of content).
• deprecates become deprecated:<id> tags rather than Replaces edges: the wire's to_memory_id needs the successor's kernel-assigned id, which a wire-only adapter cannot compute. Revisit with an id-resolution RPC or a kernel-linked validator binary.
• No MDX body parsing (pulldown-cmark dropped): nothing in the contract consumes the prose.
• exocortex-wire is a path dependency during development; the published crates.io 0.1.0 predates signed registrations. Flip to a versioned dep when wire republishes.

License

AGPL-3.0-or-later, matching the core repo.