cognee README

The project's README from github.com/topoteretes/cognee. As one markdown file: README.md.

Cognee Logo

Cognee - The Open-Source AI Memory Platform for Agents

Demo . Docs . Learn More · Join Discord · Join r/AIMemory . Community Plugins & Add-ons

GitHub forks GitHub stars GitHub commits GitHub tag Downloads License Contributors Sponsor

topoteretes%2Fcognee | Trendshift

Cognee is the open-source AI memory platform that gives AI agents persistent long-term memory across sessions. Ingest data in any format, build a self-hosted knowledge graph, and let every agent recall, connect, and act with full context

🌐 This README is also available in:
Deutsch | Español | Français | 日本語 | 한국어 | Português | Русский | 中文

Cognee Demo

📄 Read the research paper: Optimizing the Interface Between Knowledge Graphs and LLMs for Complex Reasoning — Markovic et al., 2025

When to use Cognee

Choose your starting point

I want to… Start here
See a memory graph without an API key Bundled demo
Build with text, code, and session memory Python quickstart
Give an existing agent memory Plugins and MCP
Run Cognee on my infrastructure Deployment options
Use a managed service Cognee Cloud

Quickstart

Requires Python 3.10–3.14.

You can install Cognee with pip, uv, or your preferred Python package manager.

uv pip install cognee

Try it without an API key

cognee-cli demo

Step 2: Configure the LLM

import os
os.environ["LLM_API_KEY"] = "YOUR OPENAI_API_KEY"

Alternatively, create a .env file using our template.

The default uses OpenAI for language models and embeddings. Processing and generated answers make provider calls. See installation, other providers, or local Ollama models for other setups.

import cognee
import asyncio


async def main():
    # Store permanently in the knowledge graph (runs add + cognify + improve)
    await cognee.remember("Cognee turns documents into AI memory.")

    # Store in session memory (fast cache, syncs to graph in background)
    await cognee.remember("User prefers detailed explanations.", session_id="chat_1")

    # Query with auto-routing (picks best search strategy automatically)
    results = await cognee.recall("What does Cognee do?")
    for result in results:
        print(result)

    # Query session memory first, fall through to graph if needed
    results = await cognee.recall("What does the user prefer?", session_id="chat_1")
    for result in results:
        print(result)

    # Delete when done
    await cognee.forget(dataset="main_dataset")


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

How Cognee works

Cognee builds connected memory from different sources. Text becomes entities, relationships, and searchable chunks; code becomes a graph of symbols and dependencies. Session distillation curates accepted lessons into permanent memory.

Text, code, and session guidance follow their ingestion paths into persistent Cognee memory

At query time, retrieval selects relevant graph, vector, or code context. Your application can inspect the retrieved evidence and use it to answer a question or continue an agent task.

Recall retrieves a document fact, a code symbol, and a learned release rule for an agent's next task

Operation What it does Learn more
remember Store content or code in permanent memory, or in a session when a session ID is supplied. Store memory
recall Retrieve context and answers, using automatic routing or a chosen search strategy. Query memory
improve Enrich memory, apply feedback, and bridge session knowledge into the graph. Improve memory
forget Remove a specific item or dataset. Delete memory

Explore the architecture and session lifecycle.

Connect your agent

Install the Claude Code plugin:

claude plugin marketplace add topoteretes/cognee-integrations
claude plugin install cognee-memory@cognee

or Codex plugin

Make sure to enable hooks:

# ~/.codex/config.toml
[features]
hooks = true

codex plugin marketplace add topoteretes/cognee-integrations --ref main
codex plugin add cognee@cognee

Follow the plugin setup guide to configure local or remote memory.

Interface Start here
Claude Code memory plugin Install and configure the plugin
OpenClaw memory plugin Install @cognee/cognee-openclaw
Cursor, Cline, and other MCP clients Cognee MCP guide and server README
Python applications Python API reference
TypeScript applications TypeScript SDK
Rust applications Cognee-RS
Applications using HTTP REST API reference

Browse the integrations repository for agent frameworks, plugins, and source connectors. Each guide describes its setup and memory capture behavior.

To inspect a local installation in the UI:

cognee-cli -ui

The UI launcher requires Node.js/npm; Docker is needed for its MCP service. See local UI setup.

Explore examples

Deploy Cognee

For a local API demo using a prebuilt image, follow the minimal Docker Compose guide. It includes a persistent-volume configuration and explains the single-user demo settings.

To run the API, UI, and MCP server from a source checkout, clone this repository, enter its directory, copy .env.template to .env, and configure your providers. Then run:

docker compose --profile ui --profile mcp up

The default ports are API 8000, UI 3000, and MCP 8001. For deployment beyond a local demo, configure authentication, persistent storage, and compatible backends using the permissions guide and deployment templates. Cognee Cloud provides the managed option.

Run the Whole Memory Layer on Postgres

Graph memory traditionally means operating a stack — a graph database for relationships, a vector database for embeddings, Redis for sessions, and a relational database for metadata — all deployed, secured, and paid for before an agent remembers anything. In cognee 1.0 you can run the entire memory layer on a single Postgres instance.

⚠️ Warning: Using Postgres as a graph store is currently a released as a demo feature. The production ready feature is available as a licenced product. Use it to demo keeping relational metadata, PGVector, and graph working together

Benchmarks and research

The BEAM evaluation measures conversational memory using synthetic long-context conversations and an LLM judge. The reported runs use Cognee's memory components with benchmark-specific data formatting, prompts, and retrieval configuration.

BEAM context Reported score (0–1) Scope
100K tokens 0.79 Fixed hybrid retrieval; four evaluation rounds over 20 questions from one held-out conversation.
10M tokens 0.67 Exploratory result; question-type routing selected and scored on the same question set, averaged over five rounds.

The two settings use different conversations, ingestion models, and retrieval-selection procedures. Read the methodology, models, limitations, and reproduction instructions before comparing these scores with other systems. The report also documents the remaining reproduction gap for the distributed 10M ingestion.

For the research behind Cognee's graph/LLM interface, see Optimizing the Interface Between Knowledge Graphs and LLMs for Complex Reasoning (Markovic et al., 2025).

Latest News

Watch Demo

Community & Support

Contributing

We welcome contributions from the community! Your input helps make Cognee better for everyone. See CONTRIBUTING.md to get started.

Code of Conduct

We're committed to fostering an inclusive and respectful community. Read our Code of Conduct for guidelines.

Research & Citation

We recently published a research paper on optimizing knowledge graphs for LLM reasoning:

@misc{markovic2025optimizinginterfaceknowledgegraphs,
      title={Optimizing the Interface Between Knowledge Graphs and LLMs for Complex Reasoning},
      author={Vasilije Markovic and Lazar Obradovic and Laszlo Hajdu and Jovan Pavlovic},
      year={2025},
      eprint={2505.24478},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2505.24478},
}

cognee (topoteretes/cognee)

Searching Database…

32.4K ·GitHub
Cognee
What is this?Cognee is an open-source AI memory platform that gives AI agents persistent long-term memory across sessions, turning text, code, and conversations into a queryable knowledge graph.
Is this a library I add to my code, or a hosted service I just connect to?It's primarily a self-hosted Python library and API that you run yourself (pip, Docker, or MCP server), with an optional managed Cognee Cloud for those who don't want to self-host.
How do I get it running?Install with pip or uv (Python 3.10-3.14), copy .env.template to .env to configure your LLM and embedding provider, then follow the Python quickstart, or run the API, UI, and MCP server together via Docker Compose.
Do I need an OpenAI API key, or can I run it fully local?By default Cognee calls OpenAI for language models and embeddings, but it also supports local Ollama models if you want to avoid API keys; the local UI needs Node.js/npm, and its MCP service needs Docker.
Can I really run the whole memory stack on just Postgres?Yes, cognee 1.0 lets you run graph, vector, and relational memory on a single Postgres instance, but this is currently a released demo feature — the production-ready version is sold as a separately licensed product.
Does my data stay on my own infrastructure?Yes, Cognee is built around a self-hosted knowledge graph, meaning you deploy and own the memory store rather than relying on a third-party backend by default.
What are the core memory operations in Cognee?Cognee exposes four operations: remember (store content), recall (retrieve context via search), improve (apply feedback and promote session lessons into permanent memory), and forget (delete an item or dataset).
How can agents connect to Cognee memory?There are ready-made Claude Code and Codex plugins, an OpenClaw plugin, MCP support for Cursor/Cline and other MCP clients, plus Python, TypeScript, and Rust SDKs and a REST API.
How well does Cognee's memory perform on benchmarks?On the BEAM conversational-memory benchmark, Cognee scored 0.79 (0-1 scale) at 100K tokens with fixed hybrid retrieval, and an exploratory 0.67 at 10M tokens using question-type routing.
Can I migrate memory from other tools into Cognee?Yes, Cognee can import memory from Mem0, Letta, Zep, or Graphiti using the COGX exchange format.
What are similar projects?semantica, EverOS, MemOS, LongMemory, MemoryBear, xerj, OpenViking, m_flow
Which topics is it in?cognitive-architecture, contributions-welcome, help-wanted, knowledge, ai-memory, good-first-issue, graph-database, memory-management, knowledge-graph, context-engineering, vector-database, agent-memory
Creator
topoteretes
Size
266 MB
Stars
32.4K
Updated
CommitOct 16Releasev1.6.5Oct 16
Age
3y
Commits · 90 Days