How agents contribute to Knowledge OS
Knowledge OS is read and write. You discover facts with knowledge_query / knowledge_get_page, and you contribute back — but only with citations. This page is the contract (write-back shipped 2026-07-05).
The one rule: every write cites its sources
There is no uncited write. If you don't say where a fact came from, the write is refused — not silently stripped, not accepted. A source looks like:
{ "type": "url", "ref": "https://…", "label": "supplier price list" }type is required (url, file, meetgeek, gmail, invoice, wiki, manual, …); give a ref (the locator) and/or a label (human hint). One or more per write.
Two write paths — pick by intent
| You want to… | Tool | Notes |
|---|---|---|
| Create a new page | knowledge_ingest / knowledge_ingest_file | routes by confidence; low-confidence lands in _inbox/needs-review/ |
| Revise an existing page | knowledge_update_page | the page must already exist; updates never create |
knowledge_update_page(namespace, slug, content, sources, title?)
content— the full new markdown body of the page (replaces the old body).sources— required, ≥ 1 citation (see above).title— optional; omit to keep the current title.
knowledge_update_page(
namespace = "chanya",
slug = "suppliers/chiang-mai-spices",
content = "Updated pricing for Q3. Minimum order 20kg…",
sources = [{ "type": "url", "ref": "https://…/pricelist", "label": "Q3 price list" }],
)
→ { "status": "queued", "job_id": 1234, "page_path": "chanya/suppliers/chiang-mai-spices.md" }What you control vs. what the system manages
You supply: the body, the sources, an optional title.
The system manages the frontmatter — you cannot spoof it:
type,namespace,created,status,tags— preserved from the page.updated— bumped to today.authors— your agent identity (agent:<your-sub>) is appended once.sources— replaced with the citations you supplied, so provenance
always reflects the latest revision.
Namespace scope
Your token is scoped to one or more namespaces. You can only read and write within that scope — a write to a namespace you don't hold returns an error (HTTP 403 underneath). Ask an operator to widen your scope if you need more.
What happens after you call it
The call returns immediately with status: "queued". Under the hood:
- wiki-api validates (auth, scope, page exists, content + ≥1 source) and
enqueues a page_update job.
- worker-ocr — the only service allowed to write the vault — applies it
through the crash-safe queue: writes the file, commits + pushes to the vault git repo authored as agent:<you>, then refreshes the search index.
- Your change is now in the vault (Obsidian + GitLab) and queryable.
If a write fails, you get status: "error" with the reason — never a success-shaped no-op. Fix and retry.
Good vs. bad
✅ Good — a real change, cited:
content: "Chef confirmed the kitchen now closes at 22:00 on weekends." sources: [{ type: "meetgeek", ref: "mtg-2026-07-02", label: "ops sync" }]
❌ Refused — no citation:
content: "The kitchen closes at 22:00." · sources: [] → error: "at least one source is required — every agent write must cite…"
❌ Wrong tool — the page doesn't exist yet:
knowledge_update_pageon a new slug → 404. Useknowledge_ingestto create.
See also: how-to-use-knowledge-os for the read side, and style-guide for page conventions.