Implement multi-tenancy support with Cognee

[yannickmonney]

Summary

Add multi-tenancy support to enable team/organization-level data isolation, ensuring users can only access information within their authorized scope.

Motivation

Currently, our application does not support multi-tenancy, meaning all users share access to the same knowledge base and datasets. This creates several issues:

Data Privacy: Sensitive information from one team is visible to all users
Security Risk: No access control boundaries between departments/organizations
Compliance: Cannot meet data isolation requirements for enterprise customers
Scalability: Limits our ability to onboard multiple organizations or teams

Proposed Solution

Leverage Cognee's built-in permission system to implement tenant isolation. Cognee provides native support for:

Per-user/per-tenant database isolation (separate Kùzu graph and LanceDB vector stores)
Role-based access control (RBAC)
Dataset-level permissions

See: https://docs.cognee.ai/setup-configuration/permissions#enable-permission-system

[larryro]

Knowledge Agents Implementation Plan

Requirements Overview

Users want to create "Knowledge Agents" (similar to Custom GPTs) with the following capabilities:

• Knowledge Isolation: Can only access knowledge from a specific Team
• Access Control: Can only be accessed by Team members
• Tool Inheritance: Same toolset as the main Chat Agent, but with scoped knowledge

Design Decisions

1. Knowledge Isolation: Documents tagged with Team → Sync to Team-specific Cognee Dataset
2. Access Control: Better Auth Teams
3. Multi-Team Sharing: Documents with multiple Team tags → Sync to multiple Datasets (data redundancy allowed)
4. Agent Capabilities: Inherit default toolset

---

Prerequisite: Graph Database Migration

Current Limitation

The current RAG service uses Kuzu Remote as the graph database:

• Configuration: graph_db_provider: "kuzu-remote" pointing to http://graph-db:8000
• Problem: Cognee's multi-tenancy requires ENABLE_BACKEND_ACCESS_CONTROL=true, but kuzu-remote requires this flag to be false
• This means Dataset-level isolation cannot work properly with the current setup

Recommended Solution: Migrate to Neo4j

Based on Cognee documentation, Neo4j is recommended for production multi-tenant systems:

Database	Multi-Tenancy Support	Notes
Kuzu (local)	❌ No	File-based, single user only
Kuzu Remote	❌ No	Requires ENABLE_BACKEND_ACCESS_CONTROL=false
Neo4j	✅ Yes	Built-in RBAC, enterprise-grade, recommended
Neptune Analytics	✅ Yes	AWS managed, hybrid vector+graph

Neo4j Advantages:

• Native multi-tenant support with proper ACL
• Production-ready with enterprise features
• Well-supported by Cognee
• Self-hosted or managed options (Neo4j Aura)

---

Current Architecture Analysis

Current State

Component	Current	Target
Graph Database	Kuzu Remote (no ACL)	Neo4j (with ACL)
Knowledge Isolation	Organization-level (single Dataset)	Team-level (one Dataset per Team)
RAG Search	No filtering	Search by Team Dataset
Permission System	Table-level RBAC	+ Team membership access control
Agent Configuration	Single global agent	Multiple custom Agents

---

Core Concept: Team Tags → Dataset Isolation

Organization: Acme Corp
│
├── Teams (Better Auth) ←→ Cognee Datasets
│   ├── team_sales ←→ Dataset "tale_team_sales"
│   ├── team_hr ←→ Dataset "tale_team_hr"
│   └── team_exec ←→ Dataset "tale_team_exec"
│
├── Documents (with Team tags)
│   ├── Doc1 (teamTags: ["sales", "exec"])     → Sync to 2 Datasets
│   ├── Doc2 (teamTags: ["hr"])                → Sync to 1 Dataset
│   ├── Doc3 (teamTags: ["sales"])             → Sync to 1 Dataset
│   └── Doc4 (teamTags: [])                    → Sync to org-level Dataset
│
├── Knowledge Agents
│   ├── "Sales Bot" (teamId: team_sales)
│   │   ├── Search: Dataset "tale_team_sales"
│   │   └── Access: Sales Team members only
│   │
│   ├── "HR Bot" (teamId: team_hr)
│   │   ├── Search: Dataset "tale_team_hr"
│   │   └── Access: HR Team members only
│   │
│   └── "Executive Bot" (teamId: team_exec)
│       ├── Search: Dataset "tale_team_exec"
│       └── Access: Exec Team members only
│
└── Default Chat Agent (no teamId)
    ├── Search: Dataset "tale_documents" (org-level)
    └── Access: All organization members

---

Implementation Phases

Phase 0: Graph Database Migration (Prerequisite)

• Add Neo4j service to compose.yml
• Update RAG service config for Neo4j connection
• Set ENABLE_BACKEND_ACCESS_CONTROL=true
• Remove kuzu-remote service
• Test Dataset isolation

Phase 1: Infrastructure (Better Auth + Schema)

• Enable Better Auth Teams plugin
• Add knowledgeAgents table
• Add teamTags fields to documents table

Phase 2: RAG Service Modification

• Support dataset_name parameter in add/search/delete operations
• Test multi-Dataset isolation

Phase 3: RAG Sync Workflow

• Modify workflow to sync documents to Team-specific Datasets
• Handle tag change detection and diff sync

Phase 4: Convex Agent Modification

• Create createKnowledgeAgent() factory
• Create createScopedRagSearchTool() tool factory
• Add RLS access control

Phase 5: Chat Integration

• Support Knowledge Agent in chat mutations

Phase 6: Frontend

• Team management UI
• Document Team tag management
• Knowledge Agent management page
• Chat interface Agent selector

---

Key File Modifications

File	Modification
compose.yml	Add Neo4j service, remove kuzu-remote
services/rag/app/config.py	Update graph_db settings for Neo4j
convex/auth.ts	Enable Teams plugin
convex/schema.ts	Add knowledgeAgents table, extend documents
convex/lib/create_knowledge_agent.ts	New: Knowledge Agent factory
convex/agent_tools/rag/rag_search_tool.ts	Add createScopedRagSearchTool()
services/rag/app/services/cognee/service.py	Support dataset_name parameter

---

Full detailed plan available in the repository.

[yannickmonney]

@larryro Shall we replace Kuzu with Neo4j?