Manage knowledge records

Preview Knowledge records let you keep a small inventory of policies, controls or procedures inside the ontology, each with the dates it is in force. Agents can then ask what applied on a given day, for example which return policy covered an order placed last March. Records are for directly managed rules, not warehouse data. Customers and orders stay in your warehouse; a retail return policy by region is a good fit.

Before you begin

Your ontology has a published release. Knowledge records appears under Data only once a release exists.
The release includes an object type for the records. For the retail example, add a Return policy object type with policy_code (Text, identifier), region (Text) and return_window_days (Whole number, unit days), then publish. Adding a type is a compatible change, so Studio suggests 1.1.0.

Create a record

Open Knowledge records and choose New record.
In New governed record, choose the Released logical type Return policy. Studio locks the record to that release and type version, so its meaning can’t drift.
Enter a Name such as EU returns 2026, then fill in the Governed values: policy_code EU-RET, region EU, return_window_days 30.
Set Effective from to the date the policy starts. Leave Effective until empty while it remains in force.
Keep Lifecycle on Active, then choose Create record.

A record left in Draft stays out of record-set releases, and other records can’t link to it. Use Add relationship to link a record to another record through a link type, or switch Authoring mode to JSON to edit the whole record.

Change a policy without rewriting history

When the EU return window changes from 30 to 14 days on 1 July:

Select the record and choose Change validity.
Choose Replace, set Change takes effect to 1 July, and enter the Replacement values.
Choose Create successor.

The original record becomes Superseded and ends on 1 July. The successor starts at the same instant and records which record it supersedes. An agent asking about an order from 15 June still gets the 30-day policy. To end a policy with no replacement, choose Retire and then Retire record.A draft record can still be edited with Edit draft. An active record is changed only through Change validity, and a superseded or retired record is closed.

Publish the record set

Choose Publish record set….
Enter a Semantic version such as 1.0.0 and choose Publish.

The first publication creates the record set. Publishing checks that the records are consistent with each other, then freezes every active, superseded and retired record at its current version as the new latest release. Existing releases never change, so publish again after each round of edits.To publish from a script, call POST /ontology/v1/record-set-releases with the record_set_id, the new release, and optionally the base_release_id you expect to replace.

Query records as of a date

In Knowledge records, set Valid as of to the business date you care about and filter by Record type, Lifecycle or Search records. Switch between Working records and Current release to compare drafts with what is published.Agents open a session with mcp__initialise, then call extension__ontology__get_records. Replace the example ontology and session IDs with your values:

{
  "ontology_id": "ontology_01example",
  "as_of": "2026-06-15T00:00:00Z",
  "query": "EU",
  "include_relationships": true,
  "session_id": "mcp_session_<your-session-id>",
  "rationale": "Find the EU policies in force on the requested business date."
}

To read a frozen record-set release instead of current record versions, call POST /ontology/v1/record-queries with both record_set_id and record_set_release_id.

How valid time works

Each record has a business-valid period, separate from when it was saved. The period includes Effective from and excludes Effective until, so a record is returned for as_of when:

effective_from is at or before as_of, and
effective_to (Effective until) is empty or after as_of.

Query input	Default	Notes
`as_of`	Now	An RFC 3339 instant. Studio sends your local time as UTC.
`lifecycle_states`	Active only	Add `superseded`, `retired` or `draft` to see more.
`query`	None	Up to 256 characters, matched against record names and governed values.
`limit`	50	1 to 100 per page. Studio’s Ask tab shows 20 per page.

A text search inspects at most 5,000 candidate records. When it stops early, the response sets scan_truncated: true, and Studio says the results aren’t a complete inventory. Narrow the type or term and search again. A record can also cite exact versions of supporting documents. A released record keeps citing the version it was published with, even after the document changes. Pass include_knowledge_references: true to return those citations.

Publication rules and limits

Publishing a record set is refused when:

Rule	Message
The set has no non-draft records	A record set release must contain at least one governed record.
A record is locked to a different ontology release than the set	Every record in the set must pin the record set’s exact ontology release.
Two records share an API name	A record set cannot contain duplicate record api_name values.
A relationship or supersession points outside the set	A record set contains a relationship or supersession target outside the set.
Superseding records overlap in time	Superseding record business-valid intervals must not overlap.
A relationship outlives a retired target	A relationship cannot remain valid after its target record is retired.
The version already exists with different content	This record set release label already exists with different content.

Limit	Value
Records per record-set release	50,000, stored in shards of up to 500
Governed values per record	256, up to 1 MiB encoded
Relationships per record	512
Supporting-document citations per record	64
Records one record supersedes	64

A superseded or retired record must have an Effective until.

Verify

Knowledge records shows the record set’s Current release with its version and Release checksum.
With Valid as of before 1 July, the 30-day policy is listed; after 1 July, the 14-day successor is.
extension__ontology__get_records with the same as_of returns the same records.

Ontology concepts: records, record sets and releases.
Read governed records: the MCP tool’s inputs and response.
Use Ontology with agents: where records fit in an agent’s flow.

Skill management

Agent management

AI Gateway

Metrics Studio

Ontology

Before you begin

How valid time works

Publication rules and limits

Verify

​Before you begin

​How valid time works

​Publication rules and limits

​Verify

​Related

Before you begin

How valid time works

Publication rules and limits

Verify

Related