MCP Memory Tools reference

Connect and authenticate first. The server's tools/list response is authoritative: Atmina removes tools that the caller, selected Knowledge Base, or active surface cannot use. The role below is the minimum owning-team role; a share or agent policy can narrow it further. Anonymous public-KB connections expose only search.

Orient and manage Knowledge Bases

Tool	Minimum role	Required or key inputs; result
whoami	Viewer	None; authenticated person and team memberships.
health	Viewer	None; build and search-provisioning health.
list_kbs	Viewer	None; accessible Knowledge Bases and identifiers.
create_kb	Admin	name; optional slug and description. The current team is implicit.
update_kb	Admin	kb_id and changed name, slug, visibility, or location_policy (visible or flag_only).
delete_kb	Admin	kb_id; archives the KB after explicit confirmation.

Start with whoami, then list_kbs. If a KB is absent, do not guess its identifier: the caller lacks access or is connected to the wrong team.

Find and read memory

Tool	Minimum role	Required or key inputs; result
search	Anonymous on a public KB; otherwise Viewer	query; optional scope, filters, retrieval, and ranking. File-grouped snippets, scores, reasons, read_ref, and an optional asset block for picture results.
list_files	Viewer	kb_id; optional path prefix, filters, sort, and page controls. Exhaustive active catalog including tags and, for Assets when provider context is known, description_source.
read_file	Viewer	kb_id and path or file_id; content, size, and SHA-256. Path wins if both are sent.
get_file_outline	Viewer	kb_id and file identity; headings, size, and SHA-256 without the body.
file_history	Viewer	kb_id and file identity; retained versions.
get_context	Viewer	kb_id and context inputs; a bounded context package.
related	Viewer	kb_id, file identity, optional depth 1 or 2 and registered type; incoming, outgoing, and unresolved references, with an optional asset block for picture results.

{ "tool": "search", "args": { "query": "customer data retention decision", "scope": { "kb_slugs": ["acme/handbook"] }, "max_files": 5 } }

For an Asset, read_file returns the Companion text plus an available medium rendition by default; include_image: false requests text only. Original Asset bytes require the owning-Team REST or Files download. See Images and other assets.

A contribution_note appears ahead of the content when you have not written to this Knowledge Base recently, or have never written to it. It reports a condition rather than asking for an action, and it is absent when you have contributed lately. It is the reader's own record, not the Knowledge Base's: another agent's writes do not silence it.

An asset block identifies the Asset behind a picture's Companion citation. path is always present; file_id, format, width, height, pages, state, and a thumbnail rendition_url appear when the catalog resolved them. The result's own path and read_ref continue to identify the readable Companion.

Answer from a sufficient snippet. For detail, pass the top result's path or file ID to read_file. Use list_files for an exhaustive request such as every file under policies/. If fresh content is absent, inspect atmina://kb/{kb_id}/indexing-status; a successful write can precede indexing.

Write, upload, and recover files

Tool	Minimum role	Required or key inputs; result
write_file	Editor	kb_id, path, and mode; UTF-8 content for create/overwrite/append, or patch for find-replace. Optional expected_bytes, content_sha256, and if_match; returns the new head etag/version.
write_files	Editor	kb_id and up to 50 write items; per-item results, default concurrency 5.
request_uploads	Editor	kb_id and up to 50 path, MIME, byte-count, and SHA declarations; PUT URLs, required headers, and batch_token.
confirm_uploads	Editor	kb_id and batch_token after PUT; verifies, catalogs, and starts indexing. Safe to retry.
upload_file	Editor	kb_id, filename, optional MIME type, and base64 content up to 1 MiB.
update_file	Editor	kb_id, file_id, MIME type, base64 content, and concurrency guard.
move_file	Editor	kb_id, file_id, and to_path; this tool does not accept an if_match guard.
restore_version	Editor	kb_id, file identity, retained version, and current-head guard.
delete_file	Admin	kb_id and file identity; delete after explicit confirmation.
generate_hub_index	Editor	kb_id and folder inputs; preview first, then call with operation: "apply".
generate_nav	Editor	kb_id; preview first, then explicitly apply the proposed wiki/nav.yaml.

Read before changing a file and carry its returned SHA-256 as if_match. A conflict means somebody changed the head: reread and reapply the intended edit.

{
  "tool": "write_file",
  "args": {
    "kb_id": "<kb_id>",
    "path": "decisions/search.md",
    "content": "# Search decision\n\nUse hybrid retrieval.\n",
    "mode": "create",
    "expected_bytes": 41,
    "content_sha256": "<sha256-of-the-exact-utf8-bytes>"
  }
}

Call get_file_outline afterward and compare size_bytes and sha256. Recompute both from the exact UTF-8 bytes after content_integrity.

For large or binary content, call request_uploads, PUT the exact bytes to each URL with every returned required header, then call:

{ "tool": "confirm_uploads", "args": { "kb_id": "<kb_id>", "batch_token": "<batch_token>" } }

Presigned image and PDF Assets may be at most 25 MiB; other admitted files retain the 100 MiB single-PUT ceiling. Expired URLs require a new request. Batch failures are per item, except duplicate paths reject the whole batch. Apply multiple edits to one path sequentially, carrying each new hash forward.

Audit, settings, and sharing

Tool	Minimum role	Required or key inputs; result
audit_log	Editor	Optional kb_id, actor, tool, and time range; compact events.
get_audit_event	Editor	event_id; permitted diagnostic detail.
get_team_settings	Admin	None; the current Team settings.
update_team_settings	Admin	Changed Team settings; the tool schema defines supported fields.
share_kb	Admin	KB and target; legacy MCP surface, so prefer the app.
invite_to_kb	Admin	KB, email, and role; legacy MCP surface, so prefer the app.
revoke_share	Admin	KB and grant identity; legacy MCP surface, so prefer the app.

Use audit_log to find an ID before get_audit_event. Query text may be absent because team privacy settings control audit detail.

Resources and recovery

Useful read-only resources include atmina://status, atmina://my-team, atmina://my-kbs, atmina://my-team-status, atmina://kb/{kb_id}, atmina://kb/{kb_id}/files, atmina://kb/{kb_id}/files/{file_id}, and atmina://kb/{kb_id}/indexing-status. The server also publishes atmina://docs/agent-quickstart and atmina://kb/{kb_id}/write-guide.

Treat validation as bad input, permission_denied as role or scope, conflict as stale state, content_integrity as a byte/hash mismatch, and payload_too_large as a signal to use presigned upload. Do not blindly retry those failures. Respect the transport's retry interval after rate limiting.

See MCP authentication and connections for setup.