> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Knowledge in agents

> Understand what knowledge an agent can retrieve, how citations and run evidence support operations, and where memory and retrieval stop.

An agent can use only knowledge that its dispatch is allowed to read. Forge resolves readable
scopes, applies source restrictions, retrieves relevant artifacts, and records citations and
context evidence for the work. This is retrieval over governed shared knowledge—not unrestricted
access to the Knowledge corpus and not the same as the agent's memory.

## 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 needs `knowledge: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 its [`knowledge_search`](https://docs.gloo.com/forge/reference/tool-sets#knowledge_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.

For a workflow run, inspect the step's **Context** to see the knowledge and memory made available to
that step. The context record is bounded and can be partial, so use the artifact and run detail
together when investigating a decision.

## 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.

Once recorded, the case follows the normal grade, outcome, review, and retirement lifecycle. Its
agent origin does not grant it a proven grade.

## 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.

| Agent memory | Knowledge |
| - | - |
| Session, channel, long-term, facts, and episodes tied to an agent | Durable artifacts in explicit knowledge scopes |
| Read and managed under memory permissions | Read and managed under knowledge permissions plus source access |
| Recalled as context for that agent | Retrieved and cited by eligible people, agents, and workflows |
| Not automatically a shared artifact | Can originate from authoring, agents, synchronization, or eligible memory promotion |

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:

1. On the agent's **Knowledge** tab, confirm the expected scope is readable outside the run or was
   supplied by the run.
2. In [Knowledge](https://docs.gloo.com/forge/console/knowledge.md), search as yourself and, when authorized, use **Search
   as** the agent. Search as never reveals results you cannot read yourself.
3. Open the expected artifact. Check that it is active, searchable, in the intended scope, and not
   blocked by source access.
4. 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.
5. Check [Knowledge health](https://docs.gloo.com/forge/console/knowledge/health.md) for pending embeddings or source
   failures, then [Search quality](https://docs.gloo.com/forge/console/knowledge/search-quality.md) when ranking quality is
   the issue.
6. If outcomes or conflicting evidence created steward work, resolve it in
   [Review](https://docs.gloo.com/forge/console/knowledge/review.md) rather than editing around the queue.

## Do it over the API

Two steps of the sequence above have API reads. These calls use the `FORGE_BASE` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md). 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**:

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/agents/$AGENT_ID/preview-knowledge-search" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "invoice dispute escalation", "limit": 5}' \
  | jq '{hiddenByAccess: .data.hiddenByAccess, hits: [.data.hits[] | {entryId, title, namespace, grade, score}]}'
```

This needs `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](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-a-credential)). Add `namespace` to search one namespace readable by both you and the agent.

List what the agent recently authored and cited:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/agents/$AGENT_ID/knowledge-activity" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data | {cited: [.cited[] | {entryId, title, grade}], authored: [.authored[] | {entryId, title, grade}]}'
```

This needs `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:

```json theme={null}
{ "operationId": "listAgentKnowledgeActivity", "input": { "id": "<agent id>" } }
```

## 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.

See [Knowledge artifacts and lifecycle](https://docs.gloo.com/forge/knowledge.md#artifacts-and-lifecycle) for trust and
review semantics, and [Knowledge: Agents](https://docs.gloo.com/forge/console/workforce/agents#see-what-an-agent-knows) for
the Console controls.

## Related

* [Knowledge](https://docs.gloo.com/forge/knowledge.md): the model: cases, scopes and grades.
* [`knowledge_search`](https://docs.gloo.com/forge/reference/tool-sets#knowledge_search): the search tool Forge adds to workflow node agents, chat agents, the Factory Manager and the Workflow Architect, with `knowledge_list` and `knowledge_get`.
* [Search quality](https://docs.gloo.com/forge/console/knowledge/search-quality.md): check what agents retrieve.
* [Review](https://docs.gloo.com/forge/console/knowledge/review.md): settle contested and provisional knowledge.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.