Tools Reference - Cognee Documentation

Cognee MCP exposes tools for memory management, the Cognee workspace UI, and dataset operations. 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.

Provide either data or content_base64 (optionally with filename). Passing both, or neither, returns an error.

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 dataset or wipe all memory owned by the current user. See Forget.

Parameter	Type	Default	Notes
`dataset`	`str`	`None`	Dataset name to delete.
`everything`	`bool`	`False`	Set to `true` to delete all user-owned memory.

At least one of dataset or everything=true must be provided.

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 — a bare query of dataset matches create_dataset_json but not list_datasets_json.

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

Workspace UI Tools

Entry points for the Cognee workspace UI in MCP hosts that support MCP Apps (for example Cursor and Claude Desktop). Listed in tools/list in default mode.

`visualize_graph_ui`

Open the workspace UI and render the current knowledge graph. The UI also lets the user upload files to memory.

Parameter	Type	Default	Notes
`dataset_name`	`str`	`None`	Dataset whose graph to render.

`upload_file_ui`

Open the workspace UI so the user can upload files to memory. The UI also shows the current knowledge graph. No parameters.

`open_cognee_workspace`

Open the workspace UI for generic intents such as “open cognee”. Provides dataset management, file upload, text ingestion, search, and graph visualization. No parameters.

Workspace Data Tools

Structured JSON tools used by the workspace UI. In default and minimal mode they do not appear in tools/list, but stay callable by name and discoverable through search_tools (see Tool modes). Results are returned in structuredContent.

`list_datasets_json`

List datasets. Returns {datasets: [{id, name}, ...]}. No parameters.

`list_dataset_data_json`

List data items in a dataset. Returns {data: [{id, name}, ...]}.

Parameter	Type	Default	Notes
`dataset_id`	`str`	required	Dataset UUID.

`get_client_info_json`

Return the current MCP client identity and its agent-scoped default dataset, creating the dataset on demand. Returns {client: {name, version}, default_dataset}. No parameters.

`create_dataset_json`

Create an empty dataset with the given name (idempotent). Returns {dataset: {id, name}}.

Parameter	Type	Default	Notes
`name`	`str`	required	Dataset name.

Earlier versions of the server also registered cognify, search, prune, improve, save_interaction, get_document, get_chunk_neighbors, list_data, delete, delete_dataset, and cognify_status as MCP tools. These 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 per-item deletes.

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 and workspace UI 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 — including the Cognee workspace UI — 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`, `visualize_graph_ui`, `upload_file_ui`, `open_cognee_workspace`, plus `search_tools` and `call_tool`
`minimal`	`remember`, `recall`, `forget`, plus `search_tools` and `call_tool`
`all`	Every registered tool, with no `search_tools` / `call_tool`

An unrecognized value logs a warning and falls back to default.

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="list_datasets_json", 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 dataset or wipe all memory owned by the current user.
The workspace data tools exist for the workspace UI, but an agent can use them too — find them with search_tools when you need dataset IDs or programmatic dataset creation.
For lower-level control — explicit search types, custom graph models, per-item deletes — 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