> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Tools Reference
> Reference for Cognee MCP tools, parameters, defaults, and usage notes.
Cognee MCP exposes the memory API — `remember`, `recall`, and `forget` — plus `cognify_status` for tracking background ingestion. Every registered tool is callable by name, but only some of them appear in the server's `tools/list` response by default — see [Tool modes](#tool-modes).
Unless noted otherwise, parameter names and defaults below reflect the current MCP server implementation.
Some MCP parameters use compact transport-friendly encodings:
* `datasets` is a comma-separated string, not a JSON array.
* `top_k` must be between `1` and `100`.
With backend access control enabled, dataset names are resolved against datasets owned by the current user. Shared datasets that the user can access but did not create may not be targetable by name through MCP retrieval tools.
## Available Tools
The core memory API. These tools map to Cognee's main operations and appear in `tools/list` in every tool mode.
Store content as permanent graph memory or session memory in one call. Accepts either text or a base64 file upload. See [Remember](/core-concepts/main-operations/remember).
| Parameter | Type | Default | Notes |
| ---------------- | ------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data` | `str` | `None` | Text to store. Mutually exclusive with `filename` / `content_base64`. |
| `filename` | `str` | `None` | Original filename of a file upload. Used to derive the stored document's name. When omitted, the file is stored as `upload.txt`. |
| `content_base64` | `str` | `None` | Base64-encoded file content to ingest, up to 10 MB. |
| `dataset_name` | `str` | agent-scoped | Target dataset for permanent memory. Defaults to the MCP client's agent-scoped dataset (e.g. `cursor_vscode_memory`), or `main_dataset` when no client identity is detected. |
| `session_id` | `str` | `None` | When set, stores in session cache instead of permanent graph memory. |
| `custom_prompt` | `str` | `None` | Custom extraction prompt for permanent-memory mode. |
| `background` | `bool` | `False` | Queue permanent ingestion as a background task and return immediately instead of waiting for the pipeline. Ignored when `session_id` is set. |
Provide either `data` or `content_base64` (optionally with `filename`). Passing both, or neither, returns an error. With `background=true` the call returns before ingestion finishes, so failures cannot surface in the return value — check progress and any captured errors with [`cognify_status`](#available-tools).
File uploads are permanent-memory only: combining `content_base64` with `session_id` returns an error, and content that is not valid base64 or exceeds 10 MB is rejected. The stored document keeps the file's basename (directory components stripped, `.txt` appended when there is no suffix).
Retrieve memory with auto-routing and session-aware behavior. See [Recall](/core-concepts/main-operations/recall).
| Parameter | Type | Default | Notes |
| --------------- | ----- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | `str` | required | Natural-language query. |
| `search_type` | `str` | `None` | Optional override for auto-routing. |
| `datasets` | `str` | `None` | Comma-separated dataset names. Name lookup is owner-scoped. |
| `session_id` | `str` | `None` | Session-first retrieval scope. |
| `system_prompt` | `str` | `None` | Override the synthesis prompt for completion searches. When omitted, falls back to a server-side default if one is configured (see note below). |
| `top_k` | `int` | `15` | Must be between `1` and `100`. |
When `system_prompt` is omitted, `recall` falls back to a server-side default synthesis prompt if the server sets `COGNEE_MCP_RECALL_SYSTEM_PROMPT` or `COGNEE_MCP_RECALL_SYSTEM_PROMPT_FILE`. An explicit `system_prompt` always takes precedence over the server-side default. If neither environment variable is set, behavior is unchanged. See [Local Setup](/cognee-mcp/mcp-local-setup) for configuration.
`recall` currently accepts dataset names, not `dataset_ids`. If Bob is querying Alice's shared dataset, `datasets="shared_dataset"` can fail even when Bob has permission to use it. In that case, either omit `datasets` to search across all accessible datasets or use the Python SDK / REST API where `dataset_ids` are supported.
Delete a single data item, a dataset, or all memory owned by the current user. See [Forget](/core-concepts/main-operations/forget).
| Parameter | Type | Default | Notes |
| ------------ | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `dataset` | `str` | `None` | Dataset name to delete entirely. |
| `everything` | `bool` | `False` | Set to `true` to delete all user-owned memory. |
| `data_id` | `str` | `None` | UUID of a single data item to delete. Must be paired with `dataset` or `dataset_id` so the owning dataset is unambiguous. |
| `dataset_id` | `str` | `None` | UUID of the dataset to delete entirely, or to scope `data_id`. |
At least one of `dataset`, `dataset_id`, `data_id`, or `everything=true` must be provided; passing `data_id` alone returns an error. Malformed UUIDs are rejected with a message rather than a traceback.
These are tools for finding other tools. `search_tools` searches the server's own tool catalog by natural-language query, and `call_tool` invokes a tool found that way — together they let an agent reach every registered tool without all of them being in `tools/list`.
The pair only exists in `default` and `minimal` mode. In `all` mode the server does not create them: every tool is already in `tools/list`, so there is nothing to search for (see [Tool modes](#tool-modes)).
Find registered tools by natural-language query. Returns a JSON array of matching tools, each with its `name`, `description`, full `inputSchema`, and any UI metadata — enough to call the tool without another round trip. Returns empty content when nothing matches.
| Parameter | Type | Default | Notes |
| --------- | ----- | -------- | ------------------------------------------------------------------------- |
| `query` | `str` | required | Natural-language description of what you need, e.g. `"list my datasets"`. |
At most 10 tools are returned, and tools already in `tools/list` are never among them. Matching is lexical and does not stem words, so multi-word, natural phrasings work best — for example `"is my background ingestion finished?"` returns `cognify_status`.
Invoke a tool by name without it being in `tools/list` — typically one just found through `search_tools`. Calling the found tool directly by name works just as well; the proxy exists for clients that only invoke listed tools.
| Parameter | Type | Default | Notes |
| ----------- | -------- | -------- | -------------------------------------------------------------------------------------------- |
| `name` | `str` | required | Name of the tool to invoke. |
| `arguments` | `object` | — | Arguments for that tool, matching its `inputSchema`. Pass `{}` for tools without parameters. |
Returns the target tool's result unchanged. Refuses to invoke `search_tools` or `call_tool` themselves.
Check the progress of background ingestion started by `remember(background=True)`. Reports active and completed pipeline jobs for a dataset, including failures that a backgrounded call could not return inline.
| Parameter | Type | Default | Notes |
| -------------- | ----------- | ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| `dataset_name` | `str` | agent-scoped | Dataset to report on. Defaults to the MCP client's agent-scoped dataset, so each agent sees its own status. |
| `pipelines` | `list[str]` | `["cognify_pipeline"]` | Restrict the report to specific pipeline names. |
This tool is registered but not advertised: it stays out of `tools/list` in `default` and `minimal` mode, while remaining discoverable through `search_tools` and callable directly by name. It is listed in `all` mode (see [Tool modes](#tool-modes)).
Earlier versions of the server also registered `cognify`, `search`, `prune`, `improve`, `save_interaction`, `get_document`, `get_chunk_neighbors`, `list_data`, `delete`, and `delete_dataset` as MCP tools, along with the workspace UI entry points (`visualize_graph_ui`, `upload_file_ui`, `open_cognee_workspace`) and the structured JSON tools the UI used (`list_datasets_json`, `list_dataset_data_json`, `get_client_info_json`, `create_dataset_json`). The workspace UI and all of these tools have been removed in every mode — use `remember` / `recall` / `forget` instead, and reach for the Python SDK or REST API when you need lower-level control such as explicit search types, or dataset listing and creation.
## Tool Modes
An MCP client learns which tools a server offers from the server's `tools/list` response. By default, Cognee MCP keeps that list short — the memory tools above — and exposes the rest through two discovery tools: `search_tools`, which finds a tool by natural-language query, and `call_tool`, which invokes it. A shorter list costs a connected agent less context on every turn.
**Tools left out of `tools/list` stay registered and remain callable directly by name**, so clients that invoke a tool without listing it first are unaffected.
Choose how much of the catalog is listed with the `COGNEE_MCP_TOOL_MODE` environment variable (or the `--tool-mode` server argument):
| Mode | Listed in `tools/list` |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `default` (used when unset) | `remember`, `recall`, `forget`, plus `search_tools` and `call_tool` |
| `minimal` | `remember`, `recall`, `forget`, plus `search_tools` and `call_tool` |
| `all` | Every registered tool — the three memory tools and `cognify_status` — with no `search_tools` / `call_tool` |
An unrecognized value logs a warning and falls back to `default`.
`default` and `minimal` currently advertise the same set: the memory tools carry both the `default` and `memory` tags, so pinning either tag yields `remember`, `recall`, and `forget`. The two modes stay distinct because they pin by different tags — a tool added with only the `default` tag would appear in `default` but not in `minimal`.
### Finding and calling an unlisted tool
1. Call `search_tools` with a natural-language `query`. Matches are returned with their full `inputSchema`, so no extra round trip is needed before invoking one.
2. Call the tool you found, either directly by name or through the proxy: `call_tool(name="cognify_status", arguments={...})`.
Both tools are documented under **Discovery Tools** in [Available Tools](#available-tools).
If you have an integration or script that depends on the full flat `tools/list` response, set `COGNEE_MCP_TOOL_MODE=all` to restore the previous behavior. The mode is read when the server process starts, so changes require a restart. See [Local Setup](/cognee-mcp/mcp-local-setup#further-details).
## Usage Notes
* Start with `remember` to store data and `recall` to retrieve it; use `forget` to remove a single item, a dataset, or all memory owned by the current user.
* When a `remember` call would outlast your client's request deadline, pass `background=true` and poll `cognify_status` — find it with `search_tools` if your client only calls listed tools.
* For lower-level control — explicit search types, custom graph models, dataset listing and creation — use the Python SDK or REST API.
* In shared-dataset setups, prefer the Python SDK or REST API when you need UUID-based dataset scoping for a dataset the current user did not create.
## Next Steps
Learn how to use these tools with your AI development environment