Tools Reference - Cognee Documentation

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

Memory Tools

The core memory API. These tools map to Cognee’s main operations and appear in tools/list in every tool mode.

`remember`

Store content as permanent graph memory or session memory in one call. Accepts either text or a base64 file upload. See 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.

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

`recall`

Retrieve memory with auto-routing and session-aware behavior. See 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 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.

`forget`

Delete a single data item, a dataset, or all memory owned by the current user. See 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.

Discovery Tools

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

`search_tools`

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.

`call_tool`

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.

Status Tools

`cognify_status`

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

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

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

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.

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

Client Integrations

Learn how to use these tools with your AI development environment

​Available Tools

​Tool Modes

​Finding and calling an unlisted tool

​Usage Notes

​Next Steps

Client Integrations

Available Tools

Tool Modes

Finding and calling an unlisted tool

Usage Notes

Next Steps