Knowledge & Records
Knowledge & Records is a governed company document library — AI OS department #11, community-placed, with four named agents. It is a catalog over the platform's existing document stores, not a fourth one: every record carries an owner, a sensitivity label, a reader allowlist, and a retention policy, and every agent on every tier reads it through the same fenced envelope used for any outside data.
What It Catalogs
The library indexes three physical stores that already existed before the department did — nothing about them changes, and no document content moves:
| Store | Location | What lives there |
|---|---|---|
| Memory Vault | .magent/vault/{raw,wiki,outputs} | Markdown knowledge entries — the Knowledge Graph's home |
| org-docs | .magent/org-docs/<uuid>.txt | Extracted text from uploaded documents (.txt/.md/.csv/.docx/.xlsx) — the landing zone for new uploads |
| artifacts | .magent/artifacts/{docs,code,media,research,web-studio,youtube} | Agent-produced output, nested by kind |
The catalog itself — .magent/library/catalog.json — holds metadata only: which store, which path, a content hash for dedupe, and the governance fields below. Document bytes stay exactly where they already were.
The Read Choke-Point — No Trusted Tier
The single most important property of the design: the library has no trusted tier. Its purpose is that every agent reads it, and much of what it catalogs will be documents nobody on the operator's side authored. There is no "it came from inside, therefore it is safe" path. Content leaves the library only through the read choke-point, which resolves reader-permitted records and returns them fenced as untrusted data — the exact discipline AI OS already applies to scraped web pages and uploaded files. A parser bug or a planted instruction inside a cataloged document cannot escalate past that fence.
The Knowledge & Records Team
| Agent | Role |
|---|---|
| Chief Librarian (Athena) | Department head. Taxonomy authority, cross-department lookup, routing, and retention decisions. Legal hold is a consult with the Legal department, not this agent's call. Reads only, never ingests. |
| Archivist (Vellum) | Intake, format handling, dedupe, metadata, and versioning — extends the platform's existing document-extraction pipeline rather than reimplementing it. |
| Knowledge Manager (Archive) | Auto-categorizing knowledge ingestion, semantic linking, and the radial graph visualization (the former Knowledge Graph agent, relocated here). |
| Sync Steward (Tether) | Source-change detection and knowledge-base re-sync — keeps external Gems and notebooks current as source material changes. |
Reader-Scoped Access & Retention
Every record's readers field is an allowlist, built entry by entry — never a denylist, so a new field added to the schema can never accidentally widen access. An entry is an org email, an agent name, or the sentinel all-agents. Vault content migrated before the department existed defaults to all-agents, preserving how it already behaved; new uploads default narrower.
Governance fields carried on every catalog record:
- owner — the org the record belongs to, for multi-tenant scoping
- readers — the allowlist that actually enforces who may read it
- sensitivity — a human-facing label (public, internal, confidential, restricted) that travels alongside the allowlist for readability
- retention — a policy of keep, review, or expire, with a scheduled disposal date
- legalHold — a flag that blocks delete and dispose in any mode until Legal clears it
The legalHold flag is set only through a consult with the Compliance Officer and General Counsel — never unilaterally by the Chief Librarian.
Canonical-Facts Shelf
Product facts — the agent count, the department count, model and tier counts, pricing — live today in more than one place, and copies of the same fact have drifted apart before. The canonical-facts shelf is a small set of library records with source: 'canonical-fact' that every caller reads instead of a hard-coded number, so updating a fact means editing one governed record rather than finding every copy.
API Reference
The library routes are operator-only today — the client-role guard does not list /api/library/*, so a personnel or clone contribution surface is a later phase, not this one.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/library | Catalog summary — record counts by store, reader-filtered for the caller |
| GET | /api/library/search?q= | Search titles, tags, and content, reader-filtered |
| GET | /api/library/canonical | The canonical-facts shelf |
| GET | /api/library/record/:id | Record metadata (never raw content) if the caller can read it |
| GET | /api/library/record/:id/content | Raw bytes, admin-or-reader gated, path resolved per store |
The legacy /api/vault/* routes keep working at their existing session-authenticated level, now re-pointed through the catalog with the same reader filtering.
Frequently Asked Questions
What is the Knowledge & Records department?
AI OS department #11 — Knowledge & Records — is a governed company document library. It is a catalog over the platform's existing document stores (the Memory Vault, extracted uploads, and agent-output artifacts), not a fourth store: document bytes never move, only their metadata is indexed.
Why does the library have no trusted tier?
Every agent on every tier reads the library, and much of its content will be documents nobody on the operator's side authored. Content only ever reaches an agent inside the same fenced, untrusted-by-default envelope AI OS uses for any outside data, so a hostile or mistaken document cannot escalate into an instruction.
Who is on the Knowledge & Records team?
Four agents: Chief Librarian (Athena) heads the department and owns retention decisions; Archivist (Vellum) handles intake, dedupe, and versioning; Knowledge Manager (Archive) runs semantic linking and graph visualization; and Sync Steward (Tether) detects source changes and re-syncs external knowledge bases.
Who can read a library record?
Every record carries a readers allowlist — an org email, an agent name, or the sentinel all-agents — built entry by entry so a new field can never accidentally widen access. Vault content migrated before the department existed defaults to all-agents, preserving prior behavior; new records default narrower.
What is the canonical-facts shelf?
A small set of library records — agent count, department count, model and tier counts, pricing — that every caller reads instead of a hard-coded copy. It is the structural fix for the recurring defect where the same fact drifted across several files.
Is the library available on the Community edition?
Yes. Knowledge & Records is a community department, not a licensed one, because its whole purpose — every agent on every tier reads it — would break on Community installs if it were gated behind a commercial license.