Skip to main content
The knowledge base holds durable, higher-stakes entries (importance ≥ 5): SOPs, canonical facts, governance rules. Entries have a title, intro, markdown body, category, importance (5–10), tags and a scope layer (user | department | global | provider). Routing rule: use knowledge_search for conceptual “what do we know about…” questions. For exact numbers, counts, prices or filtered records use data_query — never infer a number from semantic search. Governance model for shared writes: a Company-Admin writes shared (global/department) entries directly, and so does a member of the named department (audited, status saved). Any other shared write becomes a governance candidate (status pending_governance) that an authorized human promotes in the app. scope=provider (white-label layer shared across the provider’s companies) requires Provider-Admin.
Semantic recall over the knowledge base (title/intro free-text + category filter). Returns lean rows; fetch full content with knowledge_get. Returns: { knowledge: [...], count }. Each row: id, title, intro, category, category_id, scope, importance, tags, department_id, source, created_at, updated_at, valid_at, invalid_at, source_type, retrieval_class (no body). By default only currently-valid, non-archived entries are returned. Permissions: read; rights-filtered per user (private user-layer entries of others are never returned; admins see all).

​
knowledge_get

One knowledge entry with full content — only if readable for this user. Returns: { knowledge } — the full entry: all search columns plus content (the markdown body), supersedes, source_id, source_uri, failure_count, consolidated_at. Not readable/found → { error: "Knowledge entry not found" }. Permissions: read; rights-filtered.

​
knowledge_save

Create a knowledge entry (durable, importance ≥ 5 — lower-stakes notes belong in memory_save). scope=user writes directly to your private layer (colleagues never see it; admins do). Shared scopes follow the governance model above. Returns: direct write → { status:"saved", layer, knowledge_id, audit } (layer is the resolved scope; audit records actor/version). Governance-routed shared write → { status:"pending_governance", candidate_id, note, audit } (no row yet — a human promotes it in the app). Permissions: write; role/scope rules as above.

​
knowledge_update

Edit an existing entry in place by id (the by-id counterpart to knowledge_save, which creates). Patchable: title, intro, body_markdown, importance, tags, category. The pre-edit state is snapshotted to the governance history (versioned, revertible) and the row’s version is bumped under an optimistic lock. Returns: { status:"updated", id, version, updated, note, audit } — version is the bumped row version, updated lists the patched field names. A concurrent edit returns { error: "Edit conflict …" }. Permissions: write; Company-Admin only (the knowledge base is always shared).

​
knowledge_archive

Archive an entry (soft + reversible) — hides it from knowledge_search and data_query without deleting; pass unarchive:true to restore. The pre-archive state is snapshotted. Returns: { status:"archived"|"unarchived", id, archived_at, note, audit } — archived_at is the new timestamp (or null on unarchive). The pre-toggle state is snapshotted. Permissions: write; Company-Admin only.