---
title: MCP Memory Tools reference
description: Choose and safely call Atmina's MCP memory tools for recall, files, permissions, and audit.
owner: markus
last-reviewed: 2026-09-10
---

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

```json
{ "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](https://atmina.ai/docs/images-and-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.

```json
{
  "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:

```json
{ "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](https://atmina.ai/docs/mcp-authentication) for setup.