Skip to main content
A knowledge source is an external system Forge reads knowledge from, such as a wiki space or a folder of documents. Forge copies each of its items into a case in one knowledge scope, so a synced item is graded, cited, contested, versioned and audited exactly like a case an agent recorded. A source names three things, and none of them changes after it is created:
  • a provider: the synchronized_knowledge capability provider that talks to the external system;
  • a container: the space, folder or workspace in that system to read;
  • a target scope: the knowledge scope its cases are stored in.
To change any of the three, remove the source and create a new one. A source uses synchronize mode: Forge copies its items into Knowledge on a schedule. New connections support synchronization only. Historical external context references remain visible under their original access checks and show No longer available.

Who can manage sources

Every function is also fenced by scope. You see and manage only the sources whose target scope you can read, and you can create a source only in a scope you can read. knowledge:manage never reaches a scope you cannot read: a source outside your scopes is reported as not found. Connecting a source also needs credentials:use where it writes, because the source syncs with the vendor credential that resolves along its target scope (see Credentials live on the vendor): company at the deployment root, a team or department at that org unit, a factory or project at its home. A machine credential manages sources through the Knowledge API and the MCP server, in its writable namespaces: connect (scopes reaching both knowledge:manage and credentials:use), list providers, update, sync now, re-list and remove. See Knowledge sources. In the Console, these actions live on Knowledge → Sources (/knowledge/synchronized-sources); see Knowledge: Sources.

Credentials live on the vendor, never on the source

A source stores no secret. Its provider’s credential belongs to the vendor’s connection on the Credentials page, and resolves along the source’s target scope: a factory’s source uses that factory’s credential first, then the broader ones. A source’s config holds non-secret provider settings only. A manager can change the settings its provider declares after the source exists; a changed setting re-lists the source on its next sync. Freshservice declares excludedCategoryPrefixes (one prefix per line): root categories whose label starts with one, and their subtrees, are not synced, and a newly added prefix is refused while a live triage policy permits a category it would exclude. Forge refuses a config key named like a secret (secret, token, password, apiKey), and any config value or container id that looks like one.

Target scopes

A source targets shared organizational knowledge: company, department, team, factory or project. It never targets global, and never a personal, agent, customer, external-app or channel scope. Its cases are visible to everyone who can read that scope.

Curated sources

Marking a source curated is a knowledge manager’s approval of what it holds. Its items enter as proven, and so do their later updates. Outcome feedback can still contest a curated item, and a sync never overrides a retired or contested grade. Items from a source that is not curated enter as provisional and earn their grade like any other case. Changing curated applies to the cases the source writes from then on. It regrades none of the cases it already wrote.

Sync interval and runs

A new source starts its first sync as it is created, then syncs every syncIntervalMinutes, from 15 to 1,440 (24 hours). Its first run is scheduled in the same step that stores it, audited as a sync request by whoever created it; the dispatcher that runs every five minutes finds that run holding the source and starts no second one. Sync now starts a run right away unless one is already running. One run per source at a time; each run lists the source’s changes a page at a time, and its history shows what it stored, skipped, deleted and failed. Pausing a source stops it at once: the run it was in is closed and records no more progress. An item that run was already writing when you paused can still land as a case. Resuming makes it due immediately. Changing an active source’s interval reschedules it: it is next due one new interval after its last run began, or at once if that time has passed; a source that has not run yet stays due at once. A source that fails too many runs in a row is set to error and stops syncing until you resume it; a run closed by a pause or removal neither counts as a failure nor resets the count, and a successful run resets it, and so does resuming a source that is in error. A provider that delivers typed records (Freshservice, for example) is listed in pages of the size it declares, up to 200 items; Freshservice asks for 100. Each page of records is written in one step, and a record whose source version has not changed is only marked as seen. Records of a searchable kind are embedded for search shortly after their page is written, in batches; until then list and get return them but search does not. Records of a kind that is not searchable are never embedded. A run of a record provider keeps listing until its time budget, then continues in a new run step. Ranked search can select one to eight exact registered kinds, for example freshservice.group. The selection searches records only and still applies every readable-scope, source-access, removal, and searchability check. Use record listing when a complete decision set is required. Until a new source’s first run begins, its drawer shows First sync queued and the sources table shows First sync started. While a source’s first pass runs, its drawer shows First sync in progress, the collection it is on and how many records it has stored so far, and how long the run has been going. You can browse the records stored so far, labelled as not yet complete. Workflows and list read a kind only once a pass has completed and been verified. An item that fails on three syncs in a row is quarantined, so one bad item never stops the whole source. A quarantined item no longer fails its run or holds the source’s place in the listing, and the run history counts it as quarantined rather than failed. Forge keeps a record of the item and tries it again whenever the source lists it. When the item next syncs, the record is cleared. While it is quarantined, a case of a restricted item is deleted, because its access can no longer be kept current. A case of an item open to the whole scope is kept. When five or more items in a row fail on one page, Forge first treats it as an outage rather than bad items. The outage might be the source, the embeddings provider, or the lookup that maps people. The run fails and counts toward the source’s failures in a row. No item is quarantined for it, and the next run lists that page again. A run of failures that keeps coming back is treated as bad items, so it never stops the source. Forge quarantines the whole run in any of these cases:
  • It failed on three syncs, and on at least one of them a later item on the page was stored, which shows the source and the store were working.
  • It failed on four syncs without that proof.
  • Failing again would set the source to error.
A source whose listing itself fails quarantines nothing and still ends in error. The cases a quarantine deleted come back with their access at the next full re-list, within 24 hours, once their items sync. A restricted case keeps its access only while Forge can re-check it. That means within a full re-list (every 24 hours), plus one sync interval, plus an hour. A source that is still active but has not completed a full re-list within that time has the access of its restricted cases sealed: nobody can read them. The exceptions are cases a run re-checked within that time, which stay readable. The next full re-list that completes gives each one its access back. A seal that fails partway is retried with backoff until it completes. Each sync dispatch and each deploy seal a stale source again. Due sources are dispatched oldest first, at most two starts a second. Knowledge › Health shows how many of the sources you can read are more than ten minutes overdue.

Record field ownership

A synchronized record’s attributes belong to its provider. Forge-owned annotations are a separate map that synchronization preserves. An annotation edit retains the previous map in the record’s bounded history; ordinary deletion removes annotations from the current record, while removing the entire source erases its stored history. The record drawer shows a record’s fields and names its provider as the source of truth, as search does. Open Advanced in the drawer to read or edit the current map in its Annotations section. HTTP clients use GET /api/v3/knowledge-record-annotations and POST /api/v3/knowledge-records/annotate; MCP clients use forge_call_operation with operationId getKnowledgeRecordAnnotations and annotateKnowledgeRecord. All take sourceId, kind and externalId. Reads require current source-home knowledge:read, readable namespace and record source access. Editing additionally requires knowledge:manage at the actual source home; credential scopes narrow both permissions. The returned canAnnotate reflects these current checks. API keys and applications retain their credential attribution. Saving replaces the whole map: omitted keys are removed, {} clears it, and null is a value. Values may be strings, finite numbers, booleans, null or arrays of strings. Maps allow at most 25 keys of 1–64 printable ASCII characters, excluding leading $ and __proto__, constructor or prototype, within 16 KiB of UTF-8 JSON. Reload before saving if another editor may have changed the map: saving can replace concurrent edits and does not merge keys. An unchanged map creates no new history. Paused or errored sources and held records can still be annotated while active and not being removed. Write acknowledgements contain status and address only; keyed replay rechecks current access without writing again or returning an old map. Generic record read endpoints retain their existing response shape. History includes stored prior annotation values alongside provider attributes.

Record history

Record updates and ordinary item deletions retain up to 20 prior versions per record in Forge’s store. Each version keeps the previous attributes and source version, who or what made the change, the changing sync run when known, and the time. Unchanged sync observations create no version. Read prior versions with POST /api/v3/knowledge-snapshots/search, MCP forge_call_operation with operationId getKnowledgeHistory, or a record’s History view in the Console source drawer. Select the record’s external ID to open it. History returns at most 20 versions per page, newest change first, with opaque continuation. It begins with recorded changes; no older payload or actor is invented. Every page checks current get-equivalent access. Inactive, deleted, removed or unreadable entries return not found, so ordinary deletion’s retained internal versions do not expose deleted content. Stored record actors retain their actual person, agent, credential, sync, provider, system or legacy attribution. A case’s opaque superseding actor stays explicitly legacy; optional corroborating audit evidence does not prove its kind. Generic change run IDs can name workflow runs. This is prior version history, not a complete activity feed or a snapshot-isolation session. Removing the entire source erases its stored record history, including versions of records deleted earlier.

Removing a source

Removing a source really deletes what it wrote. Forge pauses the source, then deletes every case it synced, whatever its grade or status, along with the case’s text, versions and search vector. It then deletes the source’s run history and the source itself, and writes one audit event. The source row stays, paused, for a few minutes after removal, while Forge checks that no sync that was already running wrote anything more.

Restricted items

An item the external system shares only with some people is restricted. Forge stores it only for the people it maps them to, and nobody else who can read the scope sees it. On every sync, Forge maps each principal the source names on the item to Forge: A principal that maps to no one grants nothing. A restricted case is read only on behalf of one person it names, or a member of a team or department it names. A person reads it as their own worker, and a personal agent reads it as its owner. Nobody else reads it: not a shared channel, a workflow, a factory manager or an external app.
  • An item nobody maps to is not synced. It is counted as skipped (unmapped) in the run’s history, and a case that already holds it is deleted.
  • An item shared with more than 256 workers and org units is not synced. It is counted as skipped (too large), and a case that already holds it is deleted. Give wide access through a group mapping to a team or department instead.
  • Every copy of a restricted case keeps its restriction. An agent’s pending rewrite of the case and each earlier version in its history carry the same access as the case, and change with it when the source changes the item’s access. Search, the case’s history and its pending rewrite are shown only to a reader the source allows. Two cases whose access differs are never merged.
  • A conversation that reads a restricted case stays restricted. From then on, the personal agent may restate the case in anything it writes there. So every later reply, tool row and plan card in that conversation is shown only to a reader the source allows. Anyone else sees it as restricted, a Platform admin included. Nothing leaves the conversation without the restriction:
    • the agent records no case from it, because knowledge_record refuses;
    • its durable blackboard notes are not saved as cases;
    • a plan it makes keeps its text only on the plan card. The plan’s run shows the text as restricted, and the plan cannot be saved as a workflow;
    • the agent can launch a saved workflow from it only without inputs, since inputs it writes could restate the case.
  • A case whose access cannot change in place is deleted: one with more than 500 steward-queue items when the source restricts its item or opens it to everyone, or one with more than 48 earlier versions when the source changes its access at all. An open case is never left readable after its source restricts it. The same sync stores the item again as a new case with the access the source now gives it.
  • Permission changes apply when the item is next synced, even when its content did not change: a person the source no longer names, a worker who left or a revoked identity claim loses access then. An item the source opens to everyone becomes readable by the whole scope. A source that lists every item on each sync applies them at the next sync. A source that lists only its changes also lists every item again at least once a day, so a change that did not change the item takes effect within 24 hours plus one sync interval; changing a source’s principal mappings makes it list every item again at its next sync.
  • A source that stops syncing hides its restricted cases. Forge cannot apply a source’s permission changes while it is not syncing it. So when a source is paused or set to error, each of its restricted cases is sealed: no one can read it until the source syncs again. Cases open to the whole scope stay readable. Each deploy also seals any source that is already paused or in error, or active but overdue for its full re-list. Resuming the source makes its next sync list every item, which gives each sealed case back the access the source now grants.
  • A worker who leaves, or leaves a team, loses access at once. Who a reader is and which team and department they belong to is checked on every read, not at sync time.
Consoles and run inspectors show a restricted case you may not read as restricted, never its title or text. See Knowledge for how the Console shows them.

Set up principal mappings

Set a source’s identityClaimType and groupMappings with knowledge.sources.updateKnowledgeSource (knowledge:manage). Each group mapping names an external group id and an org unit. You can map a group only to a team or department you can read. A source takes at most 200 group mappings. Changing either field makes the source due at once and lists every item again, so every case’s access is recomputed.

Review source changes before applying

Source diff review is opt-in. Off is the default: changes apply automatically, while the independent shrink guard remains active. With no policy, synchronization follows its existing path. A manager can configure knowledge.sourceDiffDoors.setSourceDiffPolicy at the source’s actual home:
  • always holds every nonempty ordinary delta for review.
  • conditional holds when deletes exceed a nonnegative threshold, an operation affects a declared protected record kind, or a case changes while case protection is enabled. These conditions use OR.
  • Clearing the policy with null returns the source to its ordinary path. Saving an equivalent policy changes no revision, generation or audit event.
Forge normalizes the entire provider pass before deciding whether to apply ordinary changes. A condition on the final page holds the whole prepared delta. A failed or incomplete pass releases no ordinary prefix. Snapshot absence is assessed from durable observed identities; a listed item that is invalid or no longer readable is still observed. Source access revocation takes effect immediately through the existing seal or tombstone path, including when another item exceeds a staging cap. Review never delays those security effects. getSourceDiffState and getSourceDiffReview use knowledge:read; policy changes, approval, explicit Resume and rejection use knowledge:manage. Review requires a current person and active seat with access at the source’s actual home. Samples and counts include only currently readable changes, under both existing and proposed access. Restricted changes are indicated without revealing an exact hidden count. Samples contain redacted titles and nonsensitive field names, without field values, source IDs, URLs or body excerpts. A complete current review of all remaining operations is required to approve or resume. Diff approval and snapshot shrink approval are independent. Either may come first. An approved diff applies eligible work and waits for any remaining shrink authorization; approving the shrink hold alone cannot apply a diff still awaiting review. Each final write rechecks current permissions, identity, source policy and binding, mapped access and the complete stored baseline, including Forge annotations. A concurrent edit is skipped and reported as a conflict rather than overwritten. Progress describes committed effects. Reject, expiry, policy changes, relisting and a newer source generation stop remaining work; they do not undo operations already committed. A failed apply requires explicit Resume of the same prepared remainder. Pending scheduled work is not retried merely because an observer waited a long time. Only a fully acknowledged, conflict-free pass advances the provider cursor. Delayed approval does not create a new source access-freshness window. Prepared payload authority expires 48 hours after the run starts, even if cleanup is delayed. Cleanup removes bounded pages and retains the run’s phase and counters. Enabled preparation has conservative ceilings: 256 KiB per operation, eight slots and 512 KiB per page, 512 KiB per staging call, 64 KiB added run metadata, and 64 local principal descriptors per operation. Native page sizing includes system fields and reserves acknowledgement space. A payload or legacy subtree that cannot fit is refused without truncation, blob spill or enlarged limits; it is not quarantined solely for exceeding a staging ceiling. Physical source removal retains the existing store-owned record and history cleanup chain. In the Console source drawer, use Change review policy, then select a run’s Review changes. Continue review advances one bounded page. Counts are labelled Counts shown so far until the scan is complete; the drawer never infers hidden totals from samples or ordinary run counts. Approve changes and Resume application use the selected current proof and revision. A scheduled decision acknowledgement is not an applied result: follow the server’s Applying approved changes state. Reject remaining changes requires confirmation and preserves already committed work. The separate Shrink deletion approval controls authorize only shrink, including a run-only threshold override from 0 to 79 no higher than the current threshold. A stale policy save preserves the draft and requires an explicit reload. Record history and annotations remain available while reviewing a run.

Restricted records in the source drawer

The Records section reads as your active primary seat at the source’s home. It includes each record whose current entry access admits you and shows how many active restricted candidates were omitted from the requested kinds, before filtering. A zero-visible result can still have an omission note. Other completeness and integrity failures still refuse the list. During a first pass, a page inspects at most 50 raw candidates. Its omission note applies only to that page. An empty page may have Next; this remains a partial view labelled “First pass in progress, not yet complete.” A changed source or authority asks you to start again. Procedure runs, agents and API/MCP credentials retain explicit refusal when they encounter restricted records.

Authored records

Authored records hold typed facts that Forge owns, as opposed to records synchronized from a source. They live in a record collection rather than a source, so source sync, source removal and provider completeness never overwrite or delete them. A person with knowledge:manage creates a collection in Console and chooses its namespace, name and kind schema. An API client can create one too, holding knowledge:manage where the namespace lives; the collection is created by and audited as that credential. A collection’s schema and governed home are immutable; create a new collection when the shape or home must change. After a collection exists, Console and API clients can maintain its records. API credentials need knowledge:read and knowledge:manage, and every write rechecks the collection’s current home, readable and writable namespace, and token scopes. Listing and getting collections requires knowledge:read. A write to a collection the credential may not read answers the same 404 as a collection that does not exist, and nothing is recorded; a collection it can read but may not manage answers 403. Each record address is {collectionId, kind, externalId}. Reads, history and search authorize the original caller against the collection as it exists now. Write responses contain only the address, a positive version, the outcome and request metadata; they never echo attributes or entry identifiers. A record belongs either to a source or to a collection. Synchronized records carry sourceId; authored records carry collectionId and a positive numeric version. Strict clients should pick the branch by owner field and reject a value that carries both.