Check what the agent can read
Open Workforce → Agents → agent → Knowledge. Knowledge it can read lists the agent’s ambient scopes outside a run: global, company, its organizational scopes, and its own agent scope as applicable. A run can add the factory and project scopes for that run. This view is an access explanation, not a promise that every artifact in those scopes will be retrieved. The viewer also needsknowledge:read; scopes or artifacts the viewer cannot read are
not revealed. Source-restricted items remain restricted inside an otherwise readable scope.
The same tab shows bounded lists of recently authored and recently cited artifacts. Use them to
investigate current behavior, not as a complete agent history. Personal Agent memory is owner-gated
and managed from Personal Agent settings; platform-agent memory is read-only in the agent view.
Retrieval and citations
During work, an agent searches knowledge with itsknowledge_search tool.
Forge adds it to every workflow node agent, chat agent, Factory Manager and the Workflow Architect;
no tool set has to grant it. The search ranks eligible results by semantic relevance and case grade.
Retired cases are excluded. A requested scope outside the agent’s allowed set is refused without
searching it. Source access is checked before a result can be returned.
When an agent uses a result, the citation identifies the artifact used. In Console, follow that
citation to the artifact and inspect:
- Overview for scope, origin, source, kind, grade, and current text;
- Evidence for the evidence retained for the case;
- Uses for runs or turns that cited it and their effective outcome signals; and
- History for changes to the artifact over time.
Recording knowledge is deliberate
An agent with the governed knowledge-write capability can record a durable case into an allowed scope. The target still has to be available to that agent and the write still passes normal authorization. Recording a case is not a generic way to copy anything the agent saw: restricted source content and restricted conversations retain additional safeguards. Choose the target based on who should reuse the result:- use an agent scope for durable knowledge specific to that agent;
- use an organizational, factory, or project scope only when the intended readers share that governed context; and
- do not use Knowledge as a substitute for transient working notes or private memory.
Keep memory and Knowledge distinct
Agent memory helps one agent carry context across work. Knowledge is a governed artifact corpus designed for discovery, citation, evidence, and shared reuse.
An eligible long-term memory may be promoted after successful reuse into a provisional artifact.
Promotion is a boundary crossing, not an alias: the resulting artifact has its own scope, access,
grade, citations, and review lifecycle. Do not assume a memory is searchable in Knowledge unless a
corresponding artifact exists.
Verify behavior with operator evidence
Use this sequence when an agent found the wrong item—or nothing at all:- On the agent’s Knowledge tab, confirm the expected scope is readable outside the run or was supplied by the run.
- In Knowledge, search as yourself and, when authorized, use Search as the agent. Search as never reveals results you cannot read yourself.
- Open the expected artifact. Check that it is active, searchable, in the intended scope, and not blocked by source access.
- Inspect the run step’s Context and citation links. Treat a partial marker as a limit of the recorded view, not evidence that no other context existed.
- Check Knowledge health for pending embeddings or source failures, then Search quality when ranking quality is the issue.
- If outcomes or conflicting evidence created steward work, resolve it in Review rather than editing around the queue.
Do it over the API
Two steps of the sequence above have API reads. These calls use theFORGE_BASE set up in the Raw HTTP tab of the quickstart. Send a Personal key as the bearer in place of $ACCESS_TOKEN for both, with scopes that include knowledge:manage, agents:read and knowledge:read: the first refuses an External App, and the quickstart’s token carries no knowledge scope.
Search as the agent, the HTTP form of Search as:
knowledge:manage and accepts only a Personal key or a platform API key, not an External App: send your Personal key as the bearer in place of $ACCESS_TOKEN (see Choose a credential). Add namespace to search one namespace readable by both you and the agent.
List what the agent recently authored and cited:
agents:read at the agent’s home and knowledge:read. It lists at most 20 readable cases from the agent’s latest 50 of each kind, never a case awaiting a steward’s review, and a Personal agent answers 404.
Over MCP, forge_call_read_operation reads the same activity. It is in the default start job:
Meaningful limits
- Readable does not mean relevant, selected, or complete. Retrieval uses ranking thresholds and bounded candidate sets; operator surfaces mark partial results where the contract supports it.
- A citation proves which stored artifact was used. It does not prove that the artifact was correct, current, human-verified, or the cause of the final outcome.
- A proven grade affects retrieval weight; it is not a universal truth guarantee.
- Source permissions, scope changes, retirement, and deletion can make previously visible content unavailable. Do not rely on an old link as an access grant.
- Memory recall and Knowledge retrieval are separate context channels. Inspect both when diagnosing an agent decision.
Related
- Knowledge: the model: cases, scopes and grades.
knowledge_search: the search tool Forge adds to workflow node agents, chat agents, the Factory Manager and the Workflow Architect, withknowledge_listandknowledge_get.- Search quality: check what agents retrieve.
- Review: settle contested and provisional knowledge.

