Repository: topoteretes/cognee

Stars: 16120

CLAUDE.md Copy Chapter

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview Copy Chapter

Cognee is an open-source AI memory platform that transforms raw data into persistent knowledge graphs for AI agents. It replaces traditional RAG (Retrieval-Augmented Generation) with an ECL (Extract, Cognify, Load) pipeline combining vector search, graph databases, and LLM-powered entity extraction.

Requirements: Python 3.9 - 3.12

Development Commands Copy Chapter

Setup Copy Section

Create virtual environment (recommended: uv)

uv venv && source .venv/bin/activate
Install with pip, poetry, or uv

uv pip install -e .
Install with dev dependencies

uv pip install -e ".[dev]"
Install with specific extras

uv pip install -e ".[postgres,neo4j,docs,chromadb]"
Set up pre-commit hooks

pre-commit install

Available Installation Extras Copy Section

Testing Copy Section

Run all tests

pytest
Run with coverage

pytest --cov=cognee --cov-report=html
Run specific test file

pytest cognee/tests/test_custom_model.py
Run specific test function

pytest cognee/tests/test_custom_model.py::test_function_name
Run async tests

pytest -v cognee/tests/integration/
Run unit tests only

pytest cognee/tests/unit/
Run integration tests only

pytest cognee/tests/integration/

Code Quality Copy Section

Run ruff linter

ruff check .
Run ruff formatter

ruff format .
Run both linting and formatting (pre-commit)

pre-commit run --all-files
Type checking with mypy

mypy cognee/
Run pylint

pylint cognee/

Running Cognee Copy Section

Using Python SDK

python examples/python/simple_example.py
Using CLI

cognee-cli add "Your text here"
cognee-cli cognify
cognee-cli search "Your query"
cognee-cli delete --all
Launch full stack with UI

cognee-cli -ui

Architecture Overview Copy Chapter

Core Workflow: add → cognify → search/memify Copy Section

1. add() - Ingest data (files, URLs, text) into datasets
2. cognify() - Extract entities/relationships and build knowledge graph
3. search() - Query knowledge using various retrieval strategies
4. memify() - Enrich graph with additional context and rules

Key Architectural Patterns Copy Section

#### 1. Pipeline-Based Processing
All data flows through task-based pipelines (cognee/modules/pipelines/). Tasks are composable units that can run sequentially or in parallel. Example pipeline tasks: classify_documents, extract_graph_from_data, add_data_points.

#### 2. Interface-Based Database Adapters
Multiple backends are supported through adapter interfaces:
- Graph: Kuzu (default), Neo4j, Neptune, Postgres via GraphDBInterface
- Vector: LanceDB (default), ChromaDB, PGVector via VectorDBInterface
- Relational: SQLite (default), PostgreSQL

Key files:
- cognee/infrastructure/databases/graph/graph_db_interface.py
- cognee/infrastructure/databases/vector/vector_db_interface.py

#### 3. Multi-Tenant Access Control
User → Dataset → Data hierarchy with permission-based filtering. Enable with ENABLE_BACKEND_ACCESS_CONTROL=True. Each user+dataset combination can have isolated graph/vector databases (when using supported backends: Kuzu, LanceDB, SQLite, Postgres).

Layer Structure Copy Section

API Layer (cognee/api/v1/)
    ↓
Main Functions (add, cognify, search, memify)
    ↓
Pipeline Orchestrator (cognee/modules/pipelines/)
    ↓
Task Execution Layer (cognee/tasks/)
    ↓
Domain Modules (graph, retrieval, ingestion, etc.)
    ↓
Infrastructure Adapters (LLM, databases)
    ↓
External Services (OpenAI, Kuzu, LanceDB, etc.)

Critical Data Flow Paths Copy Section

#### ADD: Data Ingestion
add() → resolve_data_directories → ingest_data → save_data_item_to_storage → Create Dataset + Data records in relational DB

Key files: cognee/api/v1/add/add.py, cognee/tasks/ingestion/ingest_data.py

#### COGNIFY: Knowledge Graph Construction
cognify() → classify_documents → extract_chunks_from_documents → extract_graph_from_data (LLM extracts entities/relationships using Instructor) → summarize_text → add_data_points (store in graph + vector DBs)

Key files:
- cognee/api/v1/cognify/cognify.py
- cognee/tasks/graph/extract_graph_from_data.py
- cognee/tasks/storage/add_data_points.py

#### SEARCH: Retrieval
search(query_text, query_type) → route to retriever type → filter by permissions → return results

Available search types (from cognee/modules/search/types/SearchType.py):
- GRAPH_COMPLETION (default) - Graph traversal + LLM completion
- GRAPH_SUMMARY_COMPLETION - Uses pre-computed summaries with graph context
- GRAPH_COMPLETION_COT - Chain-of-thought reasoning over graph
- GRAPH_COMPLETION_CONTEXT_EXTENSION - Extended context graph retrieval
- TRIPLET_COMPLETION - Triplet-based (subject-predicate-object) search
- RAG_COMPLETION - Traditional RAG with chunks
- CHUNKS - Vector similarity search over chunks
- CHUNKS_LEXICAL - Lexical (keyword) search over chunks
- SUMMARIES - Search pre-computed document summaries
- CYPHER - Direct Cypher query execution (requires ALLOW_CYPHER_QUERY=True)
- NATURAL_LANGUAGE - Natural language to structured query
- TEMPORAL - Time-aware graph search
- FEELING_LUCKY - Automatic search type selection
- CODING_RULES - Code-specific search rules

Key files:
- cognee/api/v1/search/search.py
- cognee/modules/retrieval/context_providers/TripletSearchContextProvider.py
- cognee/modules/search/types/SearchType.py

Core Data Models Copy Section

#### Engine Models (cognee/infrastructure/engine/models/)
- DataPoint - Base class for all graph nodes (versioned, with metadata)
- Edge - Graph relationships (source, target, relationship type)
- Triplet - (Subject, Predicate, Object) representation

#### Graph Models (cognee/shared/data_models.py)
- KnowledgeGraph - Container for nodes and edges
- Node - Entity (id, name, type, description)
- Edge - Relationship (source_node_id, target_node_id, relationship_name)

Key Infrastructure Components Copy Section

#### LLM Gateway (cognee/infrastructure/llm/LLMGateway.py)
Unified interface for multiple LLM providers: OpenAI, Anthropic, Gemini, Ollama, Mistral, Bedrock. Uses Instructor for structured output extraction.

#### Embedding Engines
Factory pattern for embeddings: cognee/infrastructure/databases/vector/embeddings/get_embedding_engine.py

#### Document Loaders
Support for PDF, DOCX, CSV, images, audio, code files in cognee/infrastructure/files/

Important Configuration Copy Chapter

Environment Setup Copy Section

Minimal setup (defaults to OpenAI + local file-based databases)

LLM_API_KEY="your_openai_api_key"
LLM_MODEL="openai/gpt-4o-mini"  # Default model

Important: If you configure only LLM or only embeddings, the other defaults to OpenAI. Ensure you have a working OpenAI API key, or configure both to avoid unexpected defaults.

Default databases (no extra setup needed):
- Relational: SQLite (metadata and state storage)
- Vector: LanceDB (embeddings for semantic search)
- Graph: Kuzu (knowledge graph and relationships)

All stored in .venv by default. Override with DATA_ROOT_DIRECTORY and SYSTEM_ROOT_DIRECTORY.

Switching Databases Copy Section

#### Relational Databases

PostgreSQL (requires postgres extra: pip install cognee[postgres])

DB_PROVIDER=postgres
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=cognee
DB_PASSWORD=cognee
DB_NAME=cognee_db

#### Vector Databases
Supported: lancedb (default), pgvector, chromadb, qdrant, weaviate, milvus

ChromaDB (requires chromadb extra)

VECTOR_DB_PROVIDER=chromadb
PGVector (requires postgres extra)

VECTOR_DB_PROVIDER=pgvector
VECTOR_DB_URL=postgresql://cognee:cognee@localhost:5432/cognee_db

#### Graph Databases
Supported: kuzu (default), neo4j, neptune, kuzu-remote, postgres

Neo4j (requires neo4j extra: pip install cognee[neo4j])

GRAPH_DATABASE_PROVIDER=neo4j
GRAPH_DATABASE_URL=bolt://localhost:7687
GRAPH_DATABASE_NAME=neo4j
GRAPH_DATABASE_USERNAME=neo4j
GRAPH_DATABASE_PASSWORD=yourpassword
Remote Kuzu

GRAPH_DATABASE_PROVIDER=kuzu-remote
GRAPH_DATABASE_URL=http://localhost:8000
GRAPH_DATABASE_USERNAME=your_username
GRAPH_DATABASE_PASSWORD=your_password
Postgres (requires postgres extra: pip install cognee[postgres])

Does not support raw Cypher queries, natural language search, or Graphiti.

GRAPH_DATABASE_PROVIDER=postgres
GRAPH_DATABASE_URL=postgresql+asyncpg://cognee:cognee@localhost:5432/cognee_db

LLM Provider Configuration Copy Section

Supported providers: OpenAI (default), Azure OpenAI, Google Gemini, Anthropic, AWS Bedrock, Ollama, LM Studio, Custom (OpenAI-compatible APIs)

#### OpenAI (Recommended - Minimal Setup)

LLM_API_KEY="your_openai_api_key"
LLM_MODEL="openai/gpt-4o-mini"  # or gpt-4o, gpt-4-turbo, etc.
LLM_PROVIDER="openai"

#### Azure OpenAI

LLM_PROVIDER="azure"
LLM_MODEL="azure/gpt-4o-mini"
LLM_ENDPOINT="https://YOUR-RESOURCE.openai.azure.com/openai/deployments/gpt-4o-mini"
LLM_API_KEY="your_azure_api_key"
LLM_API_VERSION="2024-12-01-preview"

#### Google Gemini (requires gemini extra)

LLM_PROVIDER="gemini"
LLM_MODEL="gemini/gemini-2.0-flash-exp"
LLM_API_KEY="your_gemini_api_key"

#### Anthropic Claude (requires anthropic extra)

LLM_PROVIDER="anthropic"
LLM_MODEL="claude-3-5-sonnet-20241022"
LLM_API_KEY="your_anthropic_api_key"

#### Ollama (Local - requires ollama extra)

LLM_PROVIDER="ollama"
LLM_MODEL="llama3.1:8b"
LLM_ENDPOINT="http://localhost:11434/v1"
LLM_API_KEY="ollama"
EMBEDDING_PROVIDER="ollama"
EMBEDDING_MODEL="nomic-embed-text:latest"
EMBEDDING_ENDPOINT="http://localhost:11434/api/embed"
HUGGINGFACE_TOKENIZER="nomic-ai/nomic-embed-text-v1.5"

#### Custom / OpenRouter / vLLM

LLM_PROVIDER="custom"
LLM_MODEL="openrouter/google/gemini-2.0-flash-lite-preview-02-05:free"
LLM_ENDPOINT="https://openrouter.ai/api/v1"
LLM_API_KEY="your_api_key"

#### AWS Bedrock (requires aws extra)

LLM_PROVIDER="bedrock"
LLM_MODEL="anthropic.claude-3-sonnet-20240229-v1:0"
AWS_REGION="us-east-1"
AWS_ACCESS_KEY_ID="your_access_key"
AWS_SECRET_ACCESS_KEY="your_secret_key"
Optional for temporary credentials:

AWS_SESSION_TOKEN="your_session_token"

#### LLM Rate Limiting

LLM_RATE_LIMIT_ENABLED=true
LLM_RATE_LIMIT_REQUESTS=60  # Requests per interval
LLM_RATE_LIMIT_INTERVAL=60  # Interval in seconds

#### Instructor Mode (Structured Output)

LLM_INSTRUCTOR_MODE controls how structured data is extracted

Each LLM has its own default (e.g., gpt-4o models use "json_schema_mode")

Override if needed:

LLM_INSTRUCTOR_MODE="json_schema_mode"  # or "tool_call", "md_json", etc.

Structured Output Framework Copy Section

Use Instructor (default, via litellm)

STRUCTURED_OUTPUT_FRAMEWORK="instructor"
Or use BAML (requires baml extra: pip install cognee[baml])

STRUCTURED_OUTPUT_FRAMEWORK="baml"
BAML_LLM_PROVIDER=openai
BAML_LLM_MODEL="gpt-4o-mini"
BAML_LLM_API_KEY="your_api_key"

Storage Backend Copy Section

Local filesystem (default)

STORAGE_BACKEND="local"
S3 (requires aws extra: pip install cognee[aws])

STORAGE_BACKEND="s3"
STORAGE_BUCKET_NAME="your-bucket-name"
AWS_REGION="us-east-1"
AWS_ACCESS_KEY_ID="your_access_key"
AWS_SECRET_ACCESS_KEY="your_secret_key"
DATA_ROOT_DIRECTORY="s3://your-bucket/cognee/data"
SYSTEM_ROOT_DIRECTORY="s3://your-bucket/cognee/system"

Extension Points Copy Chapter

Adding New Functionality Copy Section

1. New Task Type: Create task function in cognee/tasks/, return Task object, register in pipeline
2. New Database Backend: Implement GraphDBInterface or VectorDBInterface in cognee/infrastructure/databases/
3. New LLM Provider: Add configuration in LLM config (uses litellm)
4. New Document Processor: Extend loaders in cognee/modules/data/processing/
5. New Search Type: Add to SearchType enum and implement retriever in cognee/modules/retrieval/
6. Custom Graph Models: Define Pydantic models extending DataPoint in your code

Working with Ontologies Copy Section

Configuration:

ONTOLOGY_RESOLVER=rdflib  # Default: uses rdflib and OWL files
MATCHING_STRATEGY=fuzzy   # Default: fuzzy matching with 80% similarity
ONTOLOGY_FILE_PATH=/path/to/your/ontology.owl  # Full path to ontology file

Implementation: cognee/modules/ontology/

Branching Strategy Copy Chapter

IMPORTANT: Always branch from dev, not main. The dev branch is the active development branch.

git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name

Code Style Copy Chapter

- Formatter: Ruff (configured in pyproject.toml)
- Line length: 100 characters
- String quotes: Use double quotes " not single quotes ' (enforced by ruff-format)
- Pre-commit hooks: Run ruff linting and formatting automatically
- Type hints: Encouraged (mypy checks enabled)
- Important: Always run pre-commit run --all-files before committing to catch formatting issues

Testing Strategy Copy Chapter

Tests are organized in cognee/tests/:
- unit/ - Unit tests for individual modules
- integration/ - Full pipeline integration tests
- cli_tests/ - CLI command tests
- tasks/ - Task-specific tests

When adding features, add corresponding tests. Integration tests should cover the full add → cognify → search flow.

API Structure Copy Chapter

FastAPI application with versioned routes under cognee/api/v1/:
- /add - Data ingestion
- /cognify - Knowledge graph processing
- /search - Query interface
- /memify - Graph enrichment
- /datasets - Dataset management
- /users - Authentication (if REQUIRE_AUTHENTICATION=True)
- /visualize - Graph visualization server

Python SDK Entry Points Copy Chapter

Main functions exported from cognee/__init__.py:
- add(data, dataset_name) - Ingest data
- cognify(datasets) - Build knowledge graph
- search(query_text, query_type) - Query knowledge
- memify(extraction_tasks, enrichment_tasks) - Enrich graph
- delete(data_id) - Remove data
- config() - Configuration management
- datasets() - Dataset operations

All functions are async - use await or asyncio.run().

Security Considerations Copy Chapter

Several security environment variables in .env:
- ACCEPT_LOCAL_FILE_PATH - Allow local file paths (default: True)
- ALLOW_HTTP_REQUESTS - Allow HTTP requests from Cognee (default: True)
- ALLOW_CYPHER_QUERY - Allow raw Cypher queries (default: True)
- REQUIRE_AUTHENTICATION - Enable API authentication (default: False)
- ENABLE_BACKEND_ACCESS_CONTROL - Multi-tenant isolation (default: True)

For production deployments, review and tighten these settings.

Common Patterns Copy Chapter

Creating a Custom Pipeline Task Copy Section

from cognee.modules.pipelines.tasks.Task import Task
async def my_custom_task(data):
    # Your logic here
    processed_data = process(data)
    return processed_data
Use in pipeline

task = Task(my_custom_task)

Accessing Databases Directly Copy Section

from cognee.infrastructure.databases.graph import get_graph_engine
from cognee.infrastructure.databases.vector import get_vector_engine
graph_engine = await get_graph_engine()
vector_engine = await get_vector_engine()

Using LLM Gateway Copy Section

from cognee.infrastructure.llm.get_llm_client import get_llm_client
llm_client = get_llm_client()
response = await llm_client.acreate_structured_output(
    text_input="Your prompt",
    system_prompt="System instructions",
    response_model=YourPydanticModel
)

Key Concepts Copy Chapter

Datasets Copy Section

Create/use a dataset

await cognee.add(data, dataset_name="my_project")
await cognee.cognify(datasets=["my_project"])

DataPoints Copy Section

Permissions System Copy Section

Graph Visualization Copy Section

Via CLI

cognee-cli -ui  # Launches full stack with UI at http://localhost:3000
Via Python

from cognee.api.v1.visualize import start_visualization_server
await start_visualization_server(port=8080)

Debugging & Troubleshooting Copy Chapter

Debug Configuration Copy Section

Common Issues Copy Section

Ollama + OpenAI Embeddings NoDataError
- Issue: Mixing Ollama with OpenAI embeddings can cause errors
- Solution: Configure both LLM and embeddings to use the same provider, or ensure HUGGINGFACE_TOKENIZER is set when using Ollama

LM Studio Structured Output
- Issue: LM Studio requires explicit instructor mode
- Solution: Set LLM_INSTRUCTOR_MODE="json_schema_mode" (or appropriate mode)

Default Provider Fallback
- Issue: Configuring only LLM or only embeddings defaults the other to OpenAI
- Solution: Always configure both LLM and embedding providers, or ensure valid OpenAI API key

Permission Denied on Search
- Behavior: Returns empty list rather than error (prevents information leakage)
- Solution: Check dataset permissions and user access rights

Database Connection Issues
- Check: Verify database URLs, credentials, and that services are running
- Docker users: Use DB_HOST=host.docker.internal for local databases

Rate Limiting Errors
- Enable client-side rate limiting: LLM_RATE_LIMIT_ENABLED=true
- Adjust limits: LLM_RATE_LIMIT_REQUESTS and LLM_RATE_LIMIT_INTERVAL

Resources Copy Chapter

- Documentation
- Discord Community
- GitHub Issues
- Example Notebooks
- Research Paper - Optimizing knowledge graphs for LLM reasoning

README.md Copy Chapter

<div align="center">
<a href="https://github.com/topoteretes/cognee">
<img src="https://raw.githubusercontent.com/topoteretes/cognee/refs/heads/dev/assets/cognee-logo-transparent.png" alt="Cognee Logo" height="60">
</a>

<br />

Cognee - Build AI memory with a Knowledge Engine that learns

<p align="center">
<a href="https://www.youtube.com/watch?v=8hmqS2Y5RVQ&t=13s">Demo</a>
.
<a href="https://docs.cognee.ai/">Docs</a>
.
<a href="https://cognee.ai">Learn More</a>
·
<a href="https://discord.gg/NQPKmU5CCg">Join Discord</a>
·
<a href="https://www.reddit.com/r/AIMemory/">Join r/AIMemory</a>
.
<a href="https://github.com/topoteretes/cognee-community">Community Plugins & Add-ons</a>
</p>

<a href="https://github.com/sponsors/topoteretes"><img src="https://img.shields.io/badge/Sponsor-❤️-ff69b4.svg" alt="Sponsor"></a>

<p>
<a href="https://trendshift.io/repositories/13955" target="_blank" style="display:inline-block;">
<img src="https://trendshift.io/api/badge/repositories/13955" alt="topoteretes%2Fcognee | Trendshift" width="250" height="55" />
</a>
</p>

Use our knowledge engine to build personalized and dynamic memory for AI Agents.

<p align="center">
🌐 Available Languages
:
<!-- Keep these links. Translations will automatically update with the README. -->
<a href="https://www.readme-i18n.com/topoteretes/cognee?lang=de">Deutsch</a> |
<a href="https://www.readme-i18n.com/topoteretes/cognee?lang=es">Español</a> |
<a href="https://www.readme-i18n.com/topoteretes/cognee?lang=fr">Français</a> |
<a href="https://www.readme-i18n.com/topoteretes/cognee?lang=ja">日本語</a> |
<a href="README_ko.md">한국어</a> |
<a href="https://www.readme-i18n.com/topoteretes/cognee?lang=pt">Português</a> |
<a href="https://www.readme-i18n.com/topoteretes/cognee?lang=ru">Русский</a> |
<a href="https://www.readme-i18n.com/topoteretes/cognee?lang=zh">中文</a>
</p>

<div style="text-align: center">
<img src="https://raw.githubusercontent.com/topoteretes/cognee/refs/heads/main/assets/cognee_benefits.png" alt="Why cognee?" width="80%" />
</div>
</div>

About Cognee Copy Chapter

Cognee is an open-source knowledge engine that lets you ingest data in any format or structure and continuously learns to provide the right context for AI agents. It combines vector search, graph databases and cognitive science approaches to make your documents both searchable by meaning and connected by relationships as they change and evolve.

:star: _Help us reach more developers and grow the cognee community. Star this repo!_

:books: _Check our detailed documentation for setup and configuration._

:crab: _Available as a plugin for your OpenClaw — cognee-openclaw_

✴️ _Available as a plugin for your Claude Code — claude-code-plugin_

Cognee memory plugin

Why use Cognee: Copy Section

- Knowledge infrastructure — unified ingestion, graph/vector search, runs locally, ontology grounding, multimodal
- Persistent and Learning Agents - learn from feedback, context management, cross-agent knowledge sharing
- Reliable and Trustworthy Agents - agentic user/tenant isolation, traceability, OTEL collector, audit traits

Product Features Copy Section

<p align="center">
<img src="assets/cognee_products.png" alt="Cognee Products" width="80%" />
</p>

Basic Usage & Feature Guide Copy Chapter

To learn more, check out this short, end-to-end Colab walkthrough of Cognee's core features.


Quickstart Copy Chapter

Let’s try Cognee in just a few lines of code.

Prerequisites Copy Section

- Python 3.10 to 3.13

Step 1: Install Cognee Copy Section

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

uv pip install cognee

Step 2: Configure the LLM Copy Section

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

To integrate other LLM providers, see our LLM Provider Documentation.

Step 3: Run the Pipeline Copy Section

Cognee's API gives you four operations — remember, recall, forget, and improve:

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())

Use the Cognee CLI Copy Section

cognee-cli remember "Cognee turns documents into AI memory."
cognee-cli recall "What does Cognee do?"
cognee-cli forget --all

To open the local UI, run:

cognee-cli -ui

Use with AI Agents Copy Chapter

Claude Code Copy Section

Install the Cognee memory plugin to give Claude Code persistent memory across sessions. The plugin automatically captures tool calls into session memory via hooks and syncs to the permanent knowledge graph at session end.

Setup:

Install cognee

pip install cognee
Configure

export LLM_API_KEY="your-openai-key"
Clone the plugin

git clone https://github.com/topoteretes/cognee-integrations.git
Enable it (add to ~/.zshrc for permanent use)

claude --plugin-dir ./cognee-integrations/integrations/claude-code

Or connect to Cognee Cloud instead of running locally:

export COGNEE_SERVICE_URL="https://your-instance.cognee.ai"
export COGNEE_API_KEY="ck_..."

The plugin hooks into Claude Code's lifecycle — SessionStart initializes memory, PostToolUse captures actions, UserPromptSubmit injects relevant context, PreCompact preserves memory across context resets, and SessionEnd bridges session data into the permanent graph.

Hermes Agent Copy Section

Enable Cognee as the memory provider in Hermes Agent for session-aware knowledge graph memory with auto-routing recall.

Setup:

~/.hermes/config.yaml

memory:
  provider: cognee

export LLM_API_KEY="your-openai-key"
hermes  # start chatting — session memory and graph persistence are automatic

Or run hermes memory setup and select Cognee. For Cognee Cloud, set COGNEE_SERVICE_URL and COGNEE_API_KEY in ~/.hermes/.env.

Connect to Cognee Cloud Copy Section

Point any Python agent at a managed Cognee instance — all SDK calls route to the cloud:

import cognee
await cognee.serve(url="https://your-instance.cognee.ai", api_key="ck_...")
await cognee.remember("important context")
results = await cognee.recall("what happened?")
await cognee.disconnect()

Examples Copy Chapter

Browse more examples in the examples/ folder — demos, guides, custom pipelines, and database configurations.

Use Case 1 — Customer Support Agent

Goal: Resolve customer issues using their personal data across finance, support, and product history.
User: "My invoice looks wrong and the issue is still not resolved."
Cognee tracks: past interactions, failed actions, resolved cases, product history
Agent response:

Agent: "I found 2 similar billing cases resolved last month.
        The issue was caused by a sync delay between payment
        and invoice systems — a fix was applied on your account."
What happens under the hood:

- Unifies data sources from various company channels
- Reconstructs the interaction timeline and tracks outcomes
- Retrieves similar resolved cases
- Maps to the best resolution strategy
- Updates memory after execution so the agent never repeats the same mistake

Use Case 2 — Expert Knowledge Distillation (SQL Copilot)

Goal: Help junior analysts solve tasks by reusing expert-level queries, patterns, and reasoning.
User: "How do I calculate customer retention for this dataset?"
Cognee tracks: expert SQL queries, workflow patterns, schema structures, successful implementations
Agent response:

Agent: "Here's how senior analysts solved a similar retention query.
        Cognee matched your schema to a known structure and adapted
        the expert's logic to fit your dataset."
What happens under the hood:

- Extracts and stores patterns from expert SQL queries and workflows
- Maps the current schema to previously seen structures
- Retrieves similar tasks and their successful implementations
- Adapts expert reasoning to the current context
- Updates memory with new successful patterns so junior analysts perform at near-expert level

Deploy Cognee Copy Chapter

Use Cognee Cloud for a fully managed experience, or self-host with one of the 1-click deployment configurations below.

| Platform | Best For | Command |
|----------|----------|---------|
| Cognee Cloud | Managed service, no infrastructure to maintain | Sign up or await cognee.serve() |
| Modal | Serverless, auto-scaling, GPU workloads | bash distributed/deploy/modal-deploy.sh |
| Railway | Simplest PaaS, native Postgres | railway init && railway up |
| Fly.io | Edge deployment, persistent volumes | bash distributed/deploy/fly-deploy.sh |
| Render | Simple PaaS with managed Postgres | Deploy to Render button |
| Daytona | Cloud sandboxes (SDK or CLI) | See distributed/deploy/daytona_sandbox.py |

See the distributed/ folder for deploy scripts, worker configurations, and additional details.

Latest News Copy Chapter


Community & Support Copy Chapter

Contributing Copy Section

Code of Conduct Copy Section

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

Research & Citation Copy Chapter

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},
}