Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Cognee

Scalekit connector
Open markdown

The Cognee connector lets your AI agent act in each user's Cognee account. Each user connects their own Cognee API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 17 tools.

Tools
17
What they doRead · write · destructive
10 · 5 · 210 read5 write2 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Cognee connection

    In AgentKit > Connections, create a Cognee connection. The name you give it is the connection_name your code passes. See Configure connections.

    Console steps with screenshots

    Register your Cognee API key with Scalekit so it can authenticate requests on your behalf. You’ll need an API key and your Cognee Cloud API host from platform.cognee.ai.

    1. Generate an API key

      • Sign in to platform.cognee.ai and go to Dashboard → API Keys.

      • Click Create API key, enter a name (e.g., Agent Auth), and confirm.

      • Copy the key and note your API host (e.g., your-tenant.aws.cognee.ai) — you’ll need both in step 3.

    2. Create a connection

      In Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find Cognee and click Create.

    3. Create a connected account

      Go to Connected Accounts for your Cognee connection and click Add account. Fill in the required fields:

      • Your User’s ID — a unique identifier for the user in your system

      • API Key — the API key you copied in step 1

      • API Host — your Cognee Cloud API host without the https:// prefix (e.g., your-tenant.aws.cognee.ai)

      • Click Save.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'cognee'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Cognee:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'cognee_check_status',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Cognee credentials there. If your app already has a user's credentials, add the account from your backend instead, as the console steps above show. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • cognee_check_statusCheck the processing status of Cognee datasets' pipelines.Read-only

    Check status

    Check the processing status of Cognee datasets' pipelines. Use this to track an Improve run started with runInBackground=true, or to confirm ingestion/graph-building has completed before recalling.

    Inputs

    datasetarray
    JSON array of dataset UUIDs to check (from List datasets). Omit to get status for all datasets you can read.
    pipelinearray
    JSON array of pipeline names to check: 'add_pipeline' or 'cognify_pipeline'. Omit to default to cognify_pipeline.
  • cognee_get_dataset_data_rawDownload the original raw content of a single data item that was ingested into a Cognee dataset.Read-only

    Get raw data item

    Download the original raw content of a single data item that was ingested into a Cognee dataset. Use List dataset data first to find a data item's ID.

    Inputs

    data_idstringrequired
    UUID of the data item to download. Get it from List dataset data.
    dataset_idstringrequired
    UUID of the dataset that owns the data item. Get it from List datasets.
  • cognee_get_dataset_graphRetrieve the raw knowledge graph structure (nodes and edges) that Improve built for a Cognee dataset.Read-only

    Get dataset graph

    Retrieve the raw knowledge graph structure (nodes and edges) that Improve built for a Cognee dataset. Use this to inspect exactly which entities and relationships were extracted, separate from running a Recall search over them.

    Inputs

    dataset_idstringrequired
    UUID of the dataset whose graph structure to retrieve. Get it from List datasets.
  • cognee_get_dataset_schemaRetrieve the graph schema configuration (the entity and relationship types recognized when building the knowledge graph) for a Cognee dataset.Read-only

    Get dataset schema

    Retrieve the graph schema configuration (the entity and relationship types recognized when building the knowledge graph) for a Cognee dataset.

    Inputs

    dataset_idstringrequired
    UUID of the dataset whose schema to retrieve. Get it from List datasets.
  • cognee_list_dataset_dataList the individual data items stored in a Cognee dataset, with their UUIDs.Read-only

    List dataset data

    List the individual data items stored in a Cognee dataset, with their UUIDs. Use the returned data IDs with Forget to remove a single item, or to inspect what a dataset contains.

    Inputs

    dataset_idstringrequired
    UUID of the dataset whose data items to list. Get it from List datasets.
  • cognee_list_datasetsList the Cognee datasets accessible to the connected account, with their names and UUIDs.Read-only

    List datasets

    List the Cognee datasets accessible to the connected account, with their names and UUIDs. Use this to discover dataset identifiers to pass to Recall, Improve, Forget, or the status check.

    Inputs

    This tool takes no inputs.

  • cognee_list_ontologiesList the OWL ontology files uploaded to this Cognee account.Read-only

    List ontologies

    List the OWL ontology files uploaded to this Cognee account. Ontologies constrain the entity and relationship types extracted when datasets are processed by Improve.

    Inputs

    This tool takes no inputs.

  • cognee_recallRecall data previously saved to Cognee memory.Read-only

    Recall

    Recall data previously saved to Cognee memory. Runs a semantic search over the knowledge graph (and, optionally, session memory) and returns an answer or matching context. Use searchType to control the retrieval strategy.

    Inputs

    querystringrequired
    The natural-language question or search query to run against stored memory.
    datasetsarray
    JSON array of dataset names to search. Names resolve only to datasets owned by the caller. Omit to search all accessible datasets.
    nodeNamearray
    JSON array of node-set tags to restrict results to (the node_set values used when the data was remembered).
    scopearray
    JSON array selecting which memory sources to include, e.g. 'graph', 'session', 'triplets'. Omit to use the default graph search.
    searchTypestring
    Retrieval strategy. GRAPH_COMPLETION (default) returns graph context plus an LLM answer. RAG_COMPLETION uses classic retrieval-augmented generation. CHUNKS and SUMMARIES return raw matching content. FEELING_LUCKY auto-selects a strategy.one of GRAPH_COMPLETIONRAG_COMPLETIONCHUNKSSUMMARIESHYBRID_COMPLETIONTRIPLET_COMPLETIONGRAPH_COMPLETION_DECOMPOSITIONGRAPH_SUMMARY_COMPLETIONGRAPH_COMPLETION_COTGRAPH_COMPLETION_CONTEXT_EXTENSIONNATURAL_LANGUAGECYPHERTEMPORALFEELING_LUCKYCODING_RULESCHUNKS_LEXICALAGENTIC_COMPLETION
    sessionIdstring
    Session whose cached memory entries should also be searched. Pair with scope including 'session' to recall data saved with a session_id.
    systemPromptstring
    Optional instructions that guide how the answer is generated for completion-type search strategies.
    topKinteger
    Maximum number of results to consider during retrieval. Defaults to 15.

Workflows

Proxy API call
const result = await actions.request({
  connectionName: 'cognee',
  identifier: 'user_123',
  path: '/api/v1/recall',
  method: 'POST',
  body: { query: 'What plan did Acme Corp sign up for?' },
});
console.log(result.data);
Create a dataset

Provision an empty dataset up front by name. This is optional — cognee_improve creates a dataset automatically the first time you add data to it — but useful when you want the dataset’s UUID before ingesting anything.

result = actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_create_dataset",
    tool_input={"name": "sales_notes"}
)


print(result.data)  # includes the new dataset's UUID
List datasets

Discover the dataset names and UUIDs available to the connected account. Use the returned UUIDs anywhere a tool accepts datasetId — cognee_recall, cognee_improve, cognee_forget, or cognee_check_status.

result = actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_list_datasets",
    tool_input={}
)


for dataset in result.data.get("datasets", []):
    print(f"{dataset['name']}: {dataset['id']}")
Add data to a dataset

Add text to a dataset and build its knowledge graph in one call: pass the content in data, and cognee_improve ingests and graphs it.

result = actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_improve",
    tool_input={
        "data": "Acme Corp signed a 2-year contract on 2026-01-15 for the Enterprise plan.",
        "datasetName": "sales_notes",
    }
)


print(result.data)
Check pipeline status

Poll the processing status of a dataset’s ingestion or enrichment pipeline — useful after calling cognee_improve with runInBackground: true, or to confirm the knowledge graph has finished building before recalling.

result = actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_check_status",
    tool_input={
        "dataset": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
        "pipeline": ["cognify_pipeline"],
    }
)


print(result.data)
Recall by meaning

Search a dataset’s knowledge graph with a natural-language question. cognee_recall returns a graph-grounded answer by default — use searchType to switch retrieval strategies.

result = actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_recall",
    tool_input={
        "query": "What plan did Acme Corp sign up for, and when?",
        "datasets": ["sales_notes"],
        "topK": 10,
    }
)


print(result.data.get("answer"))
List the data in a dataset

Inspect the individual data items stored in a dataset, with their UUIDs. Use a returned dataId with cognee_forget to delete a single item instead of the whole dataset.

result = actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_list_dataset_data",
    tool_input={"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"}
)


for item in result.data.get("data", []):
    print(f"{item['id']}: {item.get('name', 'untitled')}")
Consolidate session memory

Bridge memory cached under a session ID into the permanent knowledge graph, so it becomes searchable by cognee_recall outside that session.

result = actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_improve",
    tool_input={
        "datasetName": "sales_notes",
        "sessionIds": ["agent-run-1718000000"],
        "runInBackground": True,  # return immediately; graph builds server-side
    }
)


print(result.data)
Delete a dataset, an item, or everything

cognee_forget deletes at three levels of scope — a single data item, a whole dataset, or (with everything) every dataset on the account. Each level is permanent and cannot be undone.

# Delete a single data item
result = actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_forget",
    tool_input={
        "datasetId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "dataId": "7b1c9f0e-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
    }
)
print(result.data)
# Delete an entire dataset by name
result = actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_forget",
    tool_input={"dataset": "sales_notes"}
)
print(result.data)
End-to-end workflow: create, improve, check status, recall, list, forget

A typical Cognee session provisions a dataset, adds data to it, waits for the graph to build, queries it, inspects what’s stored, and cleans up when it’s no longer needed.

# 1. Create the dataset up front to get its UUID
create_result = actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_create_dataset",
    tool_input={"name": "support_thread_4821"}
)
dataset_id = create_result.data["id"]


# 2. Add data and build the knowledge graph
actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_improve",
    tool_input={
        "data": "Customer reported a login failure on 2026-02-03. Root cause: expired SSO certificate. Resolved by rotating the certificate.",
        "datasetId": dataset_id,
        "runInBackground": True,
    }
)


# 3. Poll until the enrichment pipeline finishes
status_result = actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_check_status",
    tool_input={"dataset": [dataset_id]}
)
print(status_result.data)


# 4. Recall the relevant context once processing completes
recall_result = actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_recall",
    tool_input={
        "query": "Why did the customer's login fail, and how was it fixed?",
        "datasets": ["support_thread_4821"],
    }
)
print(recall_result.data.get("answer"))


# 5. List what's in the dataset before deciding to clean it up
list_result = actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_list_dataset_data",
    tool_input={"dataset_id": dataset_id}
)
print(f"{len(list_result.data.get('data', []))} item(s) in the dataset")


# 6. Forget the dataset once the thread is closed and no longer needed
actions.execute_tool(
    connection_name='cognee',
    identifier='user_123',
    tool_name="cognee_forget",
    tool_input={"datasetId": dataset_id}
)
LangChain integration

Let an LLM decide which Cognee tool to call based on natural language. This example builds an agent that can create datasets, enrich memory, recall it, inspect it, and clean it up on demand.

from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.prompts import (
    ChatPromptTemplate, SystemMessagePromptTemplate,
    HumanMessagePromptTemplate, MessagesPlaceholder, PromptTemplate
)


# Load all Cognee tools in LangChain format. Use page_size=100 so connector tool lists are not truncated.
tools = actions.langchain.get_tools(
    identifier='user_123',
    providers=["COGNEE"],
    page_size=100
)


prompt = ChatPromptTemplate.from_messages([
    SystemMessagePromptTemplate(prompt=PromptTemplate(
        input_variables=[],
        template=(
            "You are an assistant with access to Cognee memory tools. "
            "Use cognee_list_datasets to discover existing datasets, cognee_create_dataset "
            "to provision a new one, cognee_improve to add or enrich data in a dataset, "
            "cognee_check_status to confirm a pipeline has finished, cognee_recall to search "
            "stored memory by meaning, cognee_list_dataset_data to inspect what a dataset "
            "contains, and cognee_forget to delete a dataset or data item. Always "
            "confirm before calling cognee_forget."
        )
    )),
    MessagesPlaceholder(variable_name="chat_history", optional=True),
    HumanMessagePromptTemplate(prompt=PromptTemplate(
        input_variables=["input"], template="{input}"
    )),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])


llm = ChatOpenAI(model="gpt-4o")
agent = create_openai_tools_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)


result = agent_executor.invoke({
    "input": "Remember that Acme Corp renewed their contract today for the Enterprise plan, then tell me what we know about Acme Corp."
})
print(result["output"])
All 134 in AI