Skip to main content
Glama
deenesjakoruzh
topoteretes

cognee-mcp

by topoteretes
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

cognee‑mcp - Run cognee’s memory engine as a Model Context Protocol server

GitHub forks GitHub stars GitHub commits Github tag Downloads License Contributors

Build memory for Agents and query from any client that speaks MCP – in your terminal or IDE.

✨ Features

  • Multiple transports – choose Streamable HTTP --transport http (recommended for web deployments), SSE --transport sse (real‑time streaming), or stdio (classic pipe, default)

  • Cloud Mode – connect to Cognee Cloud via --serve-url or COGNEE_SERVICE_URL env var (see Connection Modes)

  • API Mode – connect to an already running Cognee FastAPI server (see Connection Modes)

  • Minimal Memory API – exposes only remember, recall, and forget for agent memory workflows

  • Integrated logging – all actions written to a rotating file (see get_log_file_location()) and mirrored to console in dev

  • Session-aware memory – store fast session cache entries or permanent graph memory through one remember tool

  • Focused recall – query memory through one recall tool with optional session and search controls

  • Simple deletion – remove a dataset or all owned memory through one forget tool

Please refer to our documentation here for further information.

Related MCP server: remembrallmcp

🚀 Quick Start

  1. Clone cognee repo

    git clone https://github.com/topoteretes/cognee.git

  2. Navigate to cognee-mcp subdirectory

    cd cognee/cognee-mcp

  3. Install uv if you don't have one

    pip install uv

  4. Install all the dependencies you need for cognee mcp server with uv

    uv sync --dev --all-extras --reinstall

  5. Activate the virtual environment in cognee mcp directory

    source .venv/bin/activate

  6. Set up your OpenAI API key in .env for a quick setup with the default cognee configurations

    LLM_API_KEY="YOUR_OPENAI_API_KEY"

  7. Run cognee mcp server with stdio (default)

    python src/server.py

    or stream responses over SSE

    python src/server.py --transport sse

    or run with Streamable HTTP transport (recommended for web deployments)

    python src/server.py --transport http --host 127.0.0.1 --port 8000 --path /mcp

You can do more advanced configurations by creating .env file using our template. To use different LLM providers / database configurations, and for more info check out our documentation.

No API key? If your MCP host grants the sampling capability, LLM_PROVIDER="mcp-sampling" delegates completions to the host's own model, so no LLM_API_KEY is needed (embeddings still need a provider). Host support varies — as of early 2026 Claude Code does not yet grant sampling (anthropics/claude-code#1785). See the "MCP sampling" section of the .env template.

🐳 Docker Usage

If you'd rather run cognee-mcp in a container, you have two options:

  1. Build locally

    1. Make sure you are in /cognee root directory and have a fresh .env containing only your LLM_API_KEY (and your chosen settings).

    2. Remove any old image and rebuild:

      docker rmi cognee/cognee-mcp:main || true
docker build --no-cache -f cognee-mcp/Dockerfile -t cognee/cognee-mcp:main .

    3. Run it:

      # For HTTP transport (recommended for web deployments)
docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
# For SSE transport
docker run -e TRANSPORT_MODE=sse --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
# For stdio transport (default)
docker run -e TRANSPORT_MODE=stdio --env-file ./.env --rm -it cognee/cognee-mcp:main

      Installing optional dependencies at runtime:

      You can install optional dependencies when running the container by setting the EXTRAS environment variable:

      # Install a single optional dependency group at runtime
docker run \
  -e TRANSPORT_MODE=http \
  -e EXTRAS=aws \
  --env-file ./.env \
  -p 8000:8000 \
  --rm -it cognee/cognee-mcp:main

# Install multiple optional dependency groups at runtime (comma-separated)
docker run \
  -e TRANSPORT_MODE=sse \
  -e EXTRAS=aws,postgres,neo4j \
  --env-file ./.env \
  -p 8000:8000 \
  --rm -it cognee/cognee-mcp:main

      Available optional dependency groups:

      • aws - S3 storage support

      • postgres / postgres-binary - PostgreSQL database support

      • neo4j - Neo4j graph database support

      • neptune - AWS Neptune support

      • chromadb - ChromaDB vector store support

      • scraping - Web scraping capabilities

      • langchain - LangChain integration

      • llama-index - LlamaIndex integration

      • anthropic - Anthropic models

      • groq - Groq models

      • mistral - Mistral models

      • ollama / huggingface - Local model support

      • docs - Document processing

      • codegraph - Code analysis

      • tracing - OpenTelemetry tracing

      • redis - Redis support

      • And more (see pyproject.toml for full list)

  2. Pull from Docker Hub (no build required):

    The image is published to Docker Hub on every push to main. If you have not cloned the repo, create the .env file the run commands expect first — it needs at least your LLM key:

    # Pull the prebuilt image
docker pull cognee/cognee-mcp:main

# Create a minimal .env in the current directory (no repo checkout required)
echo 'LLM_API_KEY="YOUR_OPENAI_API_KEY"' > .env
    # With HTTP transport (recommended for web deployments)
docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
# With SSE transport
docker run -e TRANSPORT_MODE=sse --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
# With stdio transport (default)
docker run -e TRANSPORT_MODE=stdio --env-file ./.env --rm -it cognee/cognee-mcp:main

    With runtime installation of optional dependencies:

    # Install optional dependencies from Docker Hub image
docker run \
  -e TRANSPORT_MODE=http \
  -e EXTRAS=aws,postgres \
  --env-file ./.env \
  -p 8000:8000 \
  --rm -it cognee/cognee-mcp:main

Important: Docker vs Direct Usage

Docker uses environment variables, not command line arguments:

  • ✅ Docker: -e TRANSPORT_MODE=http

  • ❌ Docker: --transport http (won't work)

Direct Python usage uses command line arguments:

  • ✅ Direct: python src/server.py --transport http

  • ❌ Direct: -e TRANSPORT_MODE=http (won't work)

Docker API Mode

To connect the MCP Docker container to a Cognee API server running on your host machine:

Simple Usage (Automatic localhost handling):

# Start your Cognee API server on the host
python -m cognee.api.client

# Run MCP container in API mode - localhost is automatically converted!
docker run \
  -e TRANSPORT_MODE=sse \
  -e API_URL=http://localhost:8000 \
  -e API_TOKEN=your_auth_token \
  -p 8001:8000 \
  --rm -it cognee/cognee-mcp:main

Note: The container will automatically convert localhost to host.docker.internal on Mac/Windows/Docker Desktop. You'll see a message in the logs showing the conversion.

Explicit host.docker.internal (Mac/Windows):

# Or explicitly use host.docker.internal
docker run \
  -e TRANSPORT_MODE=sse \
  -e API_URL=http://host.docker.internal:8000 \
  -e API_TOKEN=your_auth_token \
  -p 8001:8000 \
  --rm -it cognee/cognee-mcp:main

On Linux (use host network or container IP):

# Option 1: Use host network (simplest)
docker run \
  --network host \
  -e TRANSPORT_MODE=sse \
  -e API_URL=http://localhost:8000 \
  -e API_TOKEN=your_auth_token \
  --rm -it cognee/cognee-mcp:main

# Option 2: Use host IP address
# First, get your host IP: ip addr show docker0
docker run \
  -e TRANSPORT_MODE=sse \
  -e API_URL=http://172.17.0.1:8000 \
  -e API_TOKEN=your_auth_token \
  -p 8001:8000 \
  --rm -it cognee/cognee-mcp:main

Environment variables for API mode:

  • API_URL: URL of the running Cognee API server

  • API_TOKEN: Authentication token (optional, required if API has authentication enabled)

Note: When running in API mode:

  • Database migrations are automatically skipped (API server handles its own DB)

  • Some features are limited (see API Mode Limitations)

🔗 MCP Client Configuration

After starting your Cognee MCP server with Docker, you need to configure your MCP client to connect to it.

SSE Transport Configuration (Recommended)

Start the server with SSE transport:

docker run -e TRANSPORT_MODE=sse --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main

Configure your MCP client:

Claude CLI (Easiest)

claude mcp add cognee-sse -t sse http://localhost:8000/sse

Verify the connection:

claude mcp list

You should see your server connected:

Checking MCP server health...

cognee-sse: http://localhost:8000/sse (SSE) - ✓ Connected

Manual Configuration

Claude (~/.claude.json)

{
  "mcpServers": {
    "cognee": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "cognee-sse": {
      "url": "http://localhost:8000/sse"
    }
  }
}

HTTP Transport Configuration (Alternative)

Start the server with HTTP transport:

docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main

Configure your MCP client:

Claude CLI (Easiest)

claude mcp add cognee-http -t http http://localhost:8000/mcp

Verify the connection:

claude mcp list

You should see your server connected:

Checking MCP server health...

cognee-http: http://localhost:8000/mcp (HTTP) - ✓ Connected

Manual Configuration

Claude (~/.claude.json)

{
  "mcpServers": {
    "cognee": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "cognee-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Dual Configuration Example

You can configure both transports simultaneously for testing:

{
  "mcpServers": {
    "cognee-sse": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    },
    "cognee-http": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Note: Only enable the server you're actually running to avoid connection errors.

🌐 Connection Modes

The MCP server supports three connection modes:

Direct Mode (Default)

The MCP server directly imports and uses the cognee library with local databases (SQLite, LanceDB, Ladybug). This is the default mode with full feature support.

Cloud Mode

Connect to Cognee Cloud or a remote Cognee instance. The server calls cognee.serve() at startup, and all SDK operations transparently route to the cloud. No local databases needed.

Via CLI flags:

python src/server.py --serve-url https://your-instance.cognee.ai --serve-api-key ck_...

Via environment variables (zero-config):

export COGNEE_SERVICE_URL="https://your-instance.cognee.ai"
export COGNEE_API_KEY="ck_..."
python src/server.py

Cloud Mode with Docker:

docker run \
  -e TRANSPORT_MODE=sse \
  -e COGNEE_SERVICE_URL=https://your-instance.cognee.ai \
  -e COGNEE_API_KEY=ck_... \
  -p 8000:8000 \
  --rm -it cognee/cognee-mcp:main

Cloud Mode arguments / environment variables:

  • --serve-url / COGNEE_SERVICE_URL: Cognee Cloud or remote instance URL

  • --serve-api-key / COGNEE_API_KEY: API key for the instance

Database migrations are automatically skipped in Cloud mode.

API Mode

The MCP server connects to an already running Cognee FastAPI server via HTTP requests. This is useful when:

  • You have a centralized Cognee API server running

  • You want to separate the MCP server from the knowledge graph backend

  • You need multiple MCP servers to share the same knowledge graph

Starting the MCP server in API mode:

# Start your Cognee FastAPI server first (default port 8000)
cd /path/to/cognee
python -m cognee.api.client

# Then start the MCP server in API mode
cd cognee-mcp
python src/server.py --api-url http://localhost:8000 --api-token YOUR_AUTH_TOKEN

API Mode with different transports:

# With SSE transport
python src/server.py --transport sse --api-url http://localhost:8000 --api-token YOUR_TOKEN

# With HTTP transport
python src/server.py --transport http --api-url http://localhost:8000 --api-token YOUR_TOKEN

API Mode with Docker:

# On Mac/Windows (use host.docker.internal to access host)
docker run \
  -e TRANSPORT_MODE=sse \
  -e API_URL=http://host.docker.internal:8000 \
  -e API_TOKEN=YOUR_TOKEN \
  -p 8001:8000 \
  --rm -it cognee/cognee-mcp:main

# On Linux (use host network)
docker run \
  --network host \
  -e TRANSPORT_MODE=sse \
  -e API_URL=http://localhost:8000 \
  -e API_TOKEN=YOUR_TOKEN \
  --rm -it cognee/cognee-mcp:main

Command-line arguments for API mode:

  • --api-url: Base URL of the running Cognee FastAPI server (e.g., http://localhost:8000)

  • --api-token: Authentication token for the API (optional, required if API has authentication enabled)

Docker environment variables for API mode:

  • API_URL: Base URL of the running Cognee FastAPI server

  • API_TOKEN: Authentication token (optional, required if API has authentication enabled)

API Mode behavior: The MCP server intentionally exposes only the memory API: remember, recall, and forget. In API mode these tools call the Cognee API server endpoints directly. Operational helpers such as cognify, search, list_data, delete, prune, improve, and document retrieval helpers are kept internal and are not exposed as MCP tools.

💻 Basic Usage

The MCP server exposes its functionality through tools. Call them from any MCP client (Cursor, Claude Desktop, Cline, Roo and more).

Available Tools

The MCP server exposes three tools:

  • remember: Store data in memory. Pass data for text, or filename + content_base64 to ingest an uploaded file (up to 10 MB). With session_id: fast session cache (text only). Without session_id: permanent graph memory

  • recall: Search memory with auto-routing. Searches session cache first when session_id is provided, then falls through to the permanent graph

  • forget: Delete memory by dataset name or id, a single data item by data_id, or delete all owned memory with everything=True

  • cognify_status: Check the progress of background ingestion started by remember(background=True). Unadvertised by default; discoverable via search_tools and callable by name

Tool surface (COGNEE_MCP_TOOL_MODE)

Advertising every tool up front costs agent context and hurts tool-selection accuracy, so by default the server pins a small set in tools/list and makes the rest discoverable through FastMCP's built-in search_tools. Unadvertised tools stay callable by name.

COGNEE_MCP_TOOL_MODE=default   # pinned: remember, recall, forget
COGNEE_MCP_TOOL_MODE=minimal   # pinned: remember, recall, forget
COGNEE_MCP_TOOL_MODE=all       # no search transform; advertise every tool

Also settable per-process with --tool-mode. In default/minimal an agent calls search_tools(query=...) to find a tool and either calls it by name or goes through the call_tool proxy. Tiers are declared per tool via @registry.tool(tags={...}) in src/server.py, so the pinned set is derived from the decorators rather than a separate list.

search_tools returns up to TOOL_SEARCH_MAX_RESULTS (10) tools, sized for a catalog that will grow. The window only costs context on turns that actually call search; tools/list stays constant either way. See tests/test_tool_search_benchmark.py for the recall sweep behind the number.

Writing a tool so search can find it

Search works well on natural-language queries. Every phrasing below returns its target ranked first (covered by tests/test_tool_search.py):

query

returns

"is my background ingestion finished?"

cognify_status

"check the progress of a pipeline job"

cognify_status

The one thing to know when adding a tool: matching is purely lexical. FastMCP's BM25 tokenizer does no stemming and drops tools that score zero, so a query shares no credit with a word it doesn't literally contain. Multi-word queries paper over this (they usually contain some matching token), which is why the table above passes, but terse queries won't.

So: write descriptions in the words an agent would use, including both singular and plural. Recall is bounded by vocabulary, not by TOOL_SEARCH_MAX_RESULTS. If lexical matching ever stops being enough, BaseSearchTransform leaves _search() abstract — a semantic ranker over cognee's own embeddings can be dropped in without touching the rest of the plumbing.

Agent Scoping (per-client default datasets)

By default, each MCP client gets its own auto-named dataset (e.g. Cursor → cursor_vscode_memory, Claude Code → claude_code_memory) so different agents don't share memory unintentionally. The dataset is created on demand the first time a client writes to it.

LLM-direct calls to cognify, remember, improve, and cognify_status route to the agent-scoped dataset when dataset_name is omitted. Pass dataset_name explicitly to override (e.g. dataset_name="main_dataset" still works).

To disable agent scoping and have all clients share main_dataset as the default, set in .env:

COGNEE_MCP_AGENT_SCOPED=false

When disabled, no per-client datasets are autocreated.

Per-dataset isolation (ENABLE_BACKEND_ACCESS_CONTROL)

Agent scoping decides which dataset name a tool defaults to. Whether two datasets are actually isolated at the storage layer is governed by cognee's ENABLE_BACKEND_ACCESS_CONTROL flag:

  • true (default) — each (user, dataset) pair gets its own per-dataset Kuzu + LanceDB under .cognee_system/databases/<dataset_uuid>/, and search is strictly per-dataset.

  • false — all datasets share one Kuzu graph DB and one LanceDB. The dataset filter is honored for top-level data points, but GRAPH_COMPLETION traversal can pull connected nodes from any dataset. Use for single-user local dev; also disables the API auth requirement unless REQUIRE_AUTHENTICATION=true is set explicitly.

Switching modes wipes nothing automatically — but data does not migrate. Data ingested in one mode lives at a different on-disk path than the other and won't be visible after the flip. Clean-slate when changing the flag:

# Stop server, then:
DATA_ROOT="/absolute/path/to/data-root"
rm -rf "$DATA_ROOT/.cognee_system" "$DATA_ROOT/.data_storage"
# Edit .env to flip ENABLE_BACKEND_ACCESS_CONTROL, restart, re-cognify.

(Set DATA_ROOT to whatever you used for DATA_ROOT_DIRECTORY / SYSTEM_ROOT_DIRECTORY, or your cognee install dir if you didn't set those.)

Examples:

# Store permanent memory
remember(data="Cognee MCP now exposes a focused memory API.", dataset_name="main_dataset")

# Store session memory
remember(data="Temporary working note", session_id="agent-session-1")

# Recall from memory
recall(query="What changed in the MCP server?", session_id="agent-session-1")

# Delete one dataset
forget(dataset="main_dataset")

Development and Debugging

Debugging

To use debugger, run: bash mcp dev src/server.py

Open inspector with timeout passed: http://localhost:5173?timeout=120000

To apply new changes while developing cognee you need to do:

  1. Update dependencies in cognee folder if needed

  2. uv sync --dev --all-extras --reinstall

  3. mcp dev src/server.py

Development

In order to use local cognee:

  1. Uncomment the following line in the cognee-mcp pyproject.toml file and set the cognee root path.

    #"cognee[postgres,codegraph,gemini,huggingface,docs,neo4j] @ file:/Users/<username>/Desktop/cognee"

    Remember to replace file:/Users/<username>/Desktop/cognee with your actual cognee root path.

  2. Install dependencies with uv in the mcp folder

    uv sync --reinstall

Code of Conduct

We are committed to making open source an enjoyable and respectful experience for our community. See CODE_OF_CONDUCT for more information.

💫 Contributors

Star History

Star History Chart

Available Tools

5 tools
call_toolA

Call a tool by name with the given arguments.

Use this to execute tools discovered via search_tools.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesThe name of the tool to call
argumentsNo

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not mention potential side effects, required permissions, or the fact that this tool may execute arbitrary actions. This lack of transparency is risky for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no redundant information. The description is efficient and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the basic purpose and links to search_tools, but it lacks details on error handling, return values, or behavioral constraints. Given the tool's generic nature, this is acceptable but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only the 'name' parameter has a description in the schema; 'arguments' is not described. The description adds minimal value by implying arguments are passed, but does not clarify structure or constraints, leaving significant ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (call a tool) and the target (by name with arguments), and it is distinct from the sibling tools which perform specific operations like remember or recall.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says to use this for executing tools discovered via search_tools, giving a clear use case. It does not elaborate on when not to use it, but the guidance is sufficient for typical scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

forgetA

Delete data from memory.

Can target a single data item, a specific dataset (by name or id), or everything the user owns. Removes data from the relational DB, graph DB, and vector DB.

ParametersJSON Schema
NameRequiredDescriptionDefault
data_idNoUUID of a single data item to delete. Must be paired with `dataset` or `dataset_id` so the owning dataset is unambiguous.
datasetNoDataset name to delete entirely.
dataset_idNoUUID of the dataset to delete entirely, or to scope `data_id`.
everythingNoIf true, delete ALL data across all datasets.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full disclosure burden. It does disclose the destructive scope and that data is removed from relational, graph, and vector databases, which is useful context beyond the schema. However, it omits important behavioral traits such as whether deletion is permanent/recoverable, whether permissions are required, and what happens if no targeting argument is supplied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short, front-loaded sentences plus a concise scope bullet. Every phrase adds value, with no repetition of schema fields or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has four optional parameters and no annotations, so a robust description should clarify edge cases like no-argument invocation, argument conflicts, and irreversible consequences. The existence of an output schema reduces the need to describe return values, but significant semantic guidance is still missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description paraphrases the targeting options (single item, dataset by name or id, everything) but adds no new parameter-specific semantics; for example, it does not clarify precedence or mutual exclusivity beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence 'Delete data from memory' uses a specific verb and resource, and the scope bullet (single item, dataset, or everything) clearly distinguishes it from siblings like remember, recall, and search_tools. It also states the underlying stores affected, leaving no doubt about the tool's function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies this is the deletion counterpart to remember and is appropriate whenever stored data must be removed. However, it does not explicitly state when not to use it, mention alternatives for non-destructive operations, or give guidance about argument exclusivity and fallback behavior.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recallA

Search memory with auto-routing and session awareness.

When session_id is provided without datasets or search_type, searches session cache first by keyword matching. Falls through to the permanent knowledge graph if no session results match.

Auto-routing picks the best search strategy when search_type is not specified.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesNatural language query to search for.
top_kNoMaximum results to return (default: 10).
datasetsNoComma-separated dataset names to search within.
session_idNoSession ID for session-first search.
search_typeNoOverride auto-routing. Options: GRAPH_COMPLETION, GRAPH_COMPLETION_COT, RAG_COMPLETION, CHUNKS, SUMMARIES, TEMPORAL, FEELING_LUCKY, etc.
system_promptNoOverride the synthesis prompt for completion searches. When omitted, falls back to COGNEE_MCP_RECALL_SYSTEM_PROMPT / _FILE if configured on the server.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations present, the description carries the disclosure burden and it does reveal non-obvious behavior: session-first keyword matching, fallback to the permanent knowledge graph, and automatic search-strategy selection. It does not discuss side effects, permissions, or rate limits, but for a search action the main routing behavior is transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tight and front-loaded, with the main purpose in the first sentence and exactly two supporting details about routing/fallback. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and thorough parameter documentation, the description covers the non-obvious routing behavior needed to understand the tool. It lacks explicit guidance about edge cases or alternatives, but the combination of description plus schema is adequate for confident invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema coverage is 100%, so the schema already documents all six parameters; the tool description adds useful conditional context around session_id, datasets, and search_type but does not explain query, top_k, dataset syntax, or system_prompt beyond the schema. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Search memory') and adds distinguishing behavioral qualifiers ('auto-routing and session awareness'), which separates it from the write/remove siblings (remember, forget). Subsequent sentences clarify the scope with session-cache and knowledge-graph behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear invocation context: when session_id is supplied without datasets/search_type it searches the session cache first and falls through to the knowledge graph, and auto-routing applies when search_type is omitted. It does not explicitly name alternative tools or exclusion scenarios, but the parameter-condition guidance is sufficient for most recall usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rememberA

Store data in memory.

Two modes depending on whether session_id is provided:

Without session_id (permanent memory): Runs the full add + cognify pipeline to ingest data and build the knowledge graph.

With session_id (session memory): Stores the data in the session cache only. Fast, no entity extraction. Omit session_id when the content should be stored as permanent graph memory.

Pass either data (text) or filename + content_base64 (a file upload, up to 10 MB), not both. File uploads are permanent-memory only and don't support session_id.

ParametersJSON Schema
NameRequiredDescriptionDefault
dataNoThe text content to store. Mutually exclusive with filename/content_base64.
filenameNoOriginal filename for a file upload. Used to derive the stored document's name. Requires content_base64.
backgroundNoQueue permanent ingestion as a background task and return immediately instead of waiting for the pipeline. Use when the caller has a request deadline shorter than ingestion takes. Ignored with session_id, which is already fast. Errors surface via cognify_status, not the return value.
session_idNoSession ID. When set, stores in session cache only.
dataset_nameNoTarget dataset name. Defaults to the current MCP client's agent-scoped dataset (e.g. "cursor_vscode_memory"), or "main_dataset" if no client identity is detected.
custom_promptNoCustom prompt for entity extraction (permanent mode only).
content_base64NoBase64-encoded file content to ingest. Requires filename.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden of disclosing behavior. It explains the pipeline variants, performance characteristics, error handling (errors via cognify_status), and constraints on file uploads. This is thorough for a memory storage tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections for modes and input constraints, but slightly verbose. It could be tightened while retaining key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (two modes, multiple parameters, file uploads) and the existence of an output schema, the description covers the essential nuances thoroughly. Minor omissions like return format are handled by the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents parameters. The description adds value by explaining mode interplay (e.g., background ignored with session_id) and mutual exclusivity, but many details are already in schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool stores data in memory and distinguishes two modes (permanent vs session memory) based on session_id. It explicitly contrasts with sibling tools like recall and forget.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to use each mode, when to omit session_id, and constraints on data vs file uploads (mutually exclusive). It clarifies that file uploads are permanent-only and that background mode is for avoiding deadline issues.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_toolsA

Search for tools using natural language.

Returns matching tool definitions ranked by relevance, in the same format as list_tools.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesNatural language query to search for tools

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It states that it returns matching tool definitions ranked by relevance, which is a behavioral trait. It also mentions the format is same as list_tools, which is useful. However, it doesn't disclose any side effects, rate limits, or other behavioral details. Given the tool is a search operation, this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, two sentences, and front-loaded with the purpose. Every sentence adds value: the first states what it does, the second clarifies the return format. No waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and an output schema. The description explains the return format (same as list_tools) and ranking by relevance. Given the simplicity and the presence of an output schema, the description is complete enough. It could mention that it's a read-only operation, but that's not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the single parameter 'query' as a natural language query. The description adds no additional meaning beyond that. Baseline 3 is appropriate since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: searching for tools using natural language. It specifies the action (search) and the resource (tools), and distinguishes it from siblings like list_tools by mentioning the return format. However, it doesn't explicitly differentiate from other sibling tools like call_tool, but the purpose is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: when you need to find tools by natural language query. It mentions the return format is same as list_tools, which gives some context. However, it doesn't explicitly state when to use this vs alternatives, nor does it provide exclusions or alternative tool references. The guidance is minimal but not misleading.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a distinct role: remember stores data, recall retrieves it, forget deletes it, and call_tool/search_tools handle tool execution and discovery. No two tools overlap in purpose, and the descriptions clarify boundaries (e.g., remember vs. recall).

Naming Consistency5/5

All tool names are single imperative verbs (call, remember, recall, forget, search), following a consistent pattern of action words. No naming style clashes or vague synonyms are present.

Tool Count5/5

5 tools is well-scoped for a memory management server, covering the essential operations (CRUD plus meta utilities) without redundancy. Each tool earns its place.

Completeness5/5

The toolset covers the full lifecycle of memory: store (remember), retrieve (recall), and delete (forget), including support for permanent and session contexts. The inclusion of call_tool and search_tools addresses tool discovery and execution, making the surface complete for its purpose.

Maintenance

ActivityActive
ResponsivenessWithin a week

Resources

Related MCP Connectors

Related MCP Servers

  • remembrallmcp

    roboticforce
    A
    license
    Not graded
    quality
    A
    maintenance
    Persistent knowledge memory layer for AI agents. Hybrid semantic + full-text search with pgvector, code dependency graph with blast-radius impact analysis, and incremental indexing for 7 languages. In-process ONNX embeddings, no external API required.
    46
    35
    MIT

  • dejaview-mcp

    JakeC77
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides persistent knowledge graph memory for AI agents, enabling them to store, recall, and query facts about people, projects, and relationships across sessions.
    MIT

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/topoteretes/cognee'

If you have feedback or need assistance with the MCP directory API, please join our Discord server