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 — see Default dataset resolution.
`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.
`ontology_key`	`str` or `list[str]`	`None`	One or more keys of previously uploaded ontologies used to ground entity extraction for this write. Permanent-memory mode only. Omit to keep the configured server ontology (including `ONTOLOGY_FILE_PATH`).
`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).

Selecting an uploaded ontology. Pass ontology_key to ground extraction with one or more OWL ontologies that were uploaded beforehand — a single key (ontology_key="workspace_v2") or a list (ontology_key=["organizations", "software"]). Where the keys are looked up depends on how the MCP server is running:

API mode — the keys are sent to POST /api/v1/remember as repeated ontology_key form fields and resolved against ontologies uploaded by the authenticated API user. Upload them first through POST /api/v1/ontologies as that same user.
Local mode — the keys are resolved in the default user’s local ontology store. Ontologies uploaded to a remote instance are not copied locally.

Unknown or inaccessible keys fail the write before any ingestion happens. Omitting ontology_key (or passing an empty list) preserves the configured server ontology, so existing calls are unaffected.

Ontology selection is permanent-write only: a non-empty ontology_key combined with session_id returns an error, because session-cache writes never run entity extraction. The rule is enforced both by the MCP client and by the server, so direct POST /api/v1/remember callers get a 400 for the same combination.

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

ResponseA successful call returns a single TextContent block whose first line is a memory-hit summary, followed by the result body:

3 memories found (2 from sessions, 1 from project docs)
[session] ...

The count is the number of returned entries — not top_k, and not the chunks behind a synthesized answer; system status markers are excluded. The parenthesized hints come from metadata already on the returned entries (the entry’s dataset_name, or sessions / graph for session and graph sources), so no extra lookup is made. At most three hints are listed, each truncated to 60 characters.When nothing is returned, the summary names the state and replaces the former No relevant results found. body:

Summary line	Meaning
`no matching memories`	Nothing matched, or the state could not be determined.
`still indexing — retry shortly`	Ingestion is running for the targeted datasets. Reads `still indexing — 12/40 items processed, retry shortly` when the pipeline reports progress — those are data items, not chunks.
`memory indexing failed — check cognify_status`	A pipeline run for the targeted datasets errored. Check `cognify_status`.

The same information is available to machine consumers as additive metadata on the block, at content[0]._meta["cognee/memory"]:

Field	Type	Notes
`count`	`int`	Returned entries, excluding system status markers.
`state`	`str`	One of `found`, `indexing`, `build_failed`, `none`.

The response is still exactly one text block, so existing text consumers keep working; split on the first newline to recover the body alone. Tool errors are unchanged: a single Error: <message> block with no summary line and no _meta.Empty-state diagnostics are best-effort and bounded: a recall with hits runs none at all, in-flight background ingestion for the targeted datasets short-circuits to indexing, and the status probe runs under a total five-second budget. Any failure or timeout degrades to no matching memories / none rather than blocking the response.

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 — see Default dataset resolution.
`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.

Default Dataset Resolution

remember and cognify_status pick their target dataset in this order:

The dataset_name argument, whenever the caller passes one. MCP tools are invoked by the client’s model, not by you directly, so an agent may pass a name it derived from the conversation topic (postgres_migration) even when you never named a dataset. An explicit name always wins, and the dataset is created on first write.
The agent-scoped default — <client>_memory, built from the clientInfo.name the MCP client sends when it connects (Cursor → cursor_vscode_memory, Claude Code → claude_code_memory). A trailing parenthetical appended by bridges such as mcp-remote is dropped (cursor-vscode (via mcp-remote 0.1.37) → cursor_vscode), the name is lowercased, and each run of other characters collapses to a single underscore. This is on by default so two clients do not share memory unintentionally.
main_dataset, when the client sends no identity, or when agent scoping is turned off with COGNEE_MCP_AGENT_SCOPED=false.

recall has no agent-scoped default: with datasets omitted it searches every dataset the current user can access, so content written to a per-client dataset is still retrievable without naming it.

Pinning a default dataset

Set COGNEE_MCP_AGENT_SCOPED=false in the MCP server’s environment — for a client-launched stdio server, that is the env block of its entry in the client config:

{
  "mcpServers": {
    "cognee": {
      "command": "cognee-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "LLM_API_KEY": "your-openai-api-key",
        "COGNEE_MCP_AGENT_SCOPED": "false"
      }
    }
  }
}

Every client then defaults to main_dataset, and no per-client datasets are created. The variable is read when the server process starts, so restart the client afterwards. See Local Setup for the setting in .env form. Because step 1 outranks both defaults, this pins the default only — a model that passes dataset_name explicitly still writes where it asked. To hold an LLM-driven client to one dataset, state it in the client’s own instruction file (Claude Desktop project instructions, CLAUDE.md, Cursor rules) as well:

When using cognee, always pass dataset_name="main_dataset" to remember and datasets="main_dataset" to recall. Never invent a new dataset name.

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

​Default Dataset Resolution

​Pinning a default dataset

​Usage Notes

​Next Steps

Client Integrations

Available Tools

Tool Modes

Finding and calling an unlisted tool

Default Dataset Resolution

Pinning a default dataset

Usage Notes

Next Steps