Build a memory-enabled agent

A memory-enabled agent uses Usable as a durable knowledge layer instead of relying only on conversation history. The safest architecture separates retrieval, reasoning, approval, mutation, and verification.

MCP standardizes tool discovery and calls; it does not design the agent's security policy for you.

Use a read-first loop

A practical loop is:

understand task
→ select approved workspace scope
→ search
→ fetch complete sources
→ verify and synthesize
→ answer with citations
→ propose a write if needed
→ approve
→ mutate once
→ refetch and report

Most user questions should stop after the cited answer. Do not save every conversation automatically; durable memory should be useful, scoped, reviewed knowledge.

Separate retrieval and mutation

Expose read tools to the model by default. Add write tools only in a distinct workflow or approval state.

A retrieval agent usually needs:

list-workspaces within an application-approved boundary;
agentic-search-fragments;
list-memory-fragments or semantic fallback;
get-memory-fragment-content.

A writer can additionally receive narrowly scoped create or update tools. Keep workspace administration, files, symlinks, and applications separate.

Keep credentials server-side

For interactive OAuth clients, use the approved browser authorization flow. For a custom server agent, keep a dedicated PAT or delegated credential in a secret manager and never send it to the browser or model context.

Bind each call to the current user or service identity. The backend must enforce allowed workspace IDs and actions even if the tool schema contains broader options.

Use different credentials for read agents, documentation writers, and administrative automation.

Ground before reasoning

Give the agent an explicit source policy:

Search only approved Usable workspaces. Fetch every relied-on fragment in full. Prefer released and authoritative sources. Cite source titles, state conflicts and uncertainty, and do not write unless the user approves the exact target and change.

Treat search results as candidates. Preserve fragment IDs, updated dates, and workspace attribution through the reasoning pipeline so the final answer can be audited.

Bound the loop

Set limits for:

search iterations;
results and full fragments fetched;
concurrent MCP calls;
tool-call timeout;
total model context;
mutation attempts.

When a limit is reached, return a partial result with the missing evidence instead of continuing indefinitely. Do not retry a validation or permission failure as if it were a transient network error.

Handle errors by layer

Distinguish:

HTTP transport failures;
JSON-RPC protocol errors;
MCP tool results with isError: true;
a successful operation still in asynchronous processing state;
a syntactically successful but semantically poor answer.

Only retry transient failures. Authentication requires reauthorization; permission needs deliberate access review; invalid input needs correction; ambiguous writes need a fetch before retry.

Make writes idempotent

Search before create, use stable keys where supported, persist returned IDs, and refetch after a timeout. For updates, read the latest version and use a bounded patch or complete replacement intentionally.

If the workload is a known import or synchronization job, use REST with application-owned idempotency. MCP is most valuable when model judgment is needed to discover or choose knowledge.

Add observability without leaking data

Record:

correlation or request ID;
tool name and duration;
result category and retry decision;
workspace and object IDs where policy permits;
source IDs used in an answer;
approval identity for mutations.

Do not log tokens, full private fragments, raw prompts containing secrets, or signed file URLs. Use redaction and retention controls.

Test the agent

Test at least:

no relevant source;
conflicting or stale sources;
inaccessible workspace;
expired credential;
listed tool but forbidden action;
result.isError from an invalid fragment type;
timeout after an ambiguous create;
concurrent update;
attempted prompt injection inside a fragment;
attempted write without approval;
citation correctness.

Treat fragment content as untrusted data. Instructions inside retrieved content must not override the agent's system policy or authorization boundary.

Human control

Require explicit confirmation for public publication, destructive replacement, visibility or workspace changes, cross-workspace links, application management, and high-impact business actions.

Show the user what will change and where. After execution, report the persisted result and provide its fragment ID or link.

MCP standardizes tool discovery and calls; it does not design the agent's security policy for you.

Use a read-first loop

A practical loop is:

understand task
→ select approved workspace scope
→ search
→ fetch complete sources
→ verify and synthesize
→ answer with citations
→ propose a write if needed
→ approve
→ mutate once
→ refetch and report

Most user questions should stop after the cited answer. Do not save every conversation automatically; durable memory should be useful, scoped, reviewed knowledge.

Separate retrieval and mutation

Expose read tools to the model by default. Add write tools only in a distinct workflow or approval state.

A retrieval agent usually needs:

list-workspaces within an application-approved boundary;
agentic-search-fragments;
list-memory-fragments or semantic fallback;
get-memory-fragment-content.

A writer can additionally receive narrowly scoped create or update tools. Keep workspace administration, files, symlinks, and applications separate.

Keep credentials server-side

Bind each call to the current user or service identity. The backend must enforce allowed workspace IDs and actions even if the tool schema contains broader options.

Use different credentials for read agents, documentation writers, and administrative automation.

Ground before reasoning

Give the agent an explicit source policy:

Search only approved Usable workspaces. Fetch every relied-on fragment in full. Prefer released and authoritative sources. Cite source titles, state conflicts and uncertainty, and do not write unless the user approves the exact target and change.

Treat search results as candidates. Preserve fragment IDs, updated dates, and workspace attribution through the reasoning pipeline so the final answer can be audited.

Bound the loop

Set limits for:

search iterations;
results and full fragments fetched;
concurrent MCP calls;
tool-call timeout;
total model context;
mutation attempts.

When a limit is reached, return a partial result with the missing evidence instead of continuing indefinitely. Do not retry a validation or permission failure as if it were a transient network error.

Handle errors by layer

Distinguish:

HTTP transport failures;
JSON-RPC protocol errors;
MCP tool results with isError: true;
a successful operation still in asynchronous processing state;
a syntactically successful but semantically poor answer.

Only retry transient failures. Authentication requires reauthorization; permission needs deliberate access review; invalid input needs correction; ambiguous writes need a fetch before retry.

Make writes idempotent

If the workload is a known import or synchronization job, use REST with application-owned idempotency. MCP is most valuable when model judgment is needed to discover or choose knowledge.

Add observability without leaking data

Record:

correlation or request ID;
tool name and duration;
result category and retry decision;
workspace and object IDs where policy permits;
source IDs used in an answer;
approval identity for mutations.

Do not log tokens, full private fragments, raw prompts containing secrets, or signed file URLs. Use redaction and retention controls.

Test the agent

Test at least:

no relevant source;
conflicting or stale sources;
inaccessible workspace;
expired credential;
listed tool but forbidden action;
result.isError from an invalid fragment type;
timeout after an ambiguous create;
concurrent update;
attempted prompt injection inside a fragment;
attempted write without approval;
citation correctness.

Treat fragment content as untrusted data. Instructions inside retrieved content must not override the agent's system policy or authorization boundary.

Human control

Require explicit confirmation for public publication, destructive replacement, visibility or workspace changes, cross-workspace links, application management, and high-impact business actions.

Show the user what will change and where. After execution, report the persisted result and provide its fragment ID or link.

Use a read-first loop

Separate retrieval and mutation

Keep credentials server-side

Ground before reasoning

Bound the loop

Handle errors by layer

Make writes idempotent

Add observability without leaking data

Test the agent

Human control

Related pages

Use a read-first loop

Separate retrieval and mutation

Keep credentials server-side

Ground before reasoning

Bound the loop

Handle errors by layer

Make writes idempotent

Add observability without leaking data

Test the agent

Human control

Related pages