cognee-mcp

by topoteretes

Overview Schema Source Related Servers Discussions Admin

Python

Local

remember

Store text or files as permanent graph memory or in session cache, building knowledge graphs for AI agents and apps.

Instructions

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, then the self-improvement loop (improve) unless self_improvement=False.

With session_id (session memory): Stores the data in the session cache. Direct mode may also bridge it to the graph in the background; API mode uses typed cache entries and does not bridge to the graph. 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.

Input Schema

Name	Required	Description
`data`	No	The text content to store. Mutually exclusive with filename/content_base64.
`filename`	No	Original filename for a file upload. Used to derive the stored document's name. Requires content_base64.
`node_set`	No	Node-set names to file the data under, the same names recall filters on with node_name. Permanent memory tags the ingested data. With session_id the first write that carries one pins it on the session; later writes must repeat it or omit it, and a different set is refused, so one session never spans two node sets. improve() keeps the pinned set on everything it bridges from the session into the graph. Used for per-project memory.
`background`	No	Queue 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_id`	No	Session ID. Stores in cache; direct mode may also bridge to the graph unless self_improvement is False.
`dataset_name`	No	Target 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.
`ontology_key`	No	One or more uploaded ontology keys for extraction (permanent mode only). API mode uses ontologies uploaded by the authenticated API user. Local mode uses the default user's ontology store. Omit to keep the configured server ontology.
`custom_prompt`	No	Custom prompt for entity extraction (permanent mode only).
`content_base64`	No	Base64-encoded file content to ingest. Requires filename.
`self_improvement`	No	False skips automatic improvement after permanent ingestion; add and cognify still run. In direct session mode, False disables the background session-to-graph bridge. API session entries are cache-only regardless of this flag. Default True.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.6.5Oct 17, 2026

addedInput schema / properties / node_set

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Node-set names to file the data under, the same names recall filters\non with node_name. Permanent memory tags the ingested data. With\nsession_id the first write that carries one pins it on the session;\nlater writes must repeat it or omit it, and a different set is\nrefused, so one session never spans two node sets. improve() keeps\nthe pinned set on everything it bridges from the session into the\ngraph. Used for per-project memory."
+}

Changed2 schema fields changedv1.6.1Sep 24, 2026

changedInput schema / properties / self_improvement / description

Previous value: -"Run the improve loop (triplet enrichment and, with sessions, the\nsession bridge) after cognify. Permanent mode only; default True.\nPass False for a plain add + cognify ingestion."New value: +"False skips automatic improvement after permanent ingestion; add and\ncognify still run. In direct session mode, False disables the background\nsession-to-graph bridge. API session entries are cache-only regardless\nof this flag. Default True."

changedInput schema / properties / session_id / description

Previous value: -"Session ID. When set, stores in session cache only."New value: +"Session ID. Stores in cache; direct mode may also bridge to the graph\nunless self_improvement is False."

Changed14 schema fields changedv1.6.0Sep 19, 2026

addedInput schema / properties / content_base64 / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / properties / content_base64 / type
```
Removed value: -"string"
```

addedInput schema / properties / custom_prompt / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / properties / custom_prompt / type
```
Removed value: -"string"
```

addedInput schema / properties / data / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / properties / data / type
```
Removed value: -"string"
```

addedInput schema / properties / dataset_name / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / properties / dataset_name / type
```
Removed value: -"string"
```

addedInput schema / properties / filename / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / properties / filename / type
```
Removed value: -"string"
```

addedInput schema / properties / ontology_key

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "One or more uploaded ontology keys for extraction (permanent mode only).\nAPI mode uses ontologies uploaded by the authenticated API user. Local\nmode uses the default user's ontology store. Omit to keep the configured\nserver ontology."
+}

addedInput schema / properties / self_improvement

Added value: +{
+  "default": true,
+  "description": "Run the improve loop (triplet enrichment and, with sessions, the\nsession bridge) after cognify. Permanent mode only; default True.\nPass False for a plain add + cognify ingestion.",
+  "type": "boolean"
+}

addedInput schema / properties / session_id / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / properties / session_id / type
```
Removed value: -"string"
```

Changed1 schema field changedv1.5.1Aug 22, 2026

addedInput schema / properties / background

Added value: +{
+  "default": false,
+  "description": "Queue permanent ingestion as a background task and return immediately\ninstead of waiting for the pipeline. Use when the caller has a request\ndeadline shorter than ingestion takes. Ignored with session_id, which\nis already fast. Errors surface via cognify_status, not the return\nvalue.",
+  "type": "boolean"
+}

Changed15 schema fields changedv1.5.0Aug 19, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / content_base64

Added value: +{
+  "default": null,
+  "description": "Base64-encoded file content to ingest. Requires filename.",
+  "type": "string"
+}

addedInput schema / properties / custom_prompt / description

Added value: +"Custom prompt for entity extraction (permanent mode only)."

removedInput schema / properties / custom_prompt / title
```
Removed value: -"Custom Prompt"
```
addedInput schema / properties / data / default
```
Added value: +null
```

addedInput schema / properties / data / description

Added value: +"The text content to store. Mutually exclusive with\nfilename/content_base64."

removedInput schema / properties / data / title
```
Removed value: -"Data"
```

addedInput schema / properties / dataset_name / description

Added value: +"Target dataset name. Defaults to the current MCP client's\nagent-scoped dataset (e.g. \"cursor_vscode_memory\"), or\n\"main_dataset\" if no client identity is detected."

removedInput schema / properties / dataset_name / title
```
Removed value: -"Dataset Name"
```

addedInput schema / properties / filename

Added value: +{
+  "default": null,
+  "description": "Original filename for a file upload. Used to derive the stored\ndocument's name. Requires content_base64.",
+  "type": "string"
+}

addedInput schema / properties / session_id / description

Added value: +"Session ID. When set, stores in session cache only."

removedInput schema / properties / session_id / title
```
Removed value: -"Session Id"
```
removedInput schema / required
```
Removed value: -[
-  "data"
-]
```
removedInput schema / title
```
Removed value: -"rememberArguments"
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "result": {
+      "items": {},
+      "type": "array"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "type": "object",
+  "x-fastmcp-wrap-result": true
+}

Addedv1.4.1Jul 30, 2026
Removedv1.4.0Jul 17, 2026
First observedv1.0.1Jun 17, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses the add+cognify pipeline, the self-improvement loop and its opt-out flag, the session-to-graph background bridge, background queuing semantics (errors surface via cognify_status, not the return value), and a 10 MB upload limit. That is unusually complete side-effect and failure-mode coverage for an unannotated mutation 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 front-loaded with the two modes stated before the details, and every sentence carries information. It runs long for a tool description, though the density of distinct behaviors (modes, limits, pipeline flags) justifies most of the length.

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

Completeness5/5

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

Ten parameters are all documented, an output schema exists so return values need no explanation, and the description still supplies the mode logic, ingestion pipeline, background behavior, and size limit that an agent needs to call this correctly. Nothing material is missing.

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

Parameters4/5

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

Schema coverage is already 100%, so the baseline is 3, but the description adds functional meaning beyond the schema: session_id selects the storage mode, data vs filename/content_base64 are exclusive, and file uploads are incompatible with session_id. These mode-level semantics are not fully recoverable from the per-parameter text alone.

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?

States a specific verb and resource ('Store data in memory') and immediately partitions behavior into two named modes keyed on session_id, which makes it distinguishable from the retrieval-oriented sibling 'recall'. An agent knows both what it does and the shape of its two behavioral branches.

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?

Explicitly tells the caller when to omit session_id ('when the content should be stored as permanent graph memory'), what each mode does, and the mutual-exclusivity rule for data vs filename/content_base64. It also constrains file uploads to permanent memory only, so misuse is largely prevented.

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

Deploy Server