Workflows: Ingest and curate context

Browse the taxonomy, ingest new statements, edit metadata, and delete safely.

Prerequisites

• context:read to browse and search. context:write to ingest, edit metadata, or delete. acaso_os:admin implicitly satisfies both.

Browse the taxonomy

Open /context. The left panel calls GET /v1/graphium/taxonomy and renders the family → genus tree with running counts of specimens and statements. Clicking a family or genus filters the right panel to that branch.

Search statements

Two modes share the same search bar:

• Vector search (default) — POST /v1/graphium/search with {query, family?, genus?, cross_family?, limit}. Returns cards ranked by cosine similarity with classification badges and similarity score.
• Recall (toggle) — POST /v1/graphium/recall for non-vector, structural lookup by family/genus/specimen.

Tip: Prefer the explicit family= and genus= filters over cross_family=true. The explicit form hits the composite (tenant_id, family_id, genus_id) index and skips the auto-routing step that compares against each family's running summary embedding.

Ingest a statement

Click Ingest and fill in the form.

• Content (required) — The full sentence. Becomes the vector input.
• Family slug (optional) — Leave blank to auto-route by embedding similarity against family summaries.
• Genus slug (optional) — Required if family is specified.
• Specimen (optional) — Pick from the family's specimens or create one inline.
• Required scopes (optional) — Default is empty (visible to everyone in the tenant).

Submit calls POST /v1/graphium/ingest. The result card shows the classifier's assigned memory_type and layer_kind, the routed family/genus, and a "Dedup: matched existing statement" pill if the 0.999 cosine threshold was hit.

Dedup is idempotent — re-ingesting the same fact bumps access_count on the existing row rather than inserting a duplicate.

Open and edit a statement

Click a search result. The right-side sheet fetches GET /v1/graphium/statements/{id} and renders the full content, classification, required_scopes, embedding dim, access count, created-at, and any symbiosis edges to related statements (read-only in v1).

Click Edit metadata. Mutable fields:

• required_scopes
• layer_kind
• memory_type
• family_slug / genus_slug

content is not editable. The textarea is disabled with a tooltip explaining "To change content, delete and re-ingest." Save calls PATCH /v1/graphium/statements/{id}.

Warning: Editing required_scopes immediately changes who can see the statement. A statement scoped to team:engineering is invisible to operators without that scope, even if they ingested it.

Delete a statement

Click Delete and confirm. The console calls DELETE /v1/graphium/statements/{id}. The statement's quads are removed from its memory graph and its vector row is deleted from kg_embeddings.

The audit log records action = graphium.statement.delete with a metadata snapshot of the deleted row.

Create or delete a family / genus

The taxonomy panel exposes Add family and Add genus actions, calling POST /v1/graphium/taxonomy/families and .../{slug}/genera.

Deletion is allowed only when the family or genus is fully empty:

• A family must have zero genera, zero specimens, and zero statements.
• A genus must have zero specimens and zero statements.

A non-empty target returns 409 with the counts. The console renders an explanatory banner and offers a "View contents" deep link so you can clear children first. Force-delete (cascade) is out of scope for v1.