Oms Cognee

oms-cognee

Overview

Cognee is an open-source knowledge-graph memory engine for AI agents. It combines a vector store (semantic search), a graph store (entities + relationships), and a relational store (provenance) into a single three-layer memory architecture. The canonical V1 workflow is add → cognify → search: ingest data, build a knowledge graph, then query it. The new V2 memory-oriented API wraps this as remember → recall with an optional improve/forget/serve/agent_memory layer for agent contexts.

• Source: topoteretes/cognee @ v1.0.0 (commit 3c048aa4) [SRC:pyproject.toml:L4]
• Language: Python >=3.10, <3.14 [SRC:pyproject.toml:L10]
• Forge tier: Deep (AST + ccc + QMD + docs fetch)
• Public exports: 34 top-level names in cognee/__init__.py [AST:cognee/__init__.py:L1]
• Confidence: All T1 (AST-verified from source clone)
• Async model: Cognee is async-first — nearly all top-level functions are coroutines and must be awaited [EXT:https://docs.cognee.ai/getting-started/quickstart]

Quick Start

import asyncio
import cognee
from cognee import SearchType

async def main():
    # (optional) start from a clean slate
    await cognee.prune.prune_data()
    await cognee.prune.prune_system(metadata=True)

    # 1) Ingest data — text, file path, URL, or list of any of those
    await cognee.add(
        "Cognee turns documents into AI memory.",
        dataset_name="main_dataset",
    )

    # 2) Build the knowledge graph
    await cognee.cognify(datasets="main_dataset")

    # 3) Query the graph with graph-backed LLM completion (default)
    results = await cognee.search(
        query_text="What does Cognee do?",
        query_type=SearchType.GRAPH_COMPLETION,
    )
    for r in results:
        print(r)

if __name__ == "__main__":
    asyncio.run(main())

V2 memory-oriented shortcut (same workflow, simpler API):

import asyncio
import cognee

async def main():
    result = await cognee.remember("Cognee turns documents into AI memory.")
    print(result)  # RememberResult — await it to block until cognify completes
    answers = await cognee.recall("What does Cognee do?")
    for a in answers:
        print(a)

if __name__ == "__main__":
    asyncio.run(main())

Signatures: [AST:cognee/api/v1/add/add.py:L22] · [AST:cognee/api/v1/cognify/cognify.py:L44] · [AST:cognee/api/v1/search/search.py:L27] · [AST:cognee/api/v1/remember/remember.py:L339] · [AST:cognee/api/v1/recall/recall.py:L122]

Before running, set LLM_API_KEY for graph extraction and completion; Cognee defaults to OpenAI but supports litellm-compatible providers (Anthropic, Gemini, Ollama, etc.) via cognee.config.set_llm_provider(...) and friends. [AST:cognee/api/v1/config/config.py:L141] · [SRC:cognee/api/v1/add/add.py:L166]

Common Workflows

V1 — Add and process data: await cognee.add(data, dataset_name="main") → await cognee.cognify(datasets="main") → await cognee.search(query_text=..., datasets="main") [AST:cognee/api/v1/add/add.py:L22]

V2 — Remember and recall: await cognee.remember(data, dataset_name="main") → await cognee.recall(query_text="...") — wraps add+cognify into one call and search+auto-routing into another. [AST:cognee/api/v1/remember/remember.py:L339] · [AST:cognee/api/v1/recall/recall.py:L122]

Scope memory per tenant / customer / workflow with node_set: await cognee.add(data, dataset_name="agent_memory", node_set=["customer_123", "preferences"]) → await cognee.cognify(datasets="agent_memory") → await cognee.search(query_text=..., datasets="agent_memory", node_name=["customer_123"]) [SRC:cognee/skill.md:L97]

Enrich an existing graph with memify (V1) or improve (V2): await cognee.add(...) → await cognee.cognify(...) → await cognee.memify(dataset="rules_demo") → await cognee.search(query_type=SearchType.CODING_RULES, node_name=["coding_agent_rules"]) — memify creates Rule nodes with rule_associated_from edges. Equivalent V2: await cognee.improve(dataset="rules_demo", session_ids=[...]) which additionally applies feedback weights from past session Q&A. [AST:cognee/modules/memify/memify.py:L25] · [AST:cognee/api/v1/improve/improve.py:L36]

Delete data (V2): await cognee.forget(data_id=..., dataset=...) — single deletion command that replaces prune/delete/empty_dataset; supports everything=True to wipe all user data. [AST:cognee/api/v1/forget/forget.py:L15]

Connect to Cognee Cloud: await cognee.serve(url="https://my-instance.cognee.ai", api_key="ck_...") — routes subsequent remember/recall/improve/forget/visualize calls through the remote instance. await cognee.disconnect() returns to local mode. [AST:cognee/api/v1/serve/serve.py:L17] · [AST:cognee/api/v1/serve/disconnect.py:L8]

Decorate an async agent entrypoint with memory context: @cognee.agent_memory(with_memory=True, save_traces=True, memory_query_from_method="question", memory_top_k=5) — retrieves relevant memory context before the call and persists a trace after. [AST:cognee/modules/agent_memory/decorator.py:L22]

Run a custom task pipeline: from cognee.modules.pipelines import Task, run_pipeline; tasks = [Task(extract_people), Task(add_data_points)]; async for _ in run_pipeline(tasks=tasks, data=text, datasets=["people_demo"]): pass [AST:cognee/modules/pipelines/__init__.py:L1] · [EXT:https://docs.cognee.ai/guides/custom-tasks-pipelines]

Filter pipeline items with Drop: from cognee import Drop; async def skip_short(text): return Drop if len(text) < 10 else text — returning Drop from any pipeline step removes that item from the stream. [AST:cognee/pipelines/types.py:L32]

Visualize the graph: await cognee.visualize_graph("/path/to/graph.html") — writes an interactive HTML visualization. V2 alias: await cognee.visualize(...) (same function). [AST:cognee/api/v1/visualize/visualize.py:L17]

Key API Summary

V1 API (knowledge-graph primitives)

V2 memory-oriented API

Deprecations & Gotchas

Current-state deprecations and source/docs discrepancies surfaced during extraction. v1.0.0 is the first major release and introduces a new V2 API layer alongside the V1 API.

• cognee.low_level is no longer exported from cognee/__init__.py. The file cognee/low_level.py still exists and re-exports DataPoint (ExtendableDataPoint) + setup, but access it via the full path: from cognee.infrastructure.engine import ExtendableDataPoint as DataPoint or from cognee.modules.engine.operations.setup import setup. [AST:cognee/low_level.py:L1]
• cognee.run_migrations is no longer exported from cognee/__init__.py — replaced by cognee.run_startup_migrations() which runs relational + vector migrations in sequence. The standalone run_migrations function still lives at cognee/run_migrations.py:16 but must be imported directly. [AST:cognee/run_migrations.py:L80]
• cognee.delete(data_id, dataset_id, mode="soft", user=None) is deprecated since cognee v0.3.9. Use await cognee.datasets.delete_data(dataset_id=..., data_id=...) or the V2 await cognee.forget(data_id=..., dataset=...) instead. The old function is now defined in cognee/api/v1/delete/__init__.py (source file delete.py is empty) and decorated with @deprecated(version="0.3.9"). [AST:cognee/api/v1/delete/__init__.py:L1]
• cognee.pipelines has been restructured in v1.0.0. Old flat file cognee/pipelines.py is gone; the name now resolves to cognee/modules/pipelines/ (via from .modules import pipelines) for Task/run_tasks/run_pipeline, AND there's a new cognee/pipelines/ package that exports Drop and provides lazy legacy re-exports of the same names via __getattr__. Either import path (from cognee.modules.pipelines import Task or from cognee.pipelines import Task) works. [AST:cognee/modules/pipelines/__init__.py:L1] · [AST:cognee/pipelines/__init__.py:L1]
• cognee.agent_memory requires the wrapped function to be async — decorating a sync function raises CogneeValidationError. If memory_query_from_method="name" is set, the method must have a parameter literally named name. [AST:cognee/modules/agent_memory/decorator.py:L45]
• cognee.serve() without arguments triggers Auth0 Device Code Flow (interactive browser login). Pass url= + optional api_key= for non-interactive/local connections. After serve(), V2 operations route through the remote instance; V1 operations still execute locally. [AST:cognee/api/v1/serve/serve.py:L17]
• cognee.start_ui is sync (not async) and requires a pid_callback positional argument. Do not call await cognee.start_ui() — the function returns Optional[subprocess.Popen] synchronously. Signature: start_ui(pid_callback, port=3000, open_browser=True, auto_download=False, start_backend=False, backend_port=8000, start_mcp=False, mcp_port=8001). [AST:cognee/api/v1/ui/ui.py:L369]
• cognee.start_visualization_server is a module, not a function. The top-level __init__.py re-imports the submodule name. To start the visualization HTTP server, call cognee.start_visualization_server.visualization_server(port) which is synchronous. [AST:cognee/api/v1/visualize/start_visualization_server.py:L6]

See Full API Reference for complete parameter tables and behavioral notes.

Key Types

SearchType (enum) — cognee.SearchType

All modes accepted by cognee.search(query_type=...) and cognee.recall(query_type=...):

[AST:cognee/modules/search/types/SearchType.py:L4]

Task — cognee.pipelines.Task (or cognee.modules.pipelines.Task)

Constructor: Task(executable, *args, task_config=None, **kwargs). Wraps any callable (function, coroutine function, generator, or async generator). Detects type via inspect and picks the right execute path. task_config={"batch_size": N} controls batching. [AST:cognee/modules/pipelines/tasks/task.py:L24]

Drop — cognee.Drop (or cognee.pipelines.Drop)

Singleton sentinel. Returning Drop from any pipeline step filters that item out of the stream. bool(Drop) is False, repr(Drop) == "Drop". [AST:cognee/pipelines/types.py:L32]

RememberResult — cognee.RememberResult

Promise-like result returned by cognee.remember(). Printable for a quick summary; awaitable to block until the background pipeline finishes. Status values: "running", "completed", "errored", "session_stored". Attributes: dataset_name, dataset_id, session_id, pipeline_run_id, error, elapsed_seconds, content_hash. [AST:cognee/api/v1/remember/remember.py:L139]

DataPoint — cognee.infrastructure.engine.ExtendableDataPoint

Pydantic base class for graph-native entities. Assigning one DataPoint instance to another's field creates an edge; the field name becomes the edge label. Use metadata = {"index_fields": [...]} to mark which fields should be embedded in the vector store. In v1.0.0 this is no longer re-exported via cognee.low_level; import directly. [AST:cognee/low_level.py:L1] · [EXT:https://docs.cognee.ai/guides/custom-data-models]

Exceptions — cognee.exceptions

• CogneeApiError — base class (HTTP 418 default)
• CogneeSystemError — 500
• CogneeValidationError — 422
• CogneeConfigurationError — 500
• CogneeTransientError — 503

All accept (message, name, status_code, log, log_level). [AST:cognee/exceptions/exceptions.py:L7]

Architecture at a Glance

• Three-layer storage with node_set-aware graph: relational (provenance), vector (semantic), graph (entities + edges + node_set tagging). node_set tags passed to cognee.add become first-class graph nodes after cognify. [EXT:https://docs.cognee.ai/core-concepts/overview]
• V1 vs V2 APIs coexist: V1 (add → cognify → search) exposes the full graph-building primitives; V2 (remember → recall) is a thin, opinionated wrapper that folds the two most common calls into one per step, adds improve/forget/serve/agent_memory for agent workflows, and supports cloud routing via serve(). Both share the same underlying pipelines.
• Default backends (pinned in pyproject.toml): LLM via litellm / openai / instructor; vector lancedb + pylance; graph kuzu==0.11.3 + networkx; relational sqlalchemy + aiosqlite + alembic. Optional extras: neo4j, postgres (pgvector+asyncpg), fastembed, scraping, distributed (Modal). [SRC:pyproject.toml:L22]
• Async-first: every ingestion/graph/search/memify/update/remember/recall/improve/forget/serve function is a coroutine — call via await from inside an async def and drive with asyncio.run(main()). The sole exceptions are start_ui, start_visualization_server.visualization_server, and the enable_tracing/disable_tracing/get_*_trace/clear_traces family.

CLI

Cognee ships a CLI (cognee-cli) for terminal usage, but it lives outside this skill's scope. Quick reference from the upstream repo:

cognee-cli add "Cognee turns documents into AI memory."
cognee-cli cognify
cognee-cli search "What does cognee do?"
cognee-cli -ui   # Launches UI, backend API, and MCP server together

[SRC:AGENTS.md:L40] — use this skill for the Python API only; reach for cognee-cli or cognee-mcp for CLI/MCP flows.

Full API details, complete type definitions, and integration patterns: see references/full-api-reference.md. Detailed config setter reference: references/config.md. Extended core-workflow walkthrough with env matrix: references/core-workflow.md. Custom pipelines and DataPoint primitives: references/pipelines-and-datapoints.md.