Create and maintain knowledge safely
Bergur DavidsenUpdated 2026-07-14
Writing through MCP turns an assistant into a knowledge maintainer. Give it that capability only when the workflow identifies the target, checks existing knowledge, separates drafting from mutation, and verifies the result.
A successful tool call is not the same as approved or accurate content.
Search before creating
Before create-memory-fragment:
- Confirm the target workspace.
- Search for the same topic, key, title, or source.
- Fetch likely matches in full.
- Decide whether to update an existing fragment, create a new scoped fragment, or do nothing.
- Ask for approval when the choice changes maintained knowledge.
Do not use “no exact title match” as proof that no duplicate exists. Search semantically and by stable identifiers.
Choose type and placement
Call get-fragment-types for the target workspace and use a valid returned type. Do not hard-code type IDs across workspaces.
Choose the most specific appropriate type, then provide:
- a clear title;
- durable Markdown content;
- a concise summary;
- stable, useful tags;
- collection IDs when the fragment belongs in a curated set;
- a stable key when the workflow supports idempotent creation.
Frontmatter inside Markdown is content metadata. Workspace, platform tags, fragment type, and collection membership are separate platform metadata. Keep their responsibilities clear.
Separate draft and write
For consequential changes, use this sequence:
- Agent researches and drafts.
- Agent shows target workspace, fragment, and proposed change.
- A human or deterministic policy approves it.
- Agent performs one bounded mutation.
- Agent refetches and reports the persisted result.
Do not let a general chat instruction silently convert a read-only research task into a write.
Create safely
Provide explicit summary and tags when deterministic metadata matters. AI enrichment and projection can be asynchronous, so a create result may report processing before search indexes are current.
Store the returned fragment ID. Refetch it with get-memory-fragment-content and verify title, content, type, tags, workspace, and status.
If creation returns result.isError: true, inspect the tool text. The JSON-RPC transport can succeed while the requested domain action fails.
Update safely
Use a full content replacement only when the agent has fetched the latest fragment and intends to replace the complete body.
Where the current schema exposes patch operations, use them for surgical changes. Patch mode can add, delete, or replace line ranges and rejects incompatible or overlapping operations. Line numbers are based on the fetched version, so refetch immediately before applying a patch.
Do not send full content and patch operations in the same update. If the fragment changed after the draft, stop and reconcile instead of overwriting concurrent work.
After any update, refetch and compare the intended result.
Avoid duplicate and repeated mutations
- Use stable fragment keys where appropriate.
- Record returned IDs in the calling service.
- Make retries conditional on the prior result.
- Search before retrying an ambiguous create.
- Give external jobs their own idempotency state.
- Do not assume a timeout means the write did not happen.
For bulk deterministic imports, prefer REST and application-owned idempotency over a model-driven loop.
Public and shared workspace safety
Before writing to a public or broadly shared workspace, remove:
- tokens, credentials, cookies, and private URLs;
- customer or personal data;
- private infrastructure and internal runbooks;
- unreleased claims presented as shipped;
- local paths, temporary IDs, or private issue links.
Anchor release documentation to an actual released version and label uncertainty. A public workspace subscription remains read-only; it cannot be used to publish.
Mutation permissions
Use a dedicated credential limited to the target workspaces and required create/update actions. Keep workspace creation, symlinks, files, application management, and administrative operations out of the writer unless needed.
Server-side authorization must check the current user and target. A model choosing a tool is not authorization.
Troubleshooting
Fragment type error
Call get-fragment-types for the same workspace and pass a valid fragmentTypeId. Do not retry a tool-level domain error as a network outage.
The write times out
Search or fetch before retrying. The operation may have been accepted and still be processing.
Search does not find a new fragment
Refetch by ID first, then allow for asynchronous indexing before repeating search checks.
An update removed unrelated content
Stop further writes, fetch the current fragment, recover from an authoritative source or history if available, and narrow future edits.