<div align="center">

Enhanced Cognee

Enterprise-Grade AI Memory Infrastructure with Multi-Agent Support

An enhanced fork of Cognee with 122 MCP tools, enterprise-grade multi-agent coordination, multi-tenant data partitioning, cross-language client SDKs (Python / Node / Go / Rust), encryption at rest, MCP server hardening (API-key + rate limit + payload cap), Redis-backed personalization, and production-ready security hardening

</div>

---

Latest Updates (2026-05-21)

Multi-tenant + cross-language SDKs + real benchmark baseline shipped. A 16-PR run since the 2026-05-20 update (PRs #32-#46) closed out the remaining Phase 5 work. Headline:

• Multi-tenant data partitioning (PRs #39 / #42 / #43). TenantContext ContextVar + naming helpers (tenant_scoped_table / tenant_scoped_collection / tenant_scoped_key / tenant_scoped_graph); lazy per-tenant Postgres schema bootstrap via ensure_tenant_schema using CREATE TABLE LIKE INCLUDING ALL; FastAPI X-Tenant-ID header middleware that opens the tenant context for the entire request. Wired across 24 storage modules + 100+ call sites. ENHANCED_REQUIRE_TENANT=1 production safety knob refuses un-tenanted writes. 15 cross-tenant isolation tests verify documents_t_a never bleeds into documents_t_b.
• Cross-language client SDKs (PR #41). Three new SDKs alongside the existing Python client -- clients/node/ (TypeScript, 7 tests using node:test + mocked fetch), clients/go/ (9 tests via net/http/httptest, context.Context first arg per Go idiom), clients/rust/ (7 tests via wiremock, async via tokio + reqwest/rustls). All four share the same HTTP contract (5 endpoints) and the same X-API-Key + X-Tenant-ID headers.
• 3 enterprise + 2 cloud DW relational adapters (PRs #40 / #36). MS SQL Server / Azure SQL (aioodbc), Oracle 19c-23ai / Autonomous DB (oracledb), IBM Db2 LUW (ibm_db), Snowflake (snowflake-connector-python), Databricks SQL Warehouse (databricks-sql-connector). Brings the relational tier to 10 providers (postgres / sqlite / duckdb / mysql / mariadb / mssql / oracle / db2 / snowflake / databricks; cockroachdb works via the postgres adapter).
• 3 relational adapters + cloud DW (PR #34). DuckDB (MIT embedded analytics), MySQL/MariaDB (asyncmy), CockroachDB docs-only (it speaks postgres wire so the existing adapter targets it unchanged).
• ArcadeDB dual transport (PR #33). Bolt-plugin transport (default; drop-in for the neo4j Python driver) plus a stock HTTP/JSON transport against /api/v1/command/{db} for environments where the Bolt plugin isn't available. Selected via ARCADEDB_TRANSPORT=bolt|http.
• MCP server hardening (PR #37). Optional ENHANCED_API_KEY for X-API-Key auth, per-tool token-bucket rate limiter via ENHANCED_RATE_LIMIT_PER_MINUTE, payload cap via ENHANCED_MAX_PAYLOAD_BYTES. Typed errors (RateLimitExceeded, PayloadTooLarge).
• Real benchmark baseline (PR #46). First non-synthetic baseline shipped: tests/benchmarks/baselines/2026-05-21_neo4j_stack.json (Neo4j 5.25 + Qdrant 1.12 + Valkey 8 + PostgreSQL 18 + pgvector). 60s @ 20 users @ 5 spawn-rate -> 49.06 RPS, p50=2ms, p95=7ms, p99=11ms, 2911 reqs, 0 failures. Per-permutation regression check via tests/benchmarks/compare_to_baseline.py.
• /mcp/* HTTP routes (PR #46). Six new FastAPI endpoints (add_memory / search_memories / get_memories / update_memory / delete_memory / list_agents) mirror the standard MCP tool surface over HTTP, so cross-language SDKs + Locust scenarios + any HTTP caller targeting the documented MCP contract gets a working endpoint.
• Real Redis-backed personalization (PR #46). _personalized_score in advanced_search_reranking.py now combines three signals: same-agent affinity (1.3x), interaction recency boost up to +0.5 (linear decay over a 30-day retained window), and query-affinity boost up to +0.3 (term overlap with the user's recent searches). Public record_interaction() API + rolling 20-entry search history capture on every search() call. 11 new unit tests.
• Coverage auditor + live SigNoz smoke (PR #38). tests/coverage_audit.py reads coverage.xml, reports modules below the 85% gate sorted by uncovered count; tests/integration/test_signoz_smoke.py emits an OTel span via src/tracing.py, polls SigNoz's Query Service until the span surfaces in signoz_traces.signoz_index_v2, then asserts the trace ID round-trips.
• Docs refresh. New AGENTS.md (Codex equivalent of CLAUDE.md; PR #45) -- ArcadeDB default, Valkey naming, 20+ pluggable providers, multi-tenant section, MCP hardening env knobs, body uses only ASCII so it round-trips through Windows cp1252 consoles. docs/PHASE5_TODO.md refresh (PR #44) tracks all multi-tenant + SDK sub-PRs.
• Postgres init script rewrite (PR #46). Previous version had three latent bugs: MySQL-style inline INDEX clauses (every CREATE TABLE failed with a syntax error), hardcoded ('ats', 'oma', 'smc') CHECK constraints (directly violated the dynamic-categories rule -- any custom category hit a constraint violation), and broken GET DIAGNOSTICS. Rewritten with separate CREATE INDEX statements, plain VARCHAR(100) for memory_category, per-agent legacy schemas dropped (shared_memory is now the single source of truth, per-tenant variants materialised lazily), proper ON CONFLICT unique key for the memory_usage upsert trigger.
• Test suite: 4,661 passing (4,137 unit + 93 system + others), 0 failures, 95% coverage, +707 tests since the 2026-05-20 update.

---

Latest Updates (2026-05-20)

Pluggable database stack landed (Phases 1-5). A 13-PR run since the 2026-05-18 release built out a fully-pluggable storage tier. Headline:

• 13 providers shipped across 4 tiers. You can now mix and match graph (arcadedb default / neo4j / apache_age / memgraph / kuzu / networkx_inmemory / arangodb / nebulagraph / ladybug), vector (qdrant default / pgvector / lancedb / chroma / weaviate / milvus), cache (valkey default / redis / redis_compat / in_memory / memcached), and relational (postgres default / sqlite) backends via env vars. See docs/PROFILES.md and docs/PLUGGABLE_DB_BACKENDS.md.
• ArcadeDB is the new default graph store (replacing Neo4j as the default; Neo4j remains a first-class provider). 100% Apache-2.0 graph layer. See docs/ARCADEDB_MIGRATION.md.
• Default stack is now 100% MIT + Apache-2.0. No AGPL, no SSPL, no BSL in the default profile. License audit refreshed in docs/LICENSE_AUDIT.md.
• Apache AGE native graph elements. MATCH (n) RETURN n now returns real Node/Relationship-shaped objects (PR #30); edges return start_node/end_node stubs and paths decode to ordered vertex+edge lists.
• Shared vector filter translator. All 5 vector adapters now route qdrant-style Filter(must=[FieldCondition(...)]) through a single normaliser → native dialect (pgvector SQL JSONB / Chroma where / Weaviate Filter.by_property / Milvus expr / LanceDB SQL WHERE).
• 5 importable Superset 4.x dashboards in monitoring/superset-dashboards/: memory growth, agent activity, LLM cost trends, dedup effectiveness, perf regression. With shared _dataset_definitions.yaml hitting the real schemas.
• Live AGE integration tests in CI. Dedicated postgres-age service container on port 25433 using apache/age:release_PG16_1.6.0
  • idempotent bootstrap step.
• Cross-provider benchmark runner. tests/benchmarks/run_provider_comparison.py drives Locust against 5 provider permutations and emits side-by-side RPS / p50 / p95 / p99 / error% tables (JSON + Markdown).
• Observability stack swap (Phase 4). Grafana + Loki + Tempo + Jaeger → SigNoz + Apache Superset. APM-style charts live natively in SigNoz; BI dashboards in Superset. Both fully Apache-2.0.
• Test suite: 3,954 passing, 100% success, 95% coverage, +257 integration/system tests, +13 PRs (#19-#31).

Outstanding items tracked in docs/PHASE5_TODO.md. Backlog is essentially closed pending the optional ArcadeDB-HTTP CI pivot and MAS integration (next session).

---

Latest Updates (2026-05-18)

Production-readiness sprint completed. Highlights since the previous release:

• Cache layer migrated from Redis to Valkey 8 (Apache-2.0). Wire-compatible drop-in replacement; the Python redis client library still talks to it unchanged. Eliminated Redis's BSL/SSPL/AGPLv3 license risk. See docs/LICENSE_AUDIT.md for the full audit.
• Test suite: 4,158 passing, 0 failed, 0 skipped, 0 warnings (up from 838 tests at start of sprint). Coverage 95% (up from 31%).
• 3 new undo/redo MCP tools shipped: undo_last, get_undo_history, redo_last. Total now 122 (was 119).
• 9 production bugs surfaced during the coverage push; 4 fixed in-source (secrets import, _extract_entities Neo4j corruption, timedelta import, transaction_manager return-on-success), 5 documented in tests.
• All deployment infrastructure shipped: Windows + Linux installers (deploy/local/), Hetzner CX22 VPS runbook (deploy/vps/), MAS integration guide, 10-incident operations RUNBOOK, monitoring stack (Prometheus + Grafana + Loki).
• uv-powered installs for ~20x faster setup.
• Docker container renamed: cognee-mcp-redis -> cognee-mcp-valkey (in the enhanced-cognee Compose project alongside the other 3 databases).

Full session summary in docs/SESSION_SUMMARY_2026-05-18.md.

---

Table of Contents

• Install in 30 Seconds
• Quick Comparison
• Overview
• What is Enhanced Cognee?
• New Features
• Comparison with Original Cognee
• Screenshots and Demos
• Architecture
• System Workflow
• Installation
• Quick Start
• Multi-IDE Support
• Quick Examples
• MCP Tools Reference
• How MCP Tools Work
• Agent Integration
• v1.0.9 API Parity
• Cross-Language Client SDKs
• Multi-Tenant Data Partitioning
• MCP Server Hardening
• Upstream Sync Monitoring
• Testing
• Documentation
• Configuration
• Usage Examples
• Development
• Contributing
• License
• Acknowledgments
• Project Files
• Contributors
• Roadmap
• Star History

---

Install in 30 Seconds

Windows:

git clone https://github.com/vincentspereira/Enhanced-Cognee.git
cd Enhanced-Cognee
powershell -ExecutionPolicy Bypass -File deploy/local/install.ps1

Linux / macOS:

git clone https://github.com/vincentspereira/Enhanced-Cognee.git
cd Enhanced-Cognee
./deploy/local/install.sh

Both installers are idempotent and:

• Detect Python 3.11+
• Create .venv and use uv (~20x faster than pip)
• Bring up the 4-database Docker stack (PostgreSQL + Qdrant + ArcadeDB + Valkey)
• Register the MCP server in ~/.claude.json

Full deployment guide: docs/DEPLOYMENT_QUICKSTART.md.

---

Quick Comparison

Looking for a broader market comparison? See docs/COMPARE_TO_ALTERNATIVES.md for a feature-by-feature table comparing Enhanced Cognee against Mem0, Letta (formerly MemGPT), LangChain Memory, and upstream Cognee. Includes cost tables, migration paths, and "when to choose each" recommendations.

Enhanced Cognee vs Original Cognee vs Claude-Mem

Feature	Original Cognee	Claude-Mem	Enhanced Cognee
Primary Use Case	AI agent memory platform	Claude Code session memory	Enterprise multi-agent memory
Storage	SQLite + choice of DBs	SQLite + FTS5	PostgreSQL + Qdrant + ArcadeDB + Valkey
Vector Search	Optional (LanceDB, Qdrant)	ChromaDB (optional)	Qdrant (built-in)
Graph Database	Neo4j, Kuzu, Neptune	None	ArcadeDB (default, Apache-2.0); Neo4j pluggable
Caching Layer	FsCache	None	Valkey 8 (Apache-2.0, Redis-compatible)
Installation	pip install	Plugin marketplace (1 command)	Docker compose (complex)
Configuration	Manual .env	Auto-config (zero-conf)	Manual .env + JSON
MCP Tools	cognee-mcp directory	4 search tools	122 comprehensive tools
Automatic Context Injection	No	Yes (via hooks)	No (manual)
Token Efficiency	Standard	Progressive disclosure (~10x savings)	Standard
Memory Compression	No	Yes (AI-powered)	Yes (LLM-powered)
Memory Deduplication	No	No	Yes (auto-deduplication)
TTL/Expiry	No	No	Yes (configurable)
Cross-Agent Sharing	No	No	Yes (4 policies)
Real-Time Sync	No	No	Yes (pub/sub)
Performance Monitoring	Basic logs	No	Prometheus + Grafana
Search Types	15 specialized types	FTS5 + 4 tools	15 specialized types
Multi-Language Support	English	28 languages	28 languages (detect, search, cross-language)
Session Tracking	Dataset-based	Multi-prompt sessions	Agent-based
Web Viewer	cognee-frontend	Yes (localhost:37777)	ArcadeDB Studio at localhost:22480
Memory Hierarchy	Flat	Structured observations	EAV observations (entity-attribute-value)
Scalability	Single machine	Single machine	Distributed architecture
Concurrent Agents	Limited	Not applicable	100+ agents
Enterprise Features	Basic permissions	No	RBAC, audit logging, backup
Performance	Baseline	Optimized for single user	400-700% faster
Target User	Developers	Individual developers	Enterprise teams

Decision Guide

Choose Enhanced Cognee if you need:

• Multi-agent coordination (100+ agents)
• Enterprise-grade scalability
• Knowledge graph relationships
• Cross-agent memory sharing
• Real-time synchronization
• Production deployment with monitoring

Choose Claude-Mem if you need:

• Individual developer memory
• Zero-configuration setup
• Automatic context injection
• Token-efficient search
• Session continuity
• Quick plug-and-play solution

Choose Original Cognee if you need:

• Flexible database choices
• Simple Python SDK
• Knowledge graph without enterprise features
• Basic memory functionality

---

Why Use Enhanced Cognee

If you need enterprise-grade memory across many agents

Enhanced Cognee is the right tool when you need:

• Memory shared across 10+ concurrent agents with access control
• Knowledge graph relationships (not just flat key-value storage)
• Production monitoring with Prometheus metrics
• Memory deduplication, summarization, TTL, and lifecycle policies
• Automated backup and recovery
• 122 MCP tools covering the complete memory lifecycle

How to invoke Enhanced Cognee

Step 1 - Start the database stack:

docker compose -f config/docker/docker-compose-enhanced-cognee.yml up -d

Step 2 - Start the MCP server:

python bin/enhanced_cognee_mcp_server.py

Step 3 - Connect your MCP-compatible IDE (see Multi-IDE Setup)

Step 4 - Start using memory tools. The IDE will automatically call:

• add_memory when you say "remember that..."
• search_memories when you ask about past context
• health on session start to verify connections

When to use which tool:

Your Goal	Use This Tool	Trigger
Store any knowledge	add_memory or remember	Auto / Manual
Find past information	search_memories or recall	Auto
Deep graph search (15 strategies)	recall with search_type	Manual
Ingest a website	ingest_url	Manual
Ingest a database	ingest_db	Manual
Translate stored text	translate_text	Manual
Extract named entities	regex_extract_entities	Manual
Remove outdated data	expire_memories or forget_memory	Manual
Check system health	health	Auto

Updated Decision Guide

Need	Best Choice
Single developer, zero config, quick setup	Session-memory plugin (e.g., Claude-Mem)
Multi-agent enterprise system	Enhanced Cognee
Flexible DB choice, simple SDK	Original Cognee
Knowledge graph + enterprise features + 122 MCP tools	Enhanced Cognee
Token-efficient progressive search	Session-memory plugin

---

Overview

Enhanced Cognee is an enterprise-enhanced fork of the original Cognee AI memory framework. It upgrades the memory stack with production-ready databases while maintaining compatibility with the original Cognee API and adding:

• ✅ 122 MCP tools for comprehensive memory management (including v1.0.9 session memory, web ingestion, translation, cascade v2 graph extraction, memory versioning, GDPR, plugins, webhooks)
• ✅ Dynamic category system (no hardcoded categories; configure via .enhanced-cognee-config.json)
• ✅ Automated upstream sync monitoring (GitHub Actions weekly monitor)
• ✅ Cross-agent memory sharing with access control
• ✅ Automatic memory summarization (10x storage compression)
• ✅ Memory deduplication (95%+ storage savings)
• ✅ Performance analytics with Prometheus export
• ✅ Real-time web dashboard (WebSocket-based live updates)
• ✅ Intelligent LLM summarization (multi-provider support)
• ✅ Advanced search with re-ranking (4 strategies)
• ✅ Multi-language support (28 languages with cross-language search)
• ✅ Progressive disclosure search (3-layer, 10x token efficiency)
• ✅ Lite mode (SQLite-based simplified deployment)
• ✅ Backup and recovery tools (automated with rollback)
• ✅ Memory expiry and TTL (configurable retention policies)
• ✅ Semantic memory clustering (Qdrant-powered)
• ✅ Query expansion (LLM-enhanced search)
• ✅ Production deployment (Docker, monitoring, security hardened)
• ✅ CI/CD pipeline (7 automated stages)
• ✅ Security audit (0 critical vulnerabilities)
• ✅ Comprehensive test coverage (4,661 tests, 100% pass rate)
• ✅ Support for 8 AI IDEs (Claude Code, VS Code, Cursor, Windsurf, Antigravity, Continue.dev, Kilo Code, GitHub Copilot)

What is the Original Cognee?

Cognee is an open-source AI memory framework that:

• Transforms raw data into persistent AI memory using ECL (Extract, Cognify, Load) pipelines
• Combines vector search with graph databases for semantic and relationship-based queries
• Replaces traditional RAG systems with a unified memory layer
• Provides modular, customizable data pipelines
• Offers Python SDK and CLI for easy integration

Original Cognee Repository: https://github.com/topoteretes/cognee

Original Cognee Documentation: https://docs.cognee.ai/

---

What is Enhanced Cognee?

Enhanced Cognee builds upon the original Cognee framework by replacing the default database stack with enterprise-grade alternatives and adding comprehensive multi-agent support and MCP server capabilities.

1. Enhanced Database Stack

• PostgreSQL + pgVector (instead of SQLite)
• Qdrant (instead of LanceDB)
• Neo4j (instead of Kuzu)
• Valkey 8 (Apache-2.0 cache layer, Redis-compatible)

2. 122 MCP Tools

• Standard Memory MCP tools (add_memory, search_memories, etc.)
• Session-aware memory (remember, recall, forget_memory, improve, save_interaction)
• External loaders (ingest_url, ingest_db, list_loaders)
• Translation and NER (translate_text, regex_extract_entities)
• Graph extraction (extract_graph_v2)
• Enhanced memory management (expiry, archival, TTL)
• Advanced deduplication and summarization
• Performance analytics and monitoring
• Cross-agent sharing and real-time sync
• Multi-language support (28 languages, cross-language search)
• Advanced AI features (intelligent summarization, semantic clustering, cascade v2 graph)
• Backup and recovery
• Memory versioning, provenance tracking, confidence scoring (Phase 10)
• GDPR delete/export, consent management, tenant isolation (Phase 11)
• Plugin loader system, webhook support (Phase 12)
• Encryption at rest (Fernet AES-128-CBC), structured EAV observations, Slack/Discord notifications
• Heuristic importance scoring and multi-signal re-ranking (Phase 13/14)
• Python SDK client package (enhanced_cognee_client) with 16 async methods
• 10 Architecture Decision Records (ADR-001 to ADR-010) and 10 Runbooks (RB-001 to RB-010)
• Pre-commit hooks (ruff, bandit, category gate, ASCII gate, fast unit tests at push)

3. Real-Time Multi-Agent Support

• Valkey pub/sub (Redis protocol-compatible) for instant agent coordination
• Cross-agent memory sharing with access control
• Conflict resolution for simultaneous updates
• Scalable to 100+ concurrent agents

4. Production-Ready Features

• Docker deployment with health checks
• Non-conflicting port mappings
• Comprehensive error handling
• 4,661 tests passing (100% pass rate, 0 skipped)
• Multi-IDE support (MCP-compatible IDEs)

---

New Features

✅ Implemented Features

All planned enhancements have been implemented:

1. Multi-IDE MCP Support

• ✅ Claude Code (Anthropic)
• ✅ VS Code (with Continue.dev)
• ✅ Cursor IDE
• ✅ Windsurf (Codeium)
• ✅ Antigravity
• ✅ Continue.dev Standalone
• ✅ Kilo Code (VS Code extension)
• ✅ GitHub Copilot (VS Code extension)

Setup Guide: MCP IDE Setup Guide

2. Memory Expiry & Archival Policies

• ✅ TTL-based memory expiry
• ✅ Automatic archival by category
• ✅ Retention policies (keep_all, keep_recent, archive_old, delete_old)
• ✅ Bulk TTL management

3. Performance Analytics Dashboard

• ✅ Query performance metrics (avg, min, max, P50, P95)
• ✅ Cache hit/miss tracking
• ✅ Per-agent statistics
• ✅ Prometheus metrics export
• ✅ Slow query detection

4. Advanced Semantic Search with Relevance Scoring

• ✅ Qdrant similarity scores exposed
• ✅ Text + vector hybrid search
• ✅ Relevance ranking
• ✅ Filtered search capabilities

5. Memory Deduplication

• ✅ Exact match detection
• ✅ Vector similarity (0.95 threshold)
• ✅ Auto-merge strategies
• ✅ 95%+ storage savings

6. Automatic Memory Summarization

• ✅ LLM-powered summarization
• ✅ 10x+ storage compression
• ✅ Vector embeddings preserved
• ✅ Age-based and category-based

7. Knowledge Graph Visualization

• ✅ Neo4j integration ready
• ✅ Graph visualization tools exposed
• ✅ Relationship tracking

8. Cross-Agent Memory Sharing

• ✅ 4 sharing policies (private, shared, category_shared, custom)
• ✅ Access control per agent
• ✅ Shared memory spaces
• ✅ Security enforcement

9. Real-Time Memory Synchronization

• ✅ Valkey pub/sub event broadcasting (Redis-compatible)
• ✅ Agent subscription management
• ✅ Conflict resolution
• ✅ State synchronization between agents

---

Production-Ready Enterprise Memory System

Enhanced Cognee has completed all planned development sprints, delivering a production-ready enterprise memory system with comprehensive features and 95%+ test coverage.

1: Test Suite & LLM Integration

• Comprehensive test suite with 4,661 tests (100% pass rate)
• Multi-LLM integration (multi-provider support)
• Token counting and rate limiting
• Test infrastructure (pytest, fixtures, mocks)
• Files: 23 files, 7,500+ lines

2: Simplified Installation

• Cross-platform installation scripts
• Interactive setup wizard
• Dependency verification
• Environment configuration
• Files: 5 files, 2,000+ lines

3: MCP IDE Integration

• Standard Memory MCP tools (7 tools)
• Auto-injection hooks
• Zero-configuration setup
• MCP IDE plugin integration
• Files: 8 files, 1,800+ lines

4: Progressive Disclosure

• 3-layer progressive search (exact, semantic, full)
• Token efficiency (10x improvement)
• Intelligent query routing
• Layer-specific result caching
• Files: 6 files, 1,500+ lines

5: Structured Memory Model

• Structured observations format
• Memory hierarchy (categories, tags)
• JSON schema validation
• Enhanced metadata support
• Files: 12 files, 3,200+ lines

6: Security Implementation

• RBAC (Role-Based Access Control)
• Audit logging
• Data encryption at rest
• Secure credential management
• Files: 10 files, 2,800+ lines

7: Web Dashboard

• Next.js 14 frontend
• Memory management UI
• Search and filter interfaces
• Real-time updates
• Files: 25 files, 8,500+ lines

8: Advanced Features

• Lite mode (SQLite-based)
• Backup and recovery (8 tools)
• Deduplication system (3 tools)
• Auto-summarization (3 tools)
• Files: 18 files, 5,400+ lines

9: Multi-Language & Polish

• 28 language support
• Cross-language search
• Comprehensive testing (4,661 tests, 100% pass rate)
• Performance optimization
• Files: 15 files, 4,200+ lines

10: Advanced AI Features

• Intelligent summarization (4 strategies, 3 LLMs)

• Advanced search (4 re-ranking strategies)

• Advanced search with re-ranking

• SDLC sub-agent coordination (21 agents)

• SDLC integration (21 sub-agents)

• Query expansion and semantic clustering

• Multi-LLM summarization (multi-provider support, including OpenAI, Anthropic, Ollama)

• Semantic memory clustering

• Files: 16 files, 5,200+ lines

11: Production Readiness & Deployment

• Production Docker configuration
• Security hardening checklist (100+ items)
• Monitoring setup (Prometheus, Grafana)
• Deployment documentation
• Files: 4 files, 1,200+ lines

12: Integration & Ecosystem

• Real-time WebSocket server (8 event types)
• Next.js dashboard integration
• React hooks for live updates
• Files: 4 files, 1,136+ lines

13: Quality & Maintenance

• CI/CD pipeline (7 automated stages)
• 95%+ test coverage achieved
• Security audit (0 critical vulnerabilities)
• Performance testing
• Files: 3 files, 1,468+ lines

Feature Matrix by Category

Core Memory Features

Feature	Status	Description
Multi-Database Architecture	✅	PostgreSQL, Qdrant, Neo4j, Valkey
Standard Memory MCP Tools	✅	add_memory, search_memories, get_memories, etc.
Memory Deduplication	✅	Semantic similarity detection
Memory Summarization	✅	LLM-based with 4 strategies
Memory Expiry & TTL	✅	Automatic archival and cleanup
Cross-Agent Sharing	✅	Access control and permissions
Real-Time Sync	✅	Valkey pub/sub synchronization
Encryption at Rest	✅	Fernet AES-128-CBC + HMAC-SHA256 per memory
Structured Observations	✅	EAV table (entity, attribute, value) per memory
Importance Scoring	✅	Heuristic: access0.4 + recency0.3 + confidence0.2 + source0.1
Heuristic Re-ranking	✅	Multi-signal: similarity0.5 + importance0.25 + recency0.15 + confidence0.10

Advanced AI Features

Feature	Status	Description
Intelligent Summarization	✅	Multi-provider LLM support, including OpenAI, Anthropic, Ollama support
Semantic Clustering	✅	Qdrant-based similarity clustering
Advanced Search	✅	Query expansion, re-ranking, highlighting
Multi-Language Support	✅	28 languages with cross-language search
LLM API Integration	✅	Multi-provider LLM support
Memory-Aware Conversations	✅	Context retrieval from knowledge graph

Development Features

Feature	Status	Description
Real-Time Dashboard	✅	WebSocket-based live updates
MCP Server	✅	Standard Memory MCP for AI IDEs
SDLC Coordination	✅	21 sub-agents with task orchestration
CI/CD Pipeline	✅	Automated testing and deployment
Security Audit	✅	Comprehensive vulnerability scanning
Code Coverage	✅	95%+ overall coverage
Python SDK Client	✅	enhanced_cognee_client (async httpx, 16 methods)
Slack/Discord Alerts	✅	Webhook notifications for memory events
Pre-commit Hooks	✅	ruff, bandit, category gate, ASCII gate

Operations Features

Feature	Status	Description
Backup & Recovery	✅	Automated backups for all databases
Monitoring	✅	Prometheus, Grafana, Loki, AlertManager
Security Hardening	✅	100+ checklist items
Deployment Guide	✅	Step-by-step production deployment
Performance Testing	✅	Locust load testing
Documentation	✅	Comprehensive guides and API docs

---

Comparison with Original Cognee

Feature	Original Cognee	Enhanced Cognee
Relational Database	SQLite	PostgreSQL + pgVector
Vector Database	LanceDB	Qdrant
Graph Database	Kuzu	Neo4j
Caching Layer	None	Valkey 8
Memory Categories	None	Dynamic JSON-based
MCP Tools	None	[OK] 122 tools
Multi-Agent Support	None	[OK] Real-time sync for 100+ agents
Memory Deduplication	None	[OK] 95%+ storage savings
Memory Summarization	None	[OK] 10x+ compression
Performance Analytics	None	[OK] Prometheus export
Cross-Agent Sharing	None	[OK] 4 access policies
TTL & Archival	None	[OK] Automated lifecycle
IDE Support	None	[OK] MCP-compatible IDEs
Test Coverage	Basic	[OK] 4,661 tests passing (100% pass rate)
MCP IDE Integration	No	[OK] Standard Memory MCP
Port Configuration	Default ports	Enhanced range (25000+)
Output Encoding	None	ASCII-only (Windows compatible)
Docker Deployment	Basic	Production-ready with health checks
API Compatibility	N/A	Full Cognee API compatibility

Performance Improvements

Based on testing with enterprise datasets:

• 400-700% improvement in query performance
• 10x better concurrent request handling
• Unlimited scalability with PostgreSQL and Qdrant
• Sub-millisecond cache hits with Valkey
• 95%+ storage efficiency with deduplication and summarization
• Sub-millisecond agent coordination with Valkey pub/sub

See "Comparison with Original Cognee" above for the side-by-side feature table, or docs/COMPARE_TO_ALTERNATIVES.md for broader market context.

---

Original Cognee Features Available via Enhanced Cognee MCP

[OK] 100% Feature Coverage - All original Cognee capabilities are accessible via 122 MCP tools

Core ECL Pipeline Features

Original Cognee Feature	Enhanced MCP Tool	Trigger Type	Status
add()	add_memory	Auto (A)	✅ Available
cognify()	cognify	Auto (A)	✅ Available
search()	search	Auto (A)	✅ Available
list_data() equivalent	list_data	Auto (A)	✅ Available
get_stats() equivalent	get_stats	Auto (A)	✅ Available

Knowledge Graph & Vector Stores

Original Feature	Enhanced MCP Implementation	Status
Neo4j Support	Neo4j (port 27687)	✅ Active
Vector Stores (LanceDB/Qdrant/PGVector)	Qdrant (port 26333) + PGVector (port 25432)	✅ Enhanced
Graph Databases (NetworkX/Neo4j)	Neo4j + internal NetworkX	✅ Active

Database Comparison

Aspect	Original Cognee	Enhanced Cognee MCP
Architecture	Single database setup	4-database stack (PostgreSQL, Qdrant, Neo4j, Valkey)
Performance	Baseline	400-700% faster
Ports	Default ports	Enhanced port range (25000+)

Enhanced Features NOT in Original Cognee

The following 50+ enterprise features are exclusive to Enhanced Cognee MCP:

• ✅ Backup & Recovery (5 tools) - create_backup, restore_backup, list_backups, verify_backup, rollback_restore
• ✅ Performance Monitoring (3 tools) - get_performance_metrics, get_slow_queries, get_prometheus_metrics
• ✅ Multi-Language Support (6 tools) - detect_language, get_supported_languages, search_by_language, get_language_distribution, cross_language_search, get_search_facets
• ✅ Real-Time Sync (3 tools) - publish_memory_event, get_sync_status, sync_agent_state
• ✅ Cross-Agent Collaboration (4 tools) - set_memory_sharing, check_memory_access, get_shared_memories, create_shared_space
• ✅ Advanced AI Operations (6 tools) - intelligent_summarize, auto_summarize_old_memories, cluster_memories, advanced_search, expand_search_query, get_search_analytics
• ✅ Memory Lifecycle Management (4 tools) - expire_memories, get_memory_age_stats, set_memory_ttl, archive_category
• ✅ Scheduling & Automation (3 tools) - schedule_task, schedule_deduplication, schedule_summarization

Detailed Comparison Document

For complete feature-by-feature analysis, see: COGNEE_VS_ENHANCED_MCP_COMPARISON.md

This document provides:

• Line-by-line feature mapping
• Tool availability matrix
• API compatibility comparison
• Database architecture comparison
• 50+ exclusive Enhanced features

MCP Tool Classifications

122 MCP Tools by Trigger Type:

• Manual (M): 21 tools - Only irreversible/destructive/compliance-sensitive operations requiring explicit user decision
• Auto (A): 45 tools - Automatically triggered by MCP-compatible IDEs based on conversation context
• System (S): 56 tools - Auto-triggered by Enhanced Cognee system (scheduler, hooks, events)
• Phases 7-14 complete: 122 tools total (including 3 undo operation tools). See COGNEE_VS_ENHANCED_MCP_COMPARISON.md for the full 122-tool reference table with individual trigger assignments.

For MCP IDE Users

All 122 MCP tools are accessible via Standard Memory MCP protocol:

1. Standard Memory MCP tools (7): add_memory, search_memories, get_memories, get_memory, update_memory, delete_memory, list_agents
2. Enhanced Cognee tools (115): Advanced features for enterprise deployments (Phase 2 session memory, Phase 3 external loaders, Phase 7-14 progressive search, session management, audit, GDPR, encryption, observations, notifications, importance scoring, re-ranking, undo operations)

For Claude Code and Other AI IDEs

Any MCP-capable AI IDE can access all 122 tools:

• Claude Code (Anthropic - primary reference implementation)
• Cursor IDE
• Windsurf (Codeium)
• Antigravity
• Continue.dev
• VS Code (with Continue.dev or Kilo Code extensions)
• GitHub Copilot

No LLM API keys required - All configuration is server-side.

---

Screenshots and Demos

TODO: Add terminal GIFs / screenshots showing:

• Claude Code calling add_memory and search_memories via MCP
• The Grafana dashboard with live metrics
• A typical undo_last workflow
• Multi-agent shared memory in action

Contributions welcome -- record with asciinema or peek and submit a PR.

---

Architecture

System Architecture

flowchart LR
    subgraph Clients["Client Layer"]
        AIC[MCP-Compatible<br/>IDEs]
        API[REST API]
        CLI[CLI Tool]
    end

    subgraph MCP["MCP Server Layer - 122 Tools"]
        MCP1[Enhanced Cognee Core<br/>5 Tools]
        MCP2[Standard Memory MCP<br/>7 Tools]
        MCP3[Memory Lifecycle<br/>TTL / Tiers / Consolidation<br/>9 Tools]
        MCP4[Deduplication<br/>6 Tools]
        MCP5[Summarization<br/>7 Tools]
        MCP6[Analytics & LLM Cost<br/>5 Tools]
        MCP7[Cross-Agent Sharing<br/>4 Tools]
        MCP8[Real-Time Sync<br/>3 Tools]
        MCP9[Backup & Recovery<br/>5 Tools]
        MCP10[Scheduling<br/>3 Tools]
        MCP11[Multi-Language<br/>6 Tools]
        MCP12[Advanced AI & Search<br/>9 Tools]
        MCP13[Session Memory<br/>9 Tools]
        MCP14[Knowledge Graph & Loaders<br/>9 Tools]
        MCP15[Audit & Provenance<br/>7 Tools]
        MCP16[GDPR Compliance<br/>6 Tools]
        MCP17[Plugins / Webhooks / Notifications<br/>9 Tools]
        MCP18[Encryption / EAV / Importance<br/>10 Tools]
        MCP19[Undo / Redo<br/>3 Tools]
    end

    subgraph Memory["Memory Management Layer"]
        MM[Memory Manager<br/>TTL, Expiry]
        MD[Memory Deduplicator<br/>95%+ Savings]
        MS[Memory Summarizer<br/>10x Compression]
        PA[Performance Analytics<br/>Prometheus]
        CAS[Cross-Agent Sharing<br/>4 Policies]
        RTS[Real-Time Sync<br/>Pub/Sub]
        BR[Backup & Recovery<br/>Automated]
        SC[Scheduling<br/>Automated Tasks]
        ML[Multi-Language<br/>28 Languages]
        AI[Advanced AI<br/>LLM Integration]
        AS[Advanced Search<br/>Re-ranking]
    end

    subgraph DB["Database Layer — Pluggable (4 tiers, 30 providers)"]
        direction TB
        subgraph Defaults["Default profile (100% Apache-2.0 + MIT)"]
            PG[(PostgreSQL + pgvector<br/>Port 25432)]
            QD[(Qdrant<br/>Port 26333)]
            N4[(ArcadeDB<br/>Port 27687, Apache-2.0)]
            RD[(Valkey 8<br/>Port 26379, Apache-2.0)]
        end
        subgraph Alternates["Drop-in alternates via ENHANCED_*_PROVIDER"]
            ALT_G[Graph: neo4j / apache_age /<br/>memgraph / kuzu / arangodb /<br/>nebulagraph / ladybug / networkx_inmemory]
            ALT_V[Vector: pgvector / lancedb /<br/>chroma / weaviate / milvus]
            ALT_C[Cache: redis / redis_compat /<br/>in_memory / memcached]
            ALT_R[Relational: sqlite]
        end
    end

    subgraph Obs["Observability (optional, Phase 4)"]
        direction LR
        SN[SigNoz<br/>OTel APM + traces]
        SU[Apache Superset<br/>BI dashboards]
        PR[Prometheus<br/>Metrics scraping]
    end

    AIC --> MCP
    API --> MCP
    CLI --> MCP

    MCP1 --> MM
    MCP2 --> MM
    MCP3 --> MM
    MCP4 --> MD
    MCP5 --> MS
    MCP6 --> PA
    MCP7 --> CAS
    MCP8 --> RTS
    MCP9 --> BR
    MCP10 --> SC
    MCP11 --> ML
    MCP12 --> AI
    MCP12 --> AS
    MCP13 --> MM
    MCP14 --> MM
    MCP14 --> N4
    MCP15 --> MM
    MCP16 --> MM
    MCP17 --> MM
    MCP18 --> MM
    MCP19 --> MM

    MM --> PG
    MM --> RD
    MD --> PG
    MD --> QD
    MS --> PG
    PA --> PG
    PA --> RD
    CAS --> PG
    RTS --> RD
    BR --> PG
    SC --> PG
    ML --> QD
    AI --> PG
    AS --> QD

    PG <--> QD
    PG <--> N4
    QD <--> N4

Enhanced Stack Architecture

Enhanced Cognee Memory Stack -- default profile (production)
├── PostgreSQL + pgvector (Port 25432, PostgreSQL Licence + Apache-2.0)
│   ├── Relational data storage
│   ├── Vector similarity search (via pgvector extension)
│   ├── Memory lifecycle management
│   └── ACID transactions
├── Qdrant (Port 26333, Apache-2.0)
│   ├── High-performance vector search
│   ├── HNSW indexing
│   ├── Duplicate detection
│   └── Filtered searches
├── ArcadeDB (Port 27687, Apache-2.0; default since 2026-05-19)
│   ├── Knowledge graph (openCypher, Bolt-compatible wire)
│   ├── Relationship mapping
│   ├── Multi-model: also supports document / vector / time-series
│   └── Drop-in for existing NEO4J_URI=bolt://localhost:27687 setups
├── Valkey (Port 26379, Apache-2.0; default since 2026-05-18)
│   ├── Caching layer
│   ├── Real-time pub/sub (agent coordination)
│   ├── Session management
│   └── Performance metrics
└── Enhanced Cognee MCP Server
    ├── 122 MCP tools
    ├── Multi-IDE support (MCP-compatible IDEs)
    ├── ASCII-only output (Windows console safe)
    └── Pluggable storage via ENHANCED_*_PROVIDER env vars

Alternate provider permutations (see `docs/PROFILES.md`):
  apache_only -- postgres+pgvector + apache_age + valkey       (no JVM, no JS runtime)
  lean        -- postgres+pgvector + apache_age + in_memory    (laptop / small VPS)
  embedded    -- sqlite + lancedb + ladybug + in_memory        (offline / single-process)
  neo4j_stack -- postgres + qdrant + neo4j + redis             (legacy parity)

Pluggable Database Backends (30 providers, 4 tiers)

Shipped 2026-05-19..2026-05-20 across PRs #19-#31. The default stack is ArcadeDB + Qdrant + Valkey + PostgreSQL (all Apache-2.0 or PostgreSQL Licence), but every tier accepts a drop-in alternate via the ENHANCED_*_PROVIDER env var. The factory at src/db_factory.py dispatches to the right adapter; call sites use the duck-typed neo4j.Driver / QdrantClient / redis.Redis / psycopg2-style surfaces unchanged.

Tier	Default	Drop-in alternates
Graph	arcadedb	neo4j, apache_age, memgraph, kuzu, arangodb, nebulagraph, ladybug, networkx_inmemory (9 total)
Vector	qdrant	pgvector, lancedb, chroma, weaviate, milvus (6 total)
Cache	valkey	redis, redis_compat, in_memory, memcached (5 total)
Relational	postgres	sqlite, duckdb, mysql/mariadb, mssql/sqlserver, oracle, db2, snowflake, databricks, cockroachdb (via postgres wire) (10 total)

Pre-baked profiles (see docs/PROFILES.md for the full matrix and the per-adapter caveat tables):

• production — ArcadeDB + Qdrant + Valkey + PostgreSQL (default; 4 containers)
• apache_only — Apache AGE + Qdrant + Valkey + PostgreSQL (no JVM)
• lean — Apache AGE + pgvector + in_memory + PostgreSQL (1 container)
• embedded — ladybug + LanceDB + in_memory + SQLite (no containers; offline / single-process)
• neo4j_stack — Neo4j + Qdrant + Redis + PostgreSQL (legacy parity)

Why pluggable matters:

• Licensing flexibility. The default stack is 100% MIT/Apache-2.0. Customers with stricter procurement (no AGPL, no SSPL, no BSL) can switch providers without code changes.
• Operational fit. Laptops want embedded; small VPS want lean; multi-node clusters want production. Same MCP tool surface, same CRUD semantics, different storage engines.
• Vendor exit. If a managed service goes through licence churn (the Redis BSL situation), flipping ENHANCED_CACHE_PROVIDER is a one-line config change, not a code migration.

Vector filter translator. All 5 vector adapters route qdrant-style Filter(must=[FieldCondition(...)]) through src/db_adapters/_vector_filter.py which emits the native dialect (Postgres JSONB / Chroma where / Weaviate Filter.by_property / Milvus expr / LanceDB SQL). Single- must FieldConditions are supported across all backends; compound filters raise a clear NotImplementedError with a pointer.

Apache AGE native graph elements. MATCH (n) RETURN n against Apache AGE now returns _AGENode / _AGERelationship objects shaped exactly like neo4j.graph.Node / Relationship — same .labels / .type / .start_node / dict(node.items()) API.

See docs/PLUGGABLE_DB_BACKENDS.md for the architectural overview and docs/PROFILES.md for the per-adapter capability matrix.

Enhanced Modules

src/
├── memory_management.py          # TTL, expiry, archival
├── memory_deduplication.py       # Duplicate detection
├── memory_summarization.py       # Auto summarization
├── performance_analytics.py      # Metrics collection
├── cross_agent_sharing.py        # Access control
├── realtime_sync.py              # Valkey pub/sub sync (Redis protocol)
├── multi_language_search.py      # 28-language detection and cross-language search
├── scheduled_deduplication.py    # Scheduled deduplication runner
├── scheduled_summarization.py    # Scheduled summarization runner
├── maintenance_scheduler.py      # Task scheduler and config
├── mcp_memory_tools.py           # Shared tool helpers
├── backup_manager.py             # Backup and recovery
├── plugin_registry.py            # Plugin loader system
├── webhook_manager.py            # Webhook delivery
├── encryption_manager.py         # Fernet AES-128-CBC encryption at rest (Phase 14)
├── memory_observation.py         # EAV structured observations (Phase 14)
├── notification_manager.py       # Slack/Discord webhook notifications (Phase 14)
├── memory_importance_scorer.py   # Heuristic importance scoring (Phase 14)
└── memory_reranker.py            # Multi-signal re-ranking (Phase 14)

---

Upstream Sync Monitoring

Enhanced Cognee includes automation to stay current with upstream topoteretes/cognee releases.

Automated Weekly Check

A GitHub Actions workflow (.github/workflows/upstream_sync.yml) runs every Monday at 08:00 UTC:

• Fetches the latest upstream release tag via GitHub API
• Compares against .upstream-sync/last_seen_release.txt
• If new release detected: builds diff report, opens tracking GitHub issue, sends email alert

Manual Check

# Check if upstream has new releases (exit 1 = new release available)
python scripts/upstream_diff.py --check-only

# Generate full diff report
python scripts/upstream_diff.py --token $GITHUB_TOKEN

# Generate stub MCP tools and porting checklist
python scripts/auto_port.py

Sync Files

File	Purpose
.upstream-sync/last_seen_release.txt	Current synced baseline tag
.upstream-sync/sync-metadata.json	Full sync state record
scripts/upstream_diff.py	Diff report generator
scripts/auto_port.py	Stub and TODO generator
docs/UPSTREAM_SYNC_RUNBOOK.md	Full porting operator guide

---

System Workflow

Memory Lifecycle

stateDiagram-v2
    [*] --> DataIngestion: User adds data
    DataIngestion --> Chunking: Extract
    Chunking --> EntityExtraction: Cognify
    EntityExtraction --> GraphConstruction: Build knowledge graph
    GraphConstruction --> Vectorization: Create embeddings

    Vectorization --> StorageDecision: Store

    StorageDecision --> PostgreSQL: Relational data
    StorageDecision --> Qdrant: Vector embeddings
    StorageDecision --> ArcadeDB: Graph relationships (default)
    StorageDecision --> Valkey: Cache layer

    PostgreSQL --> DeduplicationCheck: Query
    Qdrant --> DeduplicationCheck: Search
    ArcadeDB --> DeduplicationCheck: Traverse

    DeduplicationCheck --> IsDuplicate

    IsDuplicate --> Yes: Merge memories
    IsDuplicate --> No: Store as new

    Yes --> [*]
    No --> [*]

    PostgreSQL --> AgeCheck: Time-based
    AgeCheck --> OldMemory: TTL expired?
    OldMemory --> Yes: Archive or delete
    OldMemory --> No: Keep
    Yes --> [*]
    No --> [*]

Search Workflow

All 15 SearchType values are supported by the recall and search MCP tools.

flowchart LR
    A[User Query] --> R{Search Router\n15 SearchTypes}

    subgraph GraphSearch["Graph Search - 5 types"]
        G1[GRAPH_COMPLETION\ndefault recommended]
        G2[GRAPH_COMPLETION_COT\nchain-of-thought]
        G3[GRAPH_COMPLETION_DECOMPOSITION\nsub-questions]
        G4[GRAPH_COMPLETION_CONTEXT_EXTENSION\nedge extension]
        G5[GRAPH_SUMMARY_COMPLETION\ngraph summaries]
    end

    subgraph VectorChunk["Vector and Chunk Search - 4 types"]
        V1[RAG_COMPLETION]
        V2[CHUNKS]
        V3[CHUNKS_LEXICAL\nBM25 keyword]
        V4[TRIPLET_COMPLETION\nknowledge triplets]
    end

    subgraph SpecialSearch["Specialized Search - 4 types"]
        S1[SUMMARIES\ndoc summaries]
        S2[NATURAL_LANGUAGE\nNL query parser]
        S3[TEMPORAL\ntime-aware]
        S4[CODING_RULES\ncode patterns]
    end

    subgraph DirectQuery["Direct and Auto - 2 types"]
        D1[CYPHER\ndirect Cypher query\nArcadeDB/Neo4j/AGE-compatible]
        D2[FEELING_LUCKY\nauto-select best]
    end

    R --> GraphSearch
    R --> VectorChunk
    R --> SpecialSearch
    R --> DirectQuery

    GraphSearch --> K[Results]
    VectorChunk --> K
    SpecialSearch --> K
    DirectQuery --> K

    K --> L{Relevance Score}
    L -->|High| M[Return to User]
    L -->|Low| N[Refine Query]
    N --> R

---

Installation

Prerequisites

• Python: 3.10 or higher
• Docker: Latest version (for database deployment)
• Git: For cloning the repository
• 4GB RAM: Minimum for database stack
• 10GB Disk: For Docker images and data

Option 1: Quick Install (Recommended)

# Clone repository
git clone https://github.com/vincentspereira/Enhanced-Cognee.git
cd Enhanced-Cognee

# Start Enhanced databases (one command)
docker compose -f docker/docker-compose-enhanced-cognee.yml up -d

# Verify all services running
docker ps | grep enhanced

Expected output:

postgres-enhanced-cognee   Up   0.0.0.0:25432->5432/tcp
qdrant-enhanced-cognee     Up   0.0.0.0:26333->6333/tcp
arcadedb-enhanced-cognee   Up   0.0.0.0:22480->2480/tcp, 0.0.0.0:27687->7687/tcp
cognee-mcp-valkey          Up   0.0.0.0:26379->6379/tcp

(Set ENHANCED_GRAPH_PROVIDER=neo4j to opt back into Neo4j; see docs/ARCADEDB_MIGRATION.md.)

Option 2: Clone and Install (Manual)

# Clone the repository
git clone https://github.com/vincentspereira/Enhanced-Cognee.git
cd Enhanced-Cognee

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

Option 3: Install Python SDK from PyPI

The Python SDK client is available now on PyPI:

pip install enhanced-cognee-client

Full server installation via PyPI is planned for a future release.

---

Quick Start

1. Configure Environment

# Copy environment template
cp .env.example .env

# Edit with your settings
# Minimum required (default `production` profile):
# - POSTGRES_HOST=localhost
# - POSTGRES_PORT=25432
# - QDRANT_HOST=localhost
# - QDRANT_PORT=26333
# - NEO4J_URI=bolt://localhost:27687     (ArcadeDB's bolt port; same name kept for compat)
# - REDIS_HOST=localhost                  (Valkey -- wire-compatible with redis-py)
# - REDIS_PORT=26379

# Optional: switch providers via env vars
# (see `docs/PROFILES.md` for the full matrix)
# - ENHANCED_GRAPH_PROVIDER=arcadedb       # arcadedb / neo4j / apache_age / memgraph
#                                          # / kuzu / arangodb / nebulagraph / ladybug
#                                          # / networkx_inmemory
# - ENHANCED_VECTOR_PROVIDER=qdrant        # qdrant / pgvector / lancedb / chroma
#                                          # / weaviate / milvus
# - ENHANCED_CACHE_PROVIDER=valkey         # valkey / redis / redis_compat / in_memory
#                                          # / memcached
# - ENHANCED_RELATIONAL_PROVIDER=postgres  # postgres / sqlite

2. Start MCP Server

python bin/enhanced_cognee_mcp_server.py

You should see:

==================================================================
         Enhanced Cognee MCP Server - Enhanced Stack
    PostgreSQL+pgVector | Qdrant | ArcadeDB | Valkey
==================================================================

OK Initializing Enhanced Cognee stack...
OK PostgreSQL connected
OK Qdrant connected (5 collections)
OK ArcadeDB connected
OK Valkey connected
OK Memory Manager initialized
OK Memory Deduplicator initialized
OK Memory Summarizer initialized
OK Performance Analytics initialized
OK Cross-Agent Sharing initialized
OK Real-Time Sync initialized

OK Enhanced Cognee MCP Server starting...
  Available tools: 122 tools listed below...

3. Configure Your AI IDE

MCP Configuration (example for any MCP-compatible IDE):

// ~/.claude.json
{
  "mcpServers": {
    "cognee": {
      "command": "python",
      "args": [
        "/path/to/enhanced-cognee/bin/enhanced_cognee_mcp_server.py"
      ],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "25432",
        "QDRANT_HOST": "localhost",
        "QDRANT_PORT": "26333"
      }
    }
  }
}

More IDEs: See MCP IDE Setup Guide

4. Use Enhanced Cognee

In your AI IDE with MCP connected:

You: Add a memory that I prefer TypeScript for frontend development

AI: [Calls add_memory tool]
OK Memory added (ID: abc-123)

You: What do you know about my TypeScript preferences?

AI: [Calls search_memories tool]
Found 3 memories about TypeScript:
- You prefer TypeScript for frontend development
- You use strict mode in tsconfig.json
- You favor interfaces over types for public APIs

---

Multi-IDE Support

Enhanced Cognee works with any MCP-compatible IDE:

IDE	Support Level	Setup Guide
Claude Code	[OK] Full	MCP IDE Setup Guide
Cursor	[OK] Full	MCP IDE Setup Guide
Windsurf	[OK] Full	MCP IDE Setup Guide
Antigravity	[OK] Full	MCP IDE Setup Guide
Continue.dev	[OK] Full	MCP IDE Setup Guide
VS Code (+Continue)	[OK] Full	MCP IDE Setup Guide
Kilo Code	[OK] Full	MCP IDE Setup Guide
GitHub Copilot	[OK] Full	MCP IDE Setup Guide
Other MCP IDEs	[OK] Full	MCP IDE Setup Guide

Complete Setup Guide: MCP IDE Setup Guide

---

Quick Examples

A taste of the most-used MCP tools. These work from any MCP-compatible IDE (Claude Code, Cursor, Copilot).

From Claude Code (natural language)

> Remember that I prefer async/await over callbacks.
> Search my memories for "async patterns".
> Undo my last memory operation -- I shared something I shouldn't have.
> Show me a summary of my last 10 conversations with the trading bot.

Claude reads the intent and calls the right MCP tool automatically: remember(), search_memories(), undo_last(), get_session_history().

From Python (via the SDK)

from enhanced_cognee_client import EnhancedCogneeClient

async with EnhancedCogneeClient(host="localhost", port=8080) as client:
    # Store a memory
    result = await client.add_memory(
        content="Production deployed Enhanced Cognee on Hetzner CX22",
        user_id="default",
        agent_id="ops-bot",
    )

    # Search by semantic + text
    hits = await client.search_memories(
        query="production deployment",
        limit=5,
    )

    # Roll back the last write (24-hour window)
    await client.undo_last(agent_id="ops-bot")

    # Health check
    status = await client.health()

Full tool reference: see MCP Tools Reference below.

---

MCP Tools Reference

Enhanced Cognee provides 122 MCP tools with comprehensive automation across three trigger types:

Standard Memory Tools (7)

Tool	Purpose	Trigger Type	Automation Chain
add_memory	Add memory with metadata	(A) Auto	Auto-checks duplicates → publishes events → logs performance
search_memories	Semantic + text search	(A) Auto	Performs search → logs performance → detects slow queries
get_memories	List all memories	(A) Auto	Retrieves memories → logs performance metrics
get_memory	Get specific memory by ID	(A) Auto	Retrieves memory → logs performance
update_memory	Update existing memory	(A) Auto	Updates memory → publishes events → logs performance
delete_memory	Delete memory	(M) Manual	Deletes memory → publishes events → logs performance
list_agents	List all agents	(A) Auto	Lists agents → logs performance

Enhanced Cognee Tools (5)

Tool	Purpose	Trigger Type	Automation Chain
cognify	Transform data to knowledge graph	(A) Auto	Processes data → logs performance
search	Search knowledge graph	(A) Auto	Searches graph → logs performance
list_data	List all documents	(A) Auto	Lists documents → logs performance
get_stats	Get system statistics	(A) Auto	Calls all stats functions → logs performance
health	Health check all databases	(A) Auto	Checks connections → logs performance (if unhealthy)

Memory Management Tools (4)

Tool	Purpose	Trigger Type	Automation Chain
expire_memories	Expire old memories	(S) System	Expires memories → gets age stats → publishes events → gets summary stats → logs performance
get_memory_age_stats	Memory age distribution	(S) System	Gets age stats → logs performance
set_memory_ttl	Set time-to-live	(A) Auto	Sets TTL → gets age stats → logs performance
archive_category	Archive by category	(S) System	Archives category → gets age stats → publishes events → gets summary stats → logs performance

Memory Deduplication Tools (5)

Tool	Purpose	Trigger Type	Automation Chain
check_duplicate	Check if duplicate	(S) System	Checks duplicate → logs performance
auto_deduplicate	Auto-find duplicates	(S) System	Finds duplicates → gets stats → publishes events → logs performance
get_deduplication_stats	Deduplication stats	(S) System	Gets stats → logs performance
deduplicate	Manual deduplication	(S) System	Runs deduplication → gets stats → logs performance
deduplication_report	Get deduplication report	(S) System	Gets report → logs performance

Memory Summarization Tools (5)

Tool	Purpose	Trigger Type	Automation Chain
summarize_old_memories	Summarize old memories	(S) System	Summarizes memories → gets age stats → publishes events → gets summary stats → logs performance
summarize_category	Summarize specific category	(S) System	Summarizes category → gets summary stats → publishes events → logs performance
get_summary_stats	Summarization stats	(S) System	Gets stats → logs performance
get_summarization_stats	Get summarization stats	(S) System	Gets stats → logs performance
summary_stats	Get summary statistics	(S) System	Gets stats → logs performance

Performance Analytics Tools (3)

Tool	Purpose	Trigger Type	Automation Chain
get_performance_metrics	Comprehensive performance data	(S) System	Gets metrics → logs performance
get_slow_queries	Queries above threshold	(S) System	Gets slow queries → logs performance
get_prometheus_metrics	Prometheus export	(S) System	Gets prometheus metrics → logs performance

LLM Cost Tracking Tools - Plan 14.8 (2)

Tool	Purpose	Trigger Type	Automation Chain
get_llm_cost_report	Token usage and cost per agent/tool/model	(S) System	Fetches usage from DB → formats ASCII report
set_cost_budget	Set monthly LLM spend limit for agent	(M) Manual	Persists budget → in-memory cache → WARN on exceed

Cross-Agent Sharing Tools (4)

Tool	Purpose	Trigger Type	Automation Chain
set_memory_sharing	Set sharing policy for memory	(A) Auto	Sets policy → publishes events → syncs with allowed agents → logs performance
check_memory_access	Check if agent can access memory	(S) System	Checks access → logs performance
get_shared_memories	Get shared memories for agent	(A) Auto	Gets shared memories → logs performance
create_shared_space	Create shared memory space	(A) Auto	Creates space → publishes events → logs performance

Real-Time Sync Tools (3)

Tool	Purpose	Trigger Type	Automation Chain
publish_memory_event	Publish memory update events	(S) System	Publishes events → logs performance
get_sync_status	Get synchronization status	(S) System	Gets status → logs performance
sync_agent_state	Sync memories between agents	(A) Auto	Syncs state → logs performance

Backup & Recovery Tools (5)

Tool	Purpose	Trigger Type	Automation Chain
create_backup	Create system backup	(A) Auto	Creates backup → verifies backup → gets performance metrics → publishes events → logs performance
restore_backup	Restore from backup	(M) Manual	Restores backup → health check (on failure: rollback) → publishes events → logs performance
list_backups	List all backups	(A) Auto	Lists backups → logs performance
verify_backup	Verify backup integrity	(S) System	Verifies backup → logs performance
rollback_restore	Rollback failed restore	(S) System	Rollbacks restore → health check → logs performance

Scheduling Tools (3)

Tool	Purpose	Trigger Type	Automation Chain
schedule_task	Schedule maintenance task	(S) System	Schedules task → logs performance
list_tasks	List scheduled tasks	(A) Auto	Lists tasks → logs performance
cancel_task	Cancel scheduled task	(M) Manual	Cancels task → logs performance

Scheduling Automation Tools (2)

Tool	Purpose	Trigger Type	Automation Chain
schedule_deduplication	Schedule auto-deduplication	(S) System	Schedules deduplication → logs performance
schedule_summarization	Schedule auto-summarization	(S) System	Schedules summarization → logs performance

Note: deduplication_report is listed under "Memory Deduplication Tools" above.

Multi-Language Tools (6)

Tool	Purpose	Trigger Type	Automation Chain
detect_language	Detect text language	(S) System	Detects language → logs performance
get_supported_languages	List supported languages	(S) System	Lists languages → logs performance
search_by_language	Search by language filter	(S) System	Searches by language → logs performance
get_language_distribution	Get language statistics	(S) System	Gets distribution → logs performance
cross_language_search	Cross-language search	(S) System	Cross-language search → logs performance
get_search_facets	Get search facets	(S) System	Gets facets → logs performance

Advanced AI & Search Tools (6)

Tool	Purpose	Trigger Type	Automation Chain
intelligent_summarize	LLM-powered summarization	(S) System	Summarizes with LLM → logs performance
auto_summarize_old_memories	Auto batch summarize	(S) System	Batch summarizes → logs performance
cluster_memories	Cluster memories semantically	(S) System	Clusters memories → logs performance
advanced_search	Advanced search with re-ranking	(S) System	Searches → re-ranks → logs performance
expand_search_query	Expand search query with LLM	(S) System	Expands query → logs performance
get_search_analytics	Get search analytics	(S) System	Gets analytics → logs performance

Progressive Search Tools (3)

Two-phase search pattern: run a fast shallow search, then drill into one result for detail or find related memories.

Tool	Purpose	Trigger Type	Automation Chain
search_quick	Fast shallow memory search (no embedding lookup)	(S) System	Runs text-match search -> returns top N results -> logs perf
get_memory_detail	Full detail (content, metadata, history) for one memory	(S) System	Fetches single memory with full metadata -> logs perf
get_related	Memories related to a given memory ID	(S) System	Queries cosine similarity neighbours -> returns ranked list

Session-Aware Memory Tools (6)

These tools wrap the cognee v1.0.9 cognee.api.v1.* session memory API.

Tool	Purpose	Trigger Type	Automation Chain
remember	Session-aware knowledge ingestion	(A) Auto	Stores data via v1.0.9 pipeline -> logs performance
recall	15-strategy knowledge graph search	(A) Auto	Searches KG with chosen strategy -> logs performance
forget_memory	Delete graph data by id/dataset	(M) Manual	Deletes from graph -> publishes events -> logs performance
improve	4-stage feedback improvement pipeline	(M) Manual	Runs improvement stages -> logs performance
save_interaction	Record user/assistant exchange	(A) Auto	Adds interaction -> cognifies -> logs performance
cognify_status	Check background task status	(S) System	Reads internal task registry -> logs performance

External Loaders and Enrichment Tools (6)

These tools expose the cognee v1.0.9 ingestion and enrichment tasks via MCP.

Tool	Purpose	Trigger Type	Automation Chain
ingest_url	Scrape URLs into knowledge graph	(A) Auto	Scrapes URL(s) via web_scraper_task -> logs performance
ingest_db	Ingest relational DB via dlt	(A) Auto	Ingests DB tables via dlt pipeline -> logs performance
translate_text	Translate text (LLM/Google/Azure)	(S) System	Translates via provider -> logs performance
regex_extract_entities	Named entity extraction via regex	(S) System	Extracts entities via RegexEntityExtractor
extract_graph_v2	Cascade v2 knowledge graph extraction	(S) System	Runs cascade extract (n rounds) -> returns graph
list_loaders	List available file format loaders	(A) Auto	Checks supported_loaders registry -> logs performance

Session Management Tools (4)

Track multi-turn conversation sessions. Session context is stored in PostgreSQL and linked to memories.

Tool	Purpose	Trigger Type	Automation Chain
start_session	Open a new named session for a user/agent pair	(A) Auto	Creates session row -> returns session_id -> logs perf
end_session	Close active session and flush session context	(A) Auto	Marks session closed -> writes summary -> publishes event
get_session_context	Retrieve the current session's accumulated context	(A) Auto	Queries session table -> returns JSON context -> logs perf
get_session_history	List all past sessions for a user/agent	(A) Auto	Queries session history -> returns sorted list -> logs perf

Audit and Provenance Tools (7)

Full audit trail and version history for every memory. Stored in shared_memory.audit_log and shared_memory.memory_history.

Tool	Purpose	Trigger Type	Automation Chain
query_audit_log	Query the full audit log with filters	(S) System	Queries audit_log table -> returns JSON events -> logs perf
get_memory_history	Full version history of a single memory	(S) System	Queries memory_history -> returns sorted versions -> logs perf
revert_memory	Revert a memory to a previous version	(M) Manual	Fetches version -> writes revert -> appends audit log
get_memory_provenance	Source and chain-of-custody for a memory	(S) System	Traces provenance chain -> returns JSON -> logs perf
verify_memory	Check memory integrity against stored hash	(S) System	Computes hash -> compares stored -> returns PASS/FAIL
set_memory_confidence	Set confidence score (0.0-1.0) for a memory	(S) System	Updates confidence column -> logs perf
get_confidence_report	Confidence distribution across all memories	(S) System	Aggregates confidence scores -> returns JSON report

Consolidation and Tier Promotion Tools (7)

Identify redundant memories, merge them into summaries, and promote high-value memories to faster storage tiers.

Tool	Purpose	Trigger Type	Automation Chain
find_consolidation_candidates	Find groups of memories suitable for merging	(S) System	Runs similarity clustering -> returns candidate groups
consolidate_memories	Merge a group of memories into one summary	(S) System	Merges group -> writes summary memory -> deletes originals
get_consolidation_report	Report on consolidation runs and space saved	(S) System	Queries consolidation history -> returns JSON report
promote_memory_tier	Promote a memory to a higher-priority storage tier	(S) System	Moves memory to hot tier -> updates tier column -> logs perf
get_tier_stats	Distribution of memories across storage tiers	(S) System	Aggregates tier column -> returns JSON breakdown
compact_knowledge_graph	Remove orphan nodes and stale edges from graph	(S) System	Runs Neo4j compaction -> returns deleted node/edge counts
get_graph_stats	Node and edge counts for the knowledge graph	(S) System	Queries Neo4j stats -> returns JSON -> logs perf

GDPR Compliance Tools (6)

Data subject rights and consent management. All GDPR operations are logged to the audit trail.

Tool	Purpose	Trigger Type	Automation Chain
gdpr_delete_user_data	Right to erasure: delete all data for a user	(M) Manual	Deletes memories/sessions/audit for user -> writes GDPR log
gdpr_export_user_data	Right to portability: export all data for a user	(A) Auto	Queries all user data -> returns JSON export package
gdpr_record_consent	Record a consent decision (grant or revoke)	(M) Manual	Inserts consent record -> timestamps -> writes audit log
gdpr_check_consent	Check whether a user has active consent	(S) System	Queries consent table -> returns True/False + expiry
gdpr_list_consents	List all consent records for a user	(S) System	Queries consent table -> returns sorted list
gdpr_verify_tenant_isolation	Verify no cross-tenant data leakage	(S) System	Runs isolation queries -> returns PASS/FAIL + violation list

Plugin Loaders Tools (2)

Dynamic document loader plugins. Plugins are discovered at startup from the loaders/ directory.

Tool	Purpose	Trigger Type	Automation Chain
list_loader_plugins	List all installed document loader plugins	(A) Auto	Scans plugin registry -> returns JSON list with capabilities
load_document_with_plugin	Load and ingest a document using a named plugin	(A) Auto	Loads file via plugin -> cognifies content -> logs perf

Webhooks Tools (4)

Register HTTP webhook endpoints to receive real-time memory event notifications.

Tool	Purpose	Trigger Type	Automation Chain
register_webhook	Register a new HTTP webhook for memory events	(A) Auto	Stores webhook config -> validates URL -> returns webhook_id
list_webhooks	List all registered webhooks	(A) Auto	Queries webhook store -> returns JSON list
test_webhook	Send a test payload to a registered webhook	(A) Auto	Builds test payload -> POSTs to URL -> returns status code
disable_webhook	Disable a webhook (stop event delivery)	(M) Manual	Marks webhook disabled -> logs change -> returns confirmation

Encryption at Rest Tools - Phase 14 (3)

Tool	Purpose	Trigger Type	Automation Chain
encrypt_memory	Encrypt a memory's content with Fernet key	(S) System	Reads memory -> encrypts -> writes back with enc: prefix
get_encryption_stats	Report encrypted vs plaintext memory counts	(S) System	Queries DB -> returns JSON stats
rotate_encryption_key	Re-encrypt all memories with a new master key	(M) Manual	Decrypts old -> re-encrypts new -> updates rows

Implementation details: Fernet AES-128-CBC + HMAC-SHA256. Idempotent: content already starting with enc: is skipped. Key rotation is row-by-row to avoid table locks.

Structured Observations Tools - Phase 14 (4)

Tool	Purpose	Trigger Type	Automation Chain
add_observation	Add EAV observation to a memory	(A) Auto	Inserts into shared_memory.observations -> returns obs_id
get_observations	Retrieve all observations for a memory	(A) Auto	Queries EAV table -> returns JSON list
update_observation	Update value and confidence of an observation	(A) Auto	Updates row -> returns updated observation
delete_observation	Delete a specific observation by ID	(A) Auto	Deletes row -> returns confirmation

Implementation details: EAV schema in shared_memory.observations table. Fields: obs_id (UUID), memory_id (FK), entity, attribute, value (TEXT), agent_id, confidence (FLOAT), created_at. Schema is lazily created on first use (CREATE TABLE IF NOT EXISTS).

Slack and Discord Notification Tools - Phase 14 (3)

Tool	Purpose	Trigger Type	Automation Chain
configure_slack_notifications	Register a Slack webhook channel	(A) Auto	Stores channel config in memory -> returns config
configure_discord_notifications	Register a Discord webhook channel	(A) Auto	Stores channel config in memory -> returns config
test_notification_channel	Send a test payload to a webhook channel	(A) Auto	Builds payload -> POSTs to webhook -> returns status

Implementation details: In-memory channel store keyed by channel_id. Supports per-channel event filtering (memory.added, memory.updated, memory.deleted, backup.completed, backup.failed, health.degraded). Uses aiohttp if available, falls back to urllib.request in thread executor.

Importance Scoring Tools - Phase 14 (3)

Tool	Purpose	Trigger Type	Automation Chain
get_memory_importance	Score a single memory's importance (0.0-1.0)	(A) Auto	Reads memory metadata -> applies heuristic formula
update_importance_scores	Batch-score and persist importance for N memories	(S) System	Reads memories -> scores -> UPSERTs importance_score column
get_top_important_memories	Return memories ranked by importance score	(A) Auto	Queries DB sorted by importance_score DESC

Scoring formula: access_count * 0.4 + recency * 0.3 + confidence * 0.2 + source_type * 0.1

Source type weights: verified=1.0, agent=0.8, user=0.7, system=0.5, unknown=0.3

Heuristic Re-ranking Tools - Phase 14 (1)

Tool	Purpose	Trigger Type	Automation Chain
rerank_search_results	Re-rank a list of search results by 4 signals	(S) System	Computes composite score -> sorts descending -> returns

Re-ranking formula: similarity * 0.50 + importance * 0.25 + recency * 0.15 + confidence * 0.10

All signals default to 0.5 when missing. Results are shallow-copied with a rerank_score key added.

Undo / Redo Tools - Phase 18 (3)

Tool	Purpose	Trigger Type	Automation Chain
undo_last	Reverse the last automated memory operation (24-hour rolling log)	(M) Manual	Loads undo log -> reverses operation -> publishes event -> logs to audit
get_undo_history	List recent reversible operations for the current agent	(A) Auto	Reads undo log -> filters by agent and TTL -> returns descending by timestamp
redo_last	Re-apply the most recently reversed operation	(M) Manual	Reads last undone entry -> re-applies -> updates log -> publishes event

24-hour rolling log; covers add_memory, update_memory, delete_memory, set_memory_sharing, forget_memory, archive_category, and revert_memory. Multi-step undo is supported.

---

How MCP Tools Work

Three Types of Tool Invocation

CRITICAL DISTINCTION: MCP tools can be invoked in THREE ways:

1. Manual Invocation (M) - User Controlled

How it works:

• User explicitly requests tool usage
• Through specific commands or UI actions
• Direct control over tool execution
• Used for destructive or policy operations

Examples of manual triggers:

User: "Delete all memories older than 1 year"

User explicitly triggers:
→ expire_memories(days=365, dry_run=False) [MANUAL - DESTRUCTIVE]

User: "Set this memory to expire in 30 days"

User explicitly triggers:
→ set_memory_ttl(memory_id="abc-123", ttl_days=30) [MANUAL - POLICY]

User: "Delete this specific memory"

User explicitly triggers:
→ delete_memory(memory_id="xyz-789") [MANUAL - DESTRUCTIVE]

Tools requiring manual invocation (14 tools):

These tools require explicit user intent because they are irreversible, destructive, policy-setting, or carry direct financial impact:

• delete_memory - Permanently removes a memory entry (irreversible)
• deduplicate - Manual deduplication pass (user-initiated, distinct from scheduled auto_deduplicate)
• set_cost_budget - Sets monthly LLM API cost limit (financial impact)
• archive_category - Archive all memories in a category (bulk state change)
• restore_backup - Overwrites live database state with a backup (destructive)
• cancel_task - Aborts a running background task
• forget_memory - Deletes entities and relationships from the knowledge graph (irreversible)
• revert_memory - Reverts a memory to a previous version (destructive)
• gdpr_delete_user_data - GDPR right to erasure (legal, irreversible)
• gdpr_record_consent - Record consent decision (legal, must be explicit human action)
• disable_webhook - Disables event delivery to an external webhook endpoint
• rotate_encryption_key - Re-encrypts all data with a new key (security, can't be interrupted)
• undo_last - Reverse the last automated memory operation (explicit human reversal)
• redo_last - Re-apply the most recently reversed operation (explicit human re-application)

2. Automatic Invocation (A) - AI IDE Controlled

How it works:

• AI IDE (Claude Code, Cursor, etc.) decides when to call tools
• Based on user queries and context needs
• No user intervention required
• Most common usage pattern

Examples of automatic triggers:

User: "What did we discuss about authentication?"

AI IDE automatically calls:
→ search_memories(query="authentication", limit=10)
→ Returns results
→ AI formulates response

No user action needed - completely automatic

User: "Remember that we use JWT for authentication"

AI IDE automatically calls:
→ add_memory(content="We use JWT for authentication") [AUTO]
→ System internally triggers:
→   check_duplicate(content="...") [SYSTEM AUTO]
→   publish_memory_event(event_type="memory_added") [SYSTEM AUTO]
→ Returns memory ID

Tools automatically triggered by MCP-compatible IDEs (40 tools):

• add_memory - When the IDE wants to remember information
• search_memories - When you ask about past information
• get_memories - When loading context for new sessions
• get_memory - When referencing specific memory IDs
• update_memory - When the IDE needs to correct information
• list_agents - When listing available agents
• cognify - When processing data into knowledge
• search - When searching knowledge graph
• list_data - When listing documents
• get_stats - When checking system status
• health - On startup to verify system status
• create_backup - When creating system backups
• get_shared_memories - When loading shared memories
• list_backups - When listing available backups
• list_tasks - When listing scheduled tasks
• get_supported_languages - When listing supported languages
• remember - When user says "remember/save/note this"
• recall - When user asks about past context or decisions
• cognify_status - When checking background task status
• ingest_url - When user provides a URL to learn from
• ingest_db - When user supplies database credentials for ingestion
• list_loaders - When user asks what file types are supported
• start_session - When starting a new memory session
• get_session_context - When retrieving active session context
• get_session_history - When browsing session history
• list_webhooks - When listing registered webhooks
• list_loader_plugins - When listing loader plugins
• load_document_with_plugin - When loading a document via plugin
• get_undo_history - When the user asks what operations can be reversed
• set_memory_sharing - When user says "share this with agent X" or expresses sharing intent
• create_shared_space - When user requests multi-agent collaboration ("create a shared workspace")
• set_memory_ttl - When user says "remember this for 30 days" or gives a time-bound retention hint
• end_session - When the conversation ends or user says "we're done for now"
• test_webhook - Automatically after register_webhook succeeds to verify the endpoint
• test_notification_channel - Automatically after configuring Slack/Discord to verify delivery
• configure_slack_notifications - When user provides a Slack webhook URL and event preferences
• configure_discord_notifications - When user provides a Discord webhook URL and event preferences
• gdpr_export_user_data - When user says "export my data" or requests data portability
• register_webhook - When user supplies a webhook endpoint URL for event delivery
• delete_observation - When AI IDE removes a specific EAV observation from a memory

3. System Invocation (S) - Enhanced Cognee Controlled

How it works:

• Enhanced Cognee automatically triggers tools based on events
• Chained automation after user/AI actions
• Scheduled maintenance tasks
• Performance monitoring and optimization
• No direct user or AI IDE intervention

Examples of system triggers:

User: "Add memory: We use JWT for authentication"

User triggers:
→ add_memory(content="We use JWT for authentication")

System automatically chains:
→ check_duplicate() [SYSTEM - checks for duplicates]
→ publish_memory_event() [SYSTEM - notifies other agents]
→ get_performance_metrics() [SYSTEM - logs performance]

System scheduled task runs:

System automatically triggers:
→ auto_deduplicate() [SYSTEM - scheduled maintenance]
→   → get_deduplication_stats() [SYSTEM - gets stats]
→   → publish_memory_event() [SYSTEM - notifies of duplicates]
→   → get_performance_metrics() [SYSTEM - logs performance]

Tools triggered by Enhanced Cognee system (68 tools):

Performance & Monitoring (5 tools):

• check_duplicate - Automatically called before add_memory
• publish_memory_event - Automatically called after memory changes
• get_performance_metrics - Automatically called after operations
• get_slow_queries - Automatically called on performance issues
• get_prometheus_metrics - Automatically called for monitoring

Statistics (7 tools):

• get_memory_age_stats - Automatically called by memory operations
• get_deduplication_stats - Automatically called by deduplication
• get_summary_stats - Automatically called by summarization
• get_summarization_stats - Automatically called for summarization metrics
• summary_stats - Automatically called for summary statistics
• get_sync_status - Automatically called on sync diagnostics
• check_memory_access - Automatically called before memory access

Deduplication (5 tools):

• auto_deduplicate - Automatically scheduled (maintenance)
• deduplicate - Automatically triggered for deduplication
• deduplication_report - Automatically generates reports
• schedule_deduplication - Automatically schedules deduplication
• verify_backup - Automatically called after create_backup

Summarization (6 tools):

• summarize_old_memories - Automatically scheduled (maintenance)
• summarize_category - Automatically triggered by policy
• intelligent_summarize - Automatically triggered for LLM summarization
• auto_summarize_old_memories - Automatically batch summarizes
• schedule_summarization - Automatically schedules summarization
• rollback_restore - Automatically called on restore failure

Multi-Language (6 tools):

• detect_language - Automatically detects text language
• get_supported_languages - Automatically lists supported languages
• search_by_language - Automatically searches by language
• get_language_distribution - Automatically gets language stats
• cross_language_search - Automatically performs cross-language search
• get_search_facets - Automatically gets search facets

Advanced AI & Search (4 tools):

• cluster_memories - Automatically clusters memories
• advanced_search - Automatically performs advanced search
• expand_search_query - Automatically expands queries
• get_search_analytics - Automatically gets analytics

Background task monitoring (Phase 2) (1 tool):

• cognify_status - Automatically tracks background remember/improve task status

Phase 8b - Scheduler-driven (3 tools, enable in .enhanced-cognee-config.json):

• expire_memories - Daily scheduler job (auto_scheduler.expire_memories.enabled=true)
• improve - Weekly quality improvement job (auto_scheduler.improve.enabled=true)
• schedule_task - Default tasks bootstrapped from config on server startup

Phase 8b - Post-ingestion hooks (3 tools, enable in .enhanced-cognee-config.json):

• translate_text - Auto-translates non-default-language content after ingestion
• regex_extract_entities - Auto-extracts named entities after every memory write
• extract_graph_v2 - Auto-enriches graph after ingestion (compute-intensive)

Phase 8b - TTL automation (1 tool, enable in .enhanced-cognee-config.json):

• set_memory_ttl - Auto-applied on write via keyword rules (auto_ttl_rules.rules)

Plan 14.8 - LLM Cost Tracking (1 System tool):

• get_llm_cost_report - Automatically called by monitoring dashboards and schedulers for periodic LLM spend reporting; also invoked automatically when the user asks about API costs or token usage

Summary (Phases 1-14 complete):

• 14 tools require explicit manual invocation (M) - irreversible/destructive/legal/financial-impact operations
• 40 tools are automatically triggered by AI IDEs (A)
• 68 tools are automatically triggered by Enhanced Cognee system (S)
• Total: 122 tools - 83% (101/122) called automatically, no user action required

Hybrid Approach (Best of All Three)

Example workflow showing Manual + Auto + System triggers:

sequenceDiagram
    participant User
    participant AI as AI IDE
    participant MCP as Enhanced Cognee MCP
    participant Sys as System Automation

    Note over User,AI: Session Start

    AI->>MCP: health() [AUTO - AI IDE]
    MCP-->>AI: All systems OK

    AI->>MCP: get_memories(limit=50) [AUTO - AI IDE]
    MCP->>Sys: get_performance_metrics() [SYSTEM - chained]
    MCP-->>AI: Returns 50 recent memories

    Note over User,AI: During Conversation

    User->>AI: "What did we decide about authentication?"

    AI->>MCP: search_memories("authentication") [AUTO - AI IDE]
    MCP->>Sys: get_performance_metrics() [SYSTEM - chained]
    MCP->>Sys: get_slow_queries() [SYSTEM - if slow]
    MCP-->>AI: Found 3 memories

    AI-->>User: "We decided to use JWT tokens..."

    Note over User,AI: Information to Remember

    User->>AI: "We use OAuth 2.0 for external services"

    AI->>MCP: add_memory("We use OAuth 2.0...") [AUTO - AI IDE]
    MCP->>MCP: check_duplicate() [SYSTEM - chained]
    MCP->>MCP: publish_memory_event() [SYSTEM - chained]
    MCP->>Sys: get_performance_metrics() [SYSTEM - chained]
    MCP-->>AI: Memory added (ID: xyz-789)

    Note over User,AI: Manual Policy Setting

    User->>AI: "Set this memory to expire in 30 days"

    AI->>MCP: set_memory_ttl(memory_id="xyz-789", ttl_days=30) [MANUAL - User]
    MCP->>Sys: get_memory_age_stats() [SYSTEM - chained]
    MCP->>Sys: get_performance_metrics() [SYSTEM - chained]
    MCP-->>AI: TTL set successfully

    Note over User,AI: Automatic System Maintenance

    Sys->>MCP: auto_deduplicate() [SYSTEM - scheduled]
    MCP->>MCP: get_deduplication_stats() [SYSTEM - chained]
    MCP->>MCP: publish_memory_event() [SYSTEM - chained]
    MCP->>Sys: get_performance_metrics() [SYSTEM - chained]
    Sys->>Sys: Scheduled task complete

    Note over User,AI: Later - Automatic Context

    AI->>MCP: get_memory("xyz-789") [AUTO - AI IDE]
    MCP->>Sys: get_performance_metrics() [SYSTEM - chained]
    MCP-->>AI: Returns OAuth memory

Key Benefits of Three-Way Trigger System:

1. Manual (M) - User Control

   • Explicit control over destructive operations (delete, expire, archive)
   • Policy configuration (TTL, sharing, backups)
   • Safety measures prevent accidental data loss

2. Auto (A) - AI IDE Intelligence

   • Context-aware tool invocation
   • Automatic memory retrieval and storage
   • Seamless integration with AI workflows

3. System (S) - Enhanced Automation

   • Automatic performance monitoring
   • Dependency chains (one operation triggers multiple)
   • Scheduled maintenance tasks
   • Real-time event publishing
   • Zero user intervention required

Complete Automation Example:

When you add a memory, the system automatically:

1. Checks for duplicates (System)
2. Publishes events to other agents (System)
3. Logs performance metrics (System)
4. Updates memory age statistics (System)
5. Detects slow queries if applicable (System)

All without any manual configuration - comprehensive automation out of the box!

---

v1.0.9 API Parity

Enhanced Cognee tracks and exposes the full topoteretes/cognee v1.0.9 public API via MCP tools.

Session-Aware Memory (Phase 2)

These tools wrap the cognee.api.v1.* modules added in upstream v1.0.9:

Tool	API Module	Description
remember	cognee.api.v1.remember	Session-aware ingestion with background mode
recall	cognee.api.v1.search	15-strategy knowledge graph retrieval
forget_memory	cognee.api.v1.forget	Targeted graph data deletion
improve	cognee.api.v1.improve	4-stage feedback improvement pipeline
save_interaction	cognee.api.v1.add + cognify	Record user/assistant exchanges
cognify_status	internal tracker	Check background task status

External Loaders and Enrichment (Phase 3)

Tool	Underlying Task	Description
ingest_url	web_scraper_task	Scrape URLs (BeautifulSoup or Tavily)
ingest_db	dlt pipeline	Ingest relational DB tables
translate_text	translate_content	LLM/Google/Azure translation
regex_extract_entities	RegexEntityExtractor	Configurable pattern NER
extract_graph_v2	cascade extract utils	Preview v2 graph extraction (n rounds)
list_loaders	supported_loaders	Show available file format loaders

Search Type Reference

All 15 SearchType values supported by recall and search:

Type	Description
GRAPH_COMPLETION	LLM-augmented graph traversal (recommended default)
GRAPH_COMPLETION_COT	Chain-of-thought graph reasoning
GRAPH_COMPLETION_DECOMPOSITION	Decompose query into sub-questions
GRAPH_COMPLETION_CONTEXT_EXTENSION	Extend context along graph edges
GRAPH_SUMMARY_COMPLETION	Search graph-level summaries
SUMMARIES	Document and chunk summaries
CHUNKS	Raw text chunk retrieval
CHUNKS_LEXICAL	BM25-style lexical chunk search
RAG_COMPLETION	Retrieval-augmented generation
TRIPLET_COMPLETION	Knowledge triplet retrieval
NATURAL_LANGUAGE	Natural language query parser
TEMPORAL	Time-aware knowledge retrieval
CODING_RULES	Retrieve coding rules and patterns
CYPHER	Direct Cypher query against graph
FEELING_LUCKY	Auto-select best strategy for query

---

Agent Integration

The original 21 SDLC agent modules (ATS, OMA, SMC categories) have been archived as of Phase 4 due to hardcoded category violations. Enhanced Cognee now uses a dynamic agent registry loaded from .enhanced-cognee-config.json. See .archive/2026-05-13_agents_ats_oma_smc/ARCHIVE_NOTES.md for migration guidance.

Dynamic Agent Registry

Agents are registered dynamically from your configuration file:

{
  "categories": {
    "my_agent": { "prefix": "agent_", "description": "My custom agent" }
  }
}

Enhanced Cognee supports unlimited custom agent types with:

• [OK] Valkey pub/sub for sub-millisecond agent coordination
• [OK] Event broadcasting (memory_added, memory_updated, memory_deleted)
• [OK] Automatic state synchronization between agents
• [OK] Cross-agent memory sharing with 4 access policies
• [OK] Per-agent performance metrics and Prometheus export

---

Cross-Language Client SDKs

Enhanced Cognee ships four official client SDKs that all hit the same HTTP contract -- the /mcp/* routes exposed by src/enhanced_cognee_mcp.py. Same 5 core endpoints, same X-API-Key + X-Tenant-ID headers.

Language	Location	Tests	Status
Python	clients/python/ (PyPI: enhanced-cognee-client)	Production-grade integration tests	v1.0.0 on PyPI
Node.js / TypeScript	clients/node/	7 unit tests using node:test + mocked fetch	npm-ready (PR #41)
Go	clients/go/	9 unit tests using net/http/httptest (no external deps)	pkg.go.dev-ready (PR #41)
Rust	clients/rust/	7 integration tests using wiremock, async via tokio + reqwest (rustls-tls)	crates.io-ready (PR #41)

Each SDK follows its language's idioms (Python async/await, Node Promises, Go context.Context as first arg, Rust Result<T, Error> with thiserror).

Python SDK

pip install enhanced-cognee-client

PyPI: https://pypi.org/project/enhanced-cognee-client/1.0.0/

import asyncio
from enhanced_cognee_client import EnhancedCogneeClient

async def main():
    async with EnhancedCogneeClient(host="localhost", port=8080) as client:
        result = await client.add_memory(
            content="Enhanced Cognee has 122 MCP tools",
            user_id="default",
            agent_id="my-agent",
        )
        hits = await client.search_memories(query="MCP tools", limit=5)
        status = await client.health()

asyncio.run(main())

Node.js / TypeScript SDK

import { EnhancedCogneeClient } from "@enhanced-cognee/client";

const client = new EnhancedCogneeClient({
  baseUrl: "http://localhost:8080",
  apiKey: process.env.ENHANCED_API_KEY,
  tenantId: "acme",
});

await client.addMemory({ content: "...", agentId: "my-agent" });
const results = await client.searchMemories({ query: "MCP tools", limit: 5 });

Go SDK

import "github.com/vincentspereira/enhanced-cognee/clients/go"

ctx := context.Background()
client := cognee.New(cognee.Options{
    BaseURL: "http://localhost:8080",
    APIKey:  os.Getenv("ENHANCED_API_KEY"),
    TenantID: "acme",
})

memID, err := client.AddMemory(ctx, cognee.AddMemoryRequest{
    Content: "...",
    AgentID: "my-agent",
})

Rust SDK

use enhanced_cognee::ClientBuilder;

let client = ClientBuilder::new("http://localhost:8080")
    .api_key(std::env::var("ENHANCED_API_KEY").ok())
    .tenant_id("acme")
    .build()?;

let id = client.add_memory("...", "my-agent", None).await?;
let hits = client.search_memories("MCP tools", 5, None).await?;

SDK Features (all four languages)

• Async-first
• Never raises on network errors -- returns typed error objects
• Full type annotations / strict typing
• 5 core endpoints: add_memory, search_memories, get_memories, update_memory, delete_memory, list_agents (plus health)
• Supports X-Tenant-ID header for multi-tenant deployments
• Supports X-API-Key header for MCP server hardening

---

Multi-Tenant Data Partitioning

Enhanced Cognee enforces tenant isolation at the storage layer. Each tenant's data lives in its own Postgres tables (shared_memory.documents_t_<tenant>), Qdrant collections (<name>_t_<tenant>), Valkey key prefixes (t_<tenant>:...), and graph databases (<name>_t_<tenant>). No application code has to be aware of tenancy -- it's transparent via Python's ContextVar.

How it works

from src.multi_tenant import TenantContext

# Sync use
async with TenantContext("acme"):
    await add_memory(content="...", agent_id="bot")
    # -> writes to shared_memory.documents_t_acme
    # -> Qdrant collection embeddings_t_acme
    # -> Valkey key t_acme:cache:...

# HTTP callers send X-Tenant-ID header; FastAPI middleware
# opens the TenantContext for the entire request automatically.

Features

• TenantContext ContextVar -- sync + async context managers; nested contexts unwind correctly per asyncio task
• Naming helpers -- tenant_scoped_table(), tenant_scoped_collection(), tenant_scoped_key(), tenant_scoped_graph()
• Lazy schema bootstrap -- ensure_tenant_schema(pool) creates per-tenant tables on first write via CREATE TABLE LIKE INCLUDING ALL (idempotent)
• HTTP middleware -- FastAPI middleware extracts X-Tenant-ID request header and opens TenantContext for the entire request
• Tenant ID sanitisation -- _sanitize_tenant_id() enforces ^[A-Za-z0-9_]{1,64}$ to prevent SQL/Cypher injection via tenant IDs
• Production safety knob -- ENHANCED_REQUIRE_TENANT=1 makes un-tenanted storage calls raise instead of silently falling back to the global tables
• 15 isolation tests -- verify that tenant A's writes never appear in tenant B's reads across Postgres / Qdrant / Valkey / graph

See src/multi_tenant.py for the implementation and tests/unit/test_multi_tenant_isolation.py for the cross-tenant test matrix.

---

MCP Server Hardening

The MCP server (stdio + HTTP variants) supports three layered defences for production deployments:

API-key authentication

export ENHANCED_API_KEY="your-secret-token"

Once set, every MCP tool call (stdio) or HTTP request (FastAPI) must include the matching X-API-Key header or api_key= kwarg. Calls without it raise AuthenticationError (stdio) / HTTPException(401) (HTTP).

Per-tool rate limiting

Token-bucket algorithm keyed on (tool_name, agent_id). Default is unlimited (rate limiting off); enable via:

export ENHANCED_RATE_LIMIT_PER_MINUTE=120

Hits return RateLimitExceeded (stdio) / HTTPException(429) (HTTP) with a Retry-After hint.

Payload size cap

export ENHANCED_MAX_PAYLOAD_BYTES=1048576    # 1 MiB

Requests larger than this raise PayloadTooLarge (stdio) / HTTPException(413) (HTTP). Default cap is generous (10 MiB) so caches and document uploads still work.

See src/mcp_security.py for the implementation and the typed errors callers can catch.

---

Performance Benchmarks

Enhanced Cognee ships two complementary benchmark suites:

1. Synthetic per-tool dispatch benchmark (benchmarks/benchmark_all_tools.py) -- measures the Python dispatch overhead for all 122 MCP tools using mocked database pools. Useful for catching algorithmic regressions in the tool layer.
2. Real cross-provider Locust benchmark (tests/benchmarks/run_provider_comparison.py) -- drives Locust against the live MCP HTTP variant for 5 provider permutations (default / lean / neo4j_stack / embedded / memgraph_kuzu) and emits side-by-side RPS / p50 / p95 / p99 / error% tables (JSON + Markdown). Used by the CI regression gate via compare_to_baseline.py.

Real benchmark baseline (2026-05-21)

First non-synthetic baseline shipped 2026-05-21. Captured against a live stack (Neo4j 5.25 + Qdrant 1.12 + Valkey 8 + PostgreSQL 18 + pgvector). 60s duration, 20 concurrent users, 5/sec spawn rate:

Permutation	Graph	Vector	Cache	Relational	RPS	p50 (ms)	p95 (ms)	p99 (ms)	Error %
neo4j_stack	neo4j	qdrant	redis	postgres	49.06	2	7	11	0.00

2,911 requests served, 0 failures. Per-endpoint breakdown in tests/benchmarks/baselines/2026-05-21_neo4j_stack.md. The four remaining permutations (default with ArcadeDB / lean with Apache AGE+pgvector / embedded with ladybug+lancedb / memgraph_kuzu) need their respective stacks running before they can be baselined; compare_to_baseline.py treats them as "[NEW] -- no baseline, skipped" so the regression gate stays inert for them rather than ringing false alarms.

Re-run the live benchmark yourself:

# 1. Boot the stack
docker compose -f docker/docker-compose-enhanced-cognee.yml up -d

# 2. Boot the MCP HTTP variant
python -m uvicorn src.enhanced_cognee_mcp:app --host 127.0.0.1 --port 8080 &

# 3. Run the benchmark
python -m tests.benchmarks.run_provider_comparison \
    --host http://127.0.0.1:8080 \
    --users 20 --spawn-rate 5 --duration 60s \
    --permutations neo4j_stack \
    --output-dir tests/benchmarks/baselines/output

Synthetic per-tool dispatch benchmark

python benchmarks/benchmark_all_tools.py

Results are saved to benchmarks/results/benchmark_results.json.

Benchmark Results (2026-05-14)

Category	Tools	mean_ms	p50_ms	p95_ms
core_memory	13	0.02	0.00	0.05
knowledge_graph	5	0.01	0.00	0.04
ttl_archive	4	0.00	0.00	0.00
deduplication	6	0.00	0.00	0.00
summarization	8	0.00	0.00	0.00
performance_mon	3	0.00	0.00	0.00
sharing_sync	7	0.00	0.00	0.00
backup	5	0.00	0.00	0.01
scheduling	3	0.00	0.00	0.00
language	6	0.03	0.04	0.05
search_advanced	4	0.00	0.00	0.00
ingestion	6	0.02	0.02	0.05
cost	2	0.00	0.00	0.00
session	4	0.00	0.00	0.00
audit_prov	7	0.04	0.06	0.07
consolidation	7	0.04	0.06	0.10
gdpr	6	0.01	0.01	0.01
plugins_webhooks	6	0.04	0.07	0.08
phase14	17	0.05	0.06	0.08
Overall	122	-	0.00	0.07

Key finding: All production latency is DB-bound, not Python-bound. The Python dispatch layer adds 0.07ms (p95) across all 122 tools. Slowest function: get_memory_importance (0.22ms mean due to singleton init cold-start). Fastest: list_agents (0.00ms).

---

Testing

Enhanced Cognee has a comprehensive test suite with 100% pass rate:

# Install test dependencies
pip install -r requirements-test.txt

# Run all tests
python run_tests.py

# Or run specific categories
pytest tests/unit/ -v -m unit
pytest tests/integration/ -v -m integration
pytest tests/system/ -v -m system
pytest tests/e2e/ -v -m e2e

# Generate coverage report
pytest --cov=src --cov-report=html
open htmlcov/index.html

Test Statistics

• Total Test Files: 129 test modules (96 unit + 3 system + 7 integration + 3 benchmarks + 2 load + 2 e2e + the rest)
• Total collected tests: 4,661 (4,137 unit + 93 system + others)
• Unit tests: 4,137 passing (100% pass rate)
• System tests: 93 (tests/system/)
• Integration tests: tests/integration/ boots real DBs; non-blocking in CI via continue-on-error: true. Includes 8 live ArcadeDB + Apache AGE tests and the live SigNoz smoke test (test_signoz_smoke.py, gated by ENHANCED_RUN_SIGNOZ_SMOKE=1).
• Multi-tenant isolation tests: 15 cross-tenant tests verifying tenant A's writes never bleed into tenant B's storage across Postgres / Qdrant / Valkey / graph.
• Benchmark suite: tests/benchmarks/run_provider_comparison.py drives Locust against 5 provider permutations + emits comparison tables. First real baseline shipped 2026-05-21 (baselines/2026-05-21_neo4j_stack.json -- 49.06 RPS / p50=2ms / p95=7ms / p99=11ms / 0 failures).
• Load tests: tests/load/locustfile.py -- 8 HttpUser classes (read-heavy / write-heavy / mixed / health + 4 Phase-5 scenarios: SemanticSearch / KnowledgeGraph / GDPRWorkflow / BackupVerify).
• Coverage gap auditor: tests/coverage_audit.py reads coverage.xml, reports modules below the 85% gate sorted by uncovered count.
• Code Coverage: 95%+ unit coverage (pytest.ini gate at 85%)
• Success Rate: 100% (4,137 / 4,137 unit tests passing)
• Warnings: 0
• Skipped Tests: 0 in unit suite; integration tests skip gracefully when a live service isn't reachable.

Testing Guide: Testing Guide

---

Documentation

Comprehensive documentation is available:

Document	Description
README.md	This file - project overview
Cognee vs Enhanced Comparison	Full 122-tool feature-by-feature comparison
GitHub Release v1.0.0	Release notes and changelog
PyPI: enhanced-cognee-client	Python SDK on PyPI
Profiles + per-adapter caveats	The 5 pre-baked profiles + the per-adapter supported-method matrix (PostgreSQL, Qdrant, ArcadeDB, Apache AGE, Neo4j, Memgraph, Kuzu, NetworkX, ArangoDB, NebulaGraph, Ladybug + all vector adapters)
Pluggable DB Backends	Architectural overview of the 4-tier pluggable factory + how to add a new adapter
ArcadeDB Migration	How to migrate from a Neo4j default to ArcadeDB (or back)
Phase 5 Outstanding TODO	Honest accounting of what's shipped vs deferred since 2026-05-20
License Audit	Per-component licence analysis for the default stack
Feature -> License Matrix	Per-feature OSS dependency + license + MAS-incorporation verdict (use when porting features into closed-source / commercial products)
Strategy	Long-term roadmap, decision records, alternative stacks
Compare to Alternatives	Enhanced Cognee vs Mem0 / Letta / LangChain
Master Implementation Plan	Comprehensive project roadmap and plans
MCP IDE Setup Guide	Multi-IDE setup for MCP-compatible IDEs
SDLC Agents Integration Guide	21 SDLC agents integration guide
Testing Guide	Complete testing guide
Superset Dashboards	5 importable Superset dashboards (memory_growth, agent_activity, llm_cost_trends, dedup_effectiveness, perf_regression) + dataset definitions
Monitoring (SigNoz + Superset)	Phase 4 observability stack overview (replaces Grafana + Loki + Tempo + Jaeger)
Task Completion Summary	Task completion summary
Contributing Guidelines	Contribution guidelines
Contributors	Contributor history
Enhancement Roadmap	12-month enhancement roadmap
Audit Summary	Comprehensive audit summary
Final Completion Summary	Final completion summary
Production Deployment Guide	Production deployment guide
Security Hardening Checklist	Security hardening checklist
Monitoring Setup Guide	Monitoring setup guide
Multi-Language Guide	Multi-language support guide
Deduplication Guide	Deduplication guide
Summarization Guide	Summarization guide

---

Configuration

Dynamic Categories

Create .enhanced-cognee-config.json in your project root:

{
  "categories": {
    "trading": {
      "prefix": "trading_",
      "description": "Trading system memories"
    },
    "development": {
      "prefix": "dev_",
      "description": "Development-related memories"
    },
    "analysis": {
      "prefix": "analysis_",
      "description": "Analysis and reports"
    }
  }
}

No code changes required - Enhanced Cognee loads categories at runtime. Any category name, any prefix.

Port Configuration

Enhanced Cognee uses non-standard ports to avoid conflicts:

Service	Default Port	Enhanced Port
PostgreSQL	5432	25432
Qdrant	6333	26333
ArcadeDB Bolt	7687	27687
ArcadeDB Studio HTTP	2480	22480
Valkey	6379	26379

Environment Variables

See .env.example for all available configuration options.

---

Usage Examples

Example 1: Basic Memory Operations with MCP

# In any MCP-capable IDE or client:

# Add a memory
/add_memory "I prefer TypeScript for frontend development"

# Search memories
/search_memories "TypeScript"

# Get all memories
/get_memories

# Check system health
/health

Example 2: Multi-Agent Coordination

import asyncio
from src.realtime_sync import RealTimeMemorySync

async def main():
    # Initialize sync
    sync = RealTimeMemorySync(redis_client, postgres_pool)

    # Agent 2 subscribes to updates
    async def on_memory_update(event):
        print(f"Received update: {event['event_type']}")

    await sync.subscribe_to_updates("agent-2", on_memory_update)

    # Agent 1 publishes memory event
    await sync.publish_memory_event(
        event_type="memory_added",
        memory_id="mem-123",
        agent_id="agent-1",
        data={"content": "Important requirement"}
    )

Example 3: Memory Sharing Setup

from src.cross_agent_sharing import CrossAgentMemorySharing, SharePolicy

async def main():
    sharing = CrossAgentMemorySharing(postgres_pool)

    # Set memory as shared across team
    await sharing.set_memory_sharing(
        memory_id="project-design",
        policy=SharePolicy.SHARED
    )

    # Or use custom whitelist
    await sharing.set_memory_sharing(
        memory_id="sensitive-data",
        policy=SharePolicy.CUSTOM,
        allowed_agents=["agent-1", "agent-2"]
    )

---

Development

Project Structure

enhanced-cognee/
├── README.md                          # This file
├── LICENSE                            # Apache 2.0 license
├── .env.example                       # Environment template
├── .gitignore                         # Git ignore rules
├── requirements.txt                   # Runtime dependencies
├── requirements-test.txt              # Test dependencies
├── pytest.ini                         # Pytest configuration
├── bin/                               # Executable scripts
│   ├── enhanced_cognee_mcp_server.py  # Main MCP server
│   ├── install.py                     # Python installer
│   └── run_tests.py                   # Test runner script
├── setup/                             # Installation scripts
│   ├── install.sh, install.ps1        # Platform-specific installers
│   └── uninstall.sh, uninstall.ps1    # Uninstall scripts
├── config/                            # Configuration files
│   ├── docker/                        # Docker compose files
│   │   └── docker-compose-enhanced-cognee.yml
│   ├── environments/                  # Environment templates
│   └── automation/                    # Automation configs
├── cognee/                            # Original Cognee framework
│   └── infrastructure/                # Database adapters
├── src/                               # Enhanced Cognee modules
│   ├── memory_management.py           # TTL, expiry, archival
│   ├── memory_deduplication.py        # Duplicate detection
│   ├── memory_summarization.py        # Auto summarization
│   ├── performance_analytics.py       # Metrics collection
│   ├── cross_agent_sharing.py         # Access control
│   ├── realtime_sync.py               # Valkey pub/sub sync (Redis protocol)
│   ├── multi_language_search.py       # 28-language support
│   ├── scheduled_deduplication.py     # Scheduled dedup runner
│   ├── scheduled_summarization.py     # Scheduled summ runner
│   ├── maintenance_scheduler.py       # Task scheduler
│   ├── backup_manager.py              # Backup and recovery
│   ├── plugin_registry.py             # Plugin loader system
│   ├── webhook_manager.py             # Webhook delivery
│   ├── encryption_manager.py          # Fernet encryption at rest
│   ├── memory_observation.py          # EAV structured observations
│   ├── notification_manager.py        # Slack/Discord notifications
│   ├── memory_importance_scorer.py    # Heuristic importance scoring
│   └── memory_reranker.py             # Multi-signal re-ranking
├── enhanced_cognee_client/            # Python SDK package
│   ├── __init__.py
│   ├── client.py                      # EnhancedCogneeClient (16 methods)
│   ├── exceptions.py                  # Typed exception hierarchy
│   └── py.typed                       # PEP 561 marker
├── benchmarks/                        # Performance benchmarks
│   ├── benchmark_all_tools.py         # N=50 benchmark for all 122 tools
│   └── results/benchmark_results.json # Baseline timing data
├── tests/                             # Comprehensive test suite
│   ├── unit/                          # Unit tests
│   ├── integration/                   # Integration tests
│   ├── system/                        # System tests
│   ├── e2e/                           # End-to-end tests
│   └── conftest.py                    # Pytest fixtures
└── docs/                              # Comprehensive documentation

Running Tests

# Install test dependencies
pip install -r requirements-test.txt

# Run all tests
python run_tests.py

# Run with coverage
pytest --cov=src --cov-report=html

---

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Fork the repository
git clone https://github.com/vincentspereira/Enhanced-Cognee.git
cd Enhanced-Cognee

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
python run_tests.py

Development: Pre-Commit Hooks

# Install pre-commit (once per dev machine)
pip install pre-commit

# Install the hooks into .git/hooks/
pre-commit install

# Run all hooks on all files (verify setup)
pre-commit run --all-files

# Run hooks on staged files only (automatic on git commit)
git add <files>
pre-commit run

Hooks run on every git commit:

• Trailing whitespace + file hygiene
• ruff linting with auto-fix (replaces Black)
• ruff-format code formatting
• bandit security scan
• No hardcoded ATS/OMA/SMC categories gate (inline Python hook)
• ASCII-only output check on bin/enhanced_cognee_mcp_server.py (inline Python hook)

Hook at pre-push stage only:

• Fast unit test subset (no DB required, runs in under 60s)

---

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright

Enhanced Cognee is derived from Cognee by Topoteretes UG, licensed under the Apache License, Version 2.0.

The Apache 2.0 license requires that:

1. This notice is preserved in all distributions
2. The original Cognee project is credited (done above)
3. Changes from the original are noted (done in git history and this README)

Copyright 2024 Topoteretes UG (Original Cognee)
Copyright 2026 Vincent S. Pereira (Enhanced Cognee additions)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

---

Acknowledgments

Original Cognee

Enhanced Cognee is a derivative work based on the excellent Cognee framework by Topoteretes UG.

• Original Repository: https://github.com/topoteretes/cognee
• Original Documentation: https://docs.cognee.ai/
• Original License: Apache License 2.0

Third-Party Libraries

Enhanced Cognee integrates with these excellent open-source projects:

• PostgreSQL: https://www.postgresql.org/
• pgvector: https://github.com/pgvector/pgvector
• Qdrant: https://qdrant.tech/
• ArcadeDB: https://arcadedb.com/ (default graph store, Apache-2.0)
• Apache AGE: https://age.apache.org/ (Postgres extension; graph alternate)
• Memgraph: https://memgraph.com/
• Kuzu: https://kuzudb.com/
• NebulaGraph: https://www.nebula-graph.io/
• ArangoDB: https://www.arangodb.com/
• NetworkX: https://networkx.org/
• LanceDB: https://lancedb.com/
• Chroma: https://www.trychroma.com/
• Weaviate: https://weaviate.io/
• Milvus: https://milvus.io/
• Neo4j: https://neo4j.com/
• Valkey: https://valkey.io/ (default cache, Apache-2.0)
• Memcached: https://memcached.org/
• SigNoz: https://signoz.io/ (OTel APM, MIT)
• Apache Superset: https://superset.apache.org/ (BI dashboards)
• Locust: https://locust.io/ (load testing)
• FastMCP: https://github.com/jlowin/fastmcp

Special Thanks

• The original Cognee development team for creating an excellent framework
• The contributors to all the underlying open-source projects
• The MCP protocol specification contributors
• All contributors to Enhanced Cognee

---

Support

• Documentation: See the docs/ directory and MD files in project root
• Issues: Report bugs and request features via GitHub Issues
• Discussions: Use GitHub Discussions for questions

---

Project Files

Key documents and references:

File	Purpose
LICENSE	Apache-2.0 license text
NOTICE	Third-party attributions (Apache-2.0 requirement)
SECURITY.md	Responsible disclosure policy
CODE_OF_CONDUCT.md	Contributor Covenant v2.1
docs/DEPLOYMENT_QUICKSTART.md	Local + VPS deployment runbooks
docs/LICENSE_AUDIT.md	Full license analysis of every component
docs/FEATURE_LICENSE_MATRIX.md	Per-feature license + MAS-incorporation verdict
docs/PRODUCTION_READINESS_PLAN.md	Six-phase roadmap (all phases complete)
docs/COMPARE_TO_ALTERNATIVES.md	Enhanced Cognee vs Mem0 / Letta / LangChain
docs/PROFILES.md	5 pre-baked profiles + per-adapter supported-method matrices
docs/PLUGGABLE_DB_BACKENDS.md	Architectural overview of the 4-tier pluggable factory
docs/PHASE5_TODO.md	Honest Phase 5 backlog accounting
docs/ARCADEDB_MIGRATION.md	Neo4j -> ArcadeDB migration guide
docs/MONITORING.md	SigNoz + Superset observability stack (replaced Grafana + Loki + Tempo + Jaeger in Phase 4)
docs/STRATEGY.md	Long-term roadmap, decision records, alternative stacks
docs/operations/RUNBOOK.md	10 incident playbooks
docs/operations/MULTI_TENANT_DESIGN.md	Multi-tenant architecture (deferred)
docs/operations/OPENTELEMETRY_GUIDE.md	Distributed tracing setup
docs/operations/SECRETS_MANAGEMENT.md	Secret-handling approaches
monitoring/superset-dashboards/README.md	5 importable Superset dashboards + dataset definitions
tests/load/README.md	Locust load-test workload spec (8 user classes)
tests/benchmarks/run_provider_comparison.py	Cross-provider benchmark runner (5 permutations)
deploy/local/install.ps1	Windows installer
deploy/local/install.sh	Linux/macOS installer
deploy/vps/README.md	Hetzner CX22 deployment runbook
deploy/integration-with-mas/README.md	Multi-Agent System integration

---

Contributors

<a href="https://github.com/vincentspereira/Enhanced-Cognee/graphs/contributors"> <img src="https://contrib.rocks/image?repo=vincentspereira/Enhanced-Cognee" alt="Contributors" /> </a>

Contributions welcome! See CODE_OF_CONDUCT.md for the contributor covenant and SECURITY.md for responsible disclosure.

---

Roadmap

Production-ready today. Items shipped during 2026-05-19..2026-05-21 sprint are pulled out of the roadmap; remaining post-launch enhancements (in priority order):

Status	Item	Notes
✅ Shipped 2026-05-21	Multi-tenant data partitioning	TenantContext + naming helpers + per-tenant Postgres schema bootstrap + X-Tenant-ID HTTP middleware (PRs #39, #42, #43). 15 cross-tenant isolation tests.
✅ Shipped 2026-05-21	Cross-language SDKs	Node + Go + Rust clients alongside Python (PR #41).
✅ Shipped 2026-05-20	Pluggable database backends	30 providers across 4 tiers shipped via PRs #19-#46.
✅ Shipped 2026-05-19	Apache AGE replacing Neo4j	ArcadeDB became the default (PR #20); Apache AGE shipped as alternate (PR #21).
✅ Shipped 2026-05-19	OpenTelemetry / Jaeger wiring	OpenTelemetry shipped via SigNoz observability swap (PR #22); live smoke test added in PR #38.
Considered	sops + age encrypted secrets	When multi-developer deploys begin.
Considered	Publish 3 new SDKs to public registries	Node to npm, Go to pkg.go.dev, Rust to crates.io. Code is registry-ready; CI release workflow not yet wired.
Considered	Baseline the remaining 4 benchmark permutations	default (ArcadeDB stack), lean (Apache AGE+pgvector), embedded (ladybug+lancedb), memgraph_kuzu. Need their respective stacks running.
Future	Web UI dashboard	Currently terminal/MCP-only (Superset dashboards exist but for observability, not Cognee admin).
Future	Distributed deployment (Swarm/K8s)	Single-node only today.
Future	Multi-Agent System integration	Deferred to a future session per the original session constraint.

See docs/PRODUCTION_READINESS_PLAN.md for the full roadmap with effort estimates.

---

Star History

---

<div align="center">

Built as an enhanced fork of Cognee

Enterprise-Grade AI Memory Infrastructure for Multi-Agent Systems

Star us on GitHub · Report Issues · Request Features

Documentation · Testing Guide · Multi-IDE Setup · Agent Integration

</div>