Unified Document Intelligence Pipeline

DEEP is a local-first AI platform that merges document intelligence, multi-agent reasoning, and persistent memory into a single system. It runs entirely on your hardware — no cloud, no data leakage. Upload documents, build hierarchical indexes, and interact with specialized agents that research, tutor, generate, and solve problems using your local LLM.

Modern AI tools force a choice: powerful cloud APIs that send your data elsewhere, or local models that lack the orchestration to do anything useful with them. DEEP bridges this gap. It pairs local inference (via LM Studio, Ollama, or llama.cpp) with a full agent system, structured retrieval pipeline, and persistent memory — all running on your own machine.

The result is a platform where a student can upload lecture notes and get guided tutoring, a researcher can compile deep multi-source analysis, and a developer can query their codebase through a knowledge graph — without any data leaving their network. Every component, from the 3-tier model manager that balances VRAM across always-resident and on-demand models, to the 14-table memory system that tracks episodic recall and semantic facts, is designed for the constraints and strengths of consumer hardware.

Full architecture details: ARCHITECTURE.md

graph TB
    subgraph Frontend["Frontend — Next.js 16.2 :3782"]
        UI[React 19 + TypeScript]
        WS[WebSocket Provider]
        MP[Memory Provider]
    end

    subgraph Backend["Backend — FastAPI 0.136 :8001"]
        MW[Middleware Stack — 6 layers]
        R[7 Routers]
        SVC[38+ Services]
        WS1["/api/v1/solve (WS)"]
        WS2["/ws/metrics (WS)"]
    end

    subgraph Inference["Inference — LM Studio :1234"]
        T1[T1 Always Resident]
        T2[T2 Semi-Resident]
        T3[T3 On-Demand]
        TQ[TurboQuant KV Cache]
    end

    subgraph Storage["Storage — Local"]
        DB[(SQLite + FTS5 — 14 tables + 3 FTS5)]
        FS[File System — Knowledge Bases]
        KG[Knowledge Graph]
        IDX[PageIndex Trees]
    end

    UI --> WS
    UI --> MP
    WS --> Backend
    MP --> Backend
    MW --> R --> SVC
    SVC --> Inference
    SVC --> Storage
    T1 --> TQ
    T2 --> TQ
    T3 --> TQ

sequenceDiagram
    participant U as User
    participant FE as Frontend
    participant MW as Middleware
    participant BE as Backend
    participant MEM as Memory
    participant RET as Retrieval
    participant LLM as LM Studio

    U->>FE: Submit query
    FE->>BE: WebSocket /api/v1/solve
    BE->>MW: Rate → CORS → Metrics → Correlation → Headers → Auth
    MW->>BE: Validated request
    BE->>MEM: Recall episodes + facts + L3
    MEM-->>BE: Context (<2000 tokens)
    BE->>BE: Complexity scoring (4 signals)
    BE->>RET: Route to retrieval pipeline
    RET->>RET: Select mode (tree/hybrid/naive/combined/ARA)
    RET->>LLM: Query with context
    LLM-->>RET: Streaming response
    RET-->>BE: Compiled answer
    BE->>MEM: Store episode + extract facts
    BE-->>FE: Stream frames (agent_step, citation, complete)
    FE-->>U: Display answer

graph TD
    A[User Query] --> B{Complexity Scorer}
    B -->|Score < 0.3| C[Smart Solver]
    B -->|Score 0.3–0.7| D[Recursive Solver]
    B -->|Score > 0.7| E[Deep Research]
    B -->|Learning intent| F[Guided Learning]

    C --> C1[Analysis Loop]
    C1 --> C2[Investigate]
    C2 --> C3[Note]
    C3 --> C4{Sufficient?}
    C4 -->|No| C2
    C4 -->|Yes| C5[Solve Loop]
    C5 --> C6[Plan → Solve → Check → Format]

    D --> D1[Sequential]
    D --> D2[Mixture]
    D --> D3[Deliberation]
    D --> D4[Distillation]

    E --> E1[Decompose → Parallel Research → Report]

    F --> F1[Locate → Interactive → Chat → Summary]

graph LR
    A[Query] --> B[Recall Engine]
    B --> C[FTS5 Search<br/>0.6 Weight]
    B --> D[Recency Score<br/>0.4 Weight]
    C --> E[Ranked Results]
    D --> E
    E --> F[Context Injection<br/><2000 tokens]

    G[Response] --> H[Episode Store]
    H --> I[Fact Extraction<br/>via LLM]
    I --> J[Contradiction Check<br/>Jaccard + Negation]
    J --> K[Fact Store]
    K --> L[Background Maintenance]
    L --> M[Decay 30-day HL]
    L --> N[Compaction 90 days]
    L --> O[Progressive Crystallization]

Deep/
├── .env.example                        # Environment template (40+ vars)
├── .github/workflows/
│   └── production-readiness.yml        # CI/CD: 11 jobs (lint, test, security, Docker, SBOM)
├── docker-compose.yml                  # Development
├── docker-compose.prod.yml             # Production (read-only, caps, health checks)
├── docker-compose.blue-green.yml       # Blue-green (zero-downtime, nginx)
├── scripts/
│   ├── orchestrate.py                  # Blue-green deployment orchestrator
│   ├── deploy-blue-green.sh            # Deploy wrapper
│   ├── nginx-blue-green.conf           # Nginx config for blue-green
│   └── generate_hashed_requirements.py # Supply-chain: hashed requirements
├── backend/                            # FastAPI Python 3.14 backend
│   ├── Dockerfile                      # Python 3.12-slim, non-root, health check
│   ├── pyproject.toml                  # Project config + tool settings
│   ├── requirements.txt                # 67 pinned production packages
│   ├── requirements-dev.txt            # Dev/test packages
│   ├── app/
│   │   ├── main.py                     # Entry point (FastAPI + lifespan)
│   │   ├── config.py                   # pydantic-settings (40+ env vars)
│   │   ├── state.py                    # 11 global singletons
│   │   ├── lifespan.py                 # Startup/shutdown orchestration
│   │   ├── dependencies.py             # DI container (singleton/transient)
│   │   ├── websocket_handlers.py       # /api/v1/solve + /ws/metrics
│   │   ├── middleware/                  # 6 middleware layers
│   │   │   ├── auth.py                 # Token validation (3 methods)
│   │   │   ├── cors.py                 # Localhost origin pinning
│   │   │   ├── rate_limit.py           # SlowAPI 100/min per IP
│   │   │   ├── correlation.py          # X-Request-ID + ContextVar
│   │   │   └── headers.py             # CSP, HSTS, X-Frame, COOP
│   │   ├── routers/                    # 7 API routers
│   │   │   ├── knowledge.py            # Upload, KB CRUD, PageIndex
│   │   │   ├── system.py               # Health, config, models, VRAM, GDPR
│   │   │   ├── agent.py                # Research, questions, learning, notebooks
│   │   │   ├── retrieval.py            # 5-mode retrieval pipeline
│   │   │   ├── query.py                # HTTP Q&A (non-streaming)
│   │   │   ├── memory.py               # Recall, episodes, facts, profiles
│   │   │   └── validation_routes.py    # Self-validation framework
│   │   ├── services/                   # 38+ business logic services
│   │   │   ├── lm_studio_client.py     # LM Studio API client (httpx)
│   │   │   ├── model_manager.py        # 3-tier model lifecycle
│   │   │   ├── vram_monitor.py         # pynvml GPU pressure (4 levels)
│   │   │   ├── solve_orchestrator.py   # Dual-loop smart solver
│   │   │   ├── recursive_solver.py     # 4-pattern multi-agent
│   │   │   ├── deep_research.py        # 3-phase research pipeline
│   │   │   ├── guided_learning.py      # 4-agent adaptive tutoring
│   │   │   ├── memory_service.py       # SQLite+FTS5 (14 tables)
│   │   │   ├── knowledge_graph.py      # Entity-relation KG
│   │   │   ├── tree_search.py          # PageIndex tree reasoning
│   │   │   ├── vector_kb.py            # Local numpy vector store
│   │   │   ├── hybrid_rag.py           # RRF vector + keyword merge
│   │   │   ├── document_processor.py   # PDF/DOCX/TXT/MD extraction
│   │   │   ├── input_origin.py         # ContextVar-based request origin tracking
│   │   │   ├── security.py             # SSRF, path sanitize, auth
│   │   │   ├── secrets.py              # OS keyring integration
│   │   │   ├── metrics.py              # Prometheus + MetricsMiddleware
│   │   │   ├── task_wal.py             # Write-ahead log (crash recovery)
│   │   │   └── ... (18 more services)
│   │   ├── validation/                 # Self-validation framework
│   │   │   ├── baselines.py            # Thresholds + data classes
│   │   │   ├── config_validator.py     # Static config analysis
│   │   │   ├── coverage_tracker.py     # pytest coverage measurement
│   │   │   ├── health_checker.py       # LM Studio + Phase 10 checks
│   │   │   ├── remediation_tracker.py  # Sprint progress tracking
│   │   │   ├── runner.py               # CLI orchestrator
│   │   │   └── validation_routes.py    # REST API endpoints
│   │   └── prompts/                    # YAML prompt templates
│   ├── tests/                          # 62 test files, 556 tests
│   │   ├── conftest.py                 # Shared fixtures (real services, no mocks)
│   │   ├── test_memory_service.py      # Memory core operations
│   │   ├── test_solve_orchestrator.py  # Smart solver pipeline
│   │   ├── test_contract.py            # API contract testing
│   │   ├── test_property_based.py      # Hypothesis property tests
│   │   ├── locust_load.py              # Locust load testing
│   │   └── ... (57 more test files)
│   └── turboquant_plus/                # KV cache quantization (embedded repo)
├── frontend/                           # Next.js 16.2 TypeScript frontend
│   ├── Dockerfile                      # Multi-stage Node.js 20 build
│   ├── package.json                    # 15 deps + 14 devDeps
│   ├── components.json                 # shadcn/ui config (base-nova, Tailwind v4)
│   ├── app/
│   │   ├── layout.tsx                  # Root layout (TooltipProvider + Toaster)
│   │   ├── globals.css                 # Dark-only oklch design tokens
│   │   ├── page.tsx                    # Redirects to /chat
│   │   └── (platform)/
│   │       ├── layout.tsx              # App shell (sidebar, panels, navigation)
│   │       ├── chat/page.tsx           # Chat + Smart Solve streaming
│   │       ├── solve/page.tsx          # Recursive solver UI (decomposed, 347 lines)
│   │       ├── research/page.tsx       # Deep research pipeline
│   │       ├── guide/page.tsx          # Guided learning sessions
│   │       ├── questions/page.tsx      # Question generator
│   │       ├── notebooks/page.tsx      # Notebooks + CoWriter + IdeaGen
│   │       ├── documents/page.tsx      # Document upload + management
│   │       ├── knowledge/page.tsx      # KB viewer + PageIndex trees
│   │       ├── dashboard/page.tsx      # Real-time telemetry
│   │       ├── models/page.tsx         # Model management (decomposed, 230 lines)
│   │       └── settings/page.tsx       # System configuration
│   ├── components/                     # Reusable UI components
│   │   ├── ui/                         # 18 shadcn/ui base components
│   │   │   ├── badge.tsx              # Badge
│   │   │   ├── button.tsx             # Button
│   │   │   ├── card.tsx               # Card
│   │   │   ├── dialog.tsx             # Dialog (base-ui/react)
│   │   │   ├── input.tsx              # Input
│   │   │   ├── label.tsx              # Label
│   │   │   ├── select.tsx             # Select
│   │   │   ├── sheet.tsx              # Sheet (side drawer)
│   │   │   ├── skeleton.tsx           # Skeleton loading
│   │   │   ├── sonner.tsx             # Sonner toast (dark-only)
│   │   │   ├── tabs.tsx               # Tabs
│   │   │   ├── textarea.tsx           # Textarea
│   │   │   ├── tooltip.tsx            # Tooltip
│   │   │   └── ... (5 more)
│   │   ├── solve/                      # 12 components (9 new + 3 pre-existing)
│   │   │   ├── tree-item.tsx          # PageIndex tree item
│   │   │   ├── sources-sidebar.tsx    # Document sources panel
│   │   │   ├── solve-toolbar.tsx      # Agent selection toolbar
│   │   │   ├── solve-composer.tsx     # Composer with collaboration patterns
│   │   │   ├── suggested-prompts.tsx  # Suggested prompt chips
│   │   │   ├── streaming-pipeline.tsx # Real-time agent step streaming
│   │   │   ├── error-banner.tsx       # Error display banner
│   │   │   ├── synthesis-result.tsx   # Final synthesis with citations
│   │   │   ├── page-index-sidebar.tsx # PageIndex tree navigation
│   │   │   ├── agent-step-display.tsx # Agent step visualization
│   │   │   ├── citation-list.tsx      # Citation list
│   │   │   └── solve-input.tsx        # Input area
│   │   ├── models/                     # 4 components (decomposed from 932-line page)
│   │   │   ├── models-header.tsx      # Header with telemetry bar
│   │   │   ├── connection-rail.tsx    # Provider connection rail
│   │   │   ├── filter-toolbar.tsx     # Search + param category filters
│   │   │   └── tier-slot-card.tsx     # Generic T1/T2/T3 tier slot card
│   │   ├── shared/                     # Shared cross-page components
│   │   │   └── kb-selector.tsx        # KB selector (Chat + Sources sidebars)
│   │   ├── chat/                       # Chat components
│   │   │   ├── ChatSessionSidebar.tsx # Session list + KB selector
│   │   │   └── ChatInferenceDisplay.tsx# Inference display
│   │   ├── dashboard/                  # Telemetry visualizations
│   │   ├── documents/                  # Upload + list
│   │   └── error-boundary.tsx          # Global error boundary
│   ├── providers/                      # WebSocket + Memory contexts
│   ├── lib/                            # API clients + utilities
│   │   ├── config.ts                  # secureFetch + API_BASE_URL
│   │   ├── knowledge.ts               # KB API client
│   │   ├── estimate-vram.ts           # VRAM estimation (extracted from models)
│   │   └── utils.ts                   # cn() utility (tailwind-merge + clsx)
│   ├── types/                          # TypeScript interfaces
│   └── __tests__/                      # 8 test files, 43 tests
├── agent_instructions.md               # Autoresearch INSTRUCTIONS (human-only)
├── ACKNOWLEDGEMENTS.md                 # Research attributions + license compliance
├── ARCHITECTURE.md                     # Full architecture documentation
├── SECURITY.md                         # Security policy + vulnerability status
└── CONTRIBUTING.md                     # Contribution guide

# Clone the repository
git clone https://github.com/ShinShekai/Deep.git
cd Deep

# Copy environment template
cp .env.example .env

# Start development stack
docker compose up -d

# Open browser
# Frontend: http://localhost:3782
# Backend:  http://localhost:8001
# Metrics:  http://localhost:8001/metrics

# 1. Clone and configure
git clone https://github.com/ShinShekai/Deep.git
cd Deep
cp .env.example .env

# 2. Backend setup
cd backend
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # Linux/Mac
pip install -r requirements.txt

# 3. Frontend setup
cd ../frontend
npm install

# 4. Start LM Studio (download from lmstudio.ai)
#    - Enable local server on port 1234
#    - Load a model (Qwen3-1.7B-Q4_K_M recommended for T1)

# 5. Start backend
cd ../backend
uvicorn app.main:app --host 0.0.0.0 --port 8001

# 6. Start frontend (new terminal)
cd ../frontend
npm run dev

sudo apt-get update
sudo apt-get install -y \
  python3.12 python3.12-venv python3-pip \
  nodejs npm \
  tesseract-ocr \
  libgl1-mesa-glx libglib2.0-0 \
  poppler-utils \
  libreoffice-core

1. Install Tesseract OCR — add to PATH
2. Install Python 3.12+ from python.org
3. Install Node.js 20+ from nodejs.org
4. Install LM Studio and enable local server

# 1. Start LM Studio with a model loaded on localhost:1234

# 2. Start the backend
cd backend
uvicorn app.main:app --port 8001

# 3. Start the frontend (new terminal)
cd frontend
npm run dev

# 4. Open http://localhost:3782

# 5. Upload a document via the Documents page, then ask a question

• .env — Active configuration (gitignored). Created by copying .env.example.
• .env.example — Template with all variables and defaults.
• backend/app/config.py — Pydantic Settings class that reads from .env and environment.

DEEP generates an auth token on first startup and persists it to data/.auth_token. For API key storage, it integrates with the OS keyring:

• Windows: Windows Credential Manager
• macOS: macOS Keychain
• Linux: libsecret (GNOME Keyring / KWallet)

Keys are never written to disk in plaintext. Token rotation is available via POST /api/v1/secrets/rotate.

# Upload a PDF
curl -X POST http://localhost:8001/api/v1/knowledge/upload \
  -F "file=@document.pdf" \
  -F "kb_name=my-kb"

# Check task status
curl http://localhost:8001/api/v1/knowledge/tasks/{task_id}

# List all documents
curl http://localhost:8001/api/v1/knowledge/documents

# Get PageIndex tree
curl http://localhost:8001/api/v1/knowledge/pageindex/my-kb

# Connect via WebSocket
wscat -c "ws://localhost:8001/api/v1/solve?token=YOUR_TOKEN"

# Send a problem (bidirectional stream)
> {"query": "Explain the time complexity of quicksort", "context": "..."}

# Start a research task
curl -X POST http://localhost:8001/api/v1/research \
  -H "Content-Type: application/json" \
  -d '{"topic": "Impact of KV cache compression on LLM throughput"}'

# Poll results
curl http://localhost:8001/api/v1/research/{task_id}

# Start a guided learning session
curl -X POST http://localhost:8001/api/v1/guide/start \
  -H "Content-Type: application/json" \
  -d '{"topic": "Transformer attention mechanisms", "kb_name": "ml-notes"}'

# Generate questions from a document
curl -X POST http://localhost:8001/api/v1/questions/generate \
  -H "Content-Type: application/json" \
  -d '{"doc_id": "doc_abc123", "count": 10, "difficulty": "medium"}'

# Create a notebook
curl -X POST http://localhost:8001/api/v1/notebooks \
  -H "Content-Type: application/json" \
  -d '{"title": "Research Notes", "sources": ["doc_1", "doc_2"]}'

# Co-writer edit
curl -X POST http://localhost:8001/api/v1/cowriter/edit \
  -H "Content-Type: application/json" \
  -d '{"text": "Draft content...", "instruction": "Make it more technical"}'

# Idea generation
curl -X POST http://localhost:8001/api/v1/ideagen/generate \
  -H "Content-Type: application/json" \
  -d '{"topic": "novel approaches to KV cache compression", "count": 5}'

# Recall memories for a device
curl -X POST http://localhost:8001/api/v1/memory/recall \
  -H "Content-Type: application/json" \
  -d '{"device_id": "uuid-here", "query": "What did I learn about transformers?"}'

# Get memory stats
curl http://localhost:8001/api/v1/memory/stats/{device_id}

# Get user profile
curl http://localhost:8001/api/v1/memory/profile/{device_id}

# Trigger decay manually
curl -X POST http://localhost:8001/api/v1/memory/decay

# Search memory
curl -X POST http://localhost:8001/api/v1/memory/search \
  -H "Content-Type: application/json" \
  -d '{"device_id": "uuid-here", "query": "attention mechanism"}'

# List available models
curl http://localhost:8001/api/v1/models

# Discover models from LM Studio
curl http://localhost:8001/api/v1/models/discover

# Load a specific model
curl -X POST http://localhost:8001/api/v1/models/{model_id}/load

# Unload a model
curl -X POST http://localhost:8001/api/v1/models/{model_id}/unload

# Check VRAM status
curl http://localhost:8001/api/v1/vram/status

# Create a backup
curl -X POST http://localhost:8001/api/v1/backup

# List backups
curl http://localhost:8001/api/v1/backup

# Restore a backup
curl -X POST http://localhost:8001/api/v1/backup/{name}/restore

# Delete all user data (GDPR)
curl -X DELETE http://localhost:8001/api/v1/memory/episodes/{device_id}

graph TB
    subgraph Entry["Query Entry"]
        Q[User Query] --> CS[Complexity Scorer]
    end

    subgraph Scoring["4-Signal Scoring"]
        CS --> S1[Query Complexity 0.35]
        CS --> S2[Document Size 0.25]
        CS --> S3[Chunk Count 0.15]
        CS --> S4[VRAM Available 0.25]
    end

    subgraph Routing["Agent Selection"]
        S1 & S2 & S3 & S4 --> R{Router}
        R -->|Simple| SS[Smart Solver]
        R -->|Complex| RS[Recursive Solver]
        R -->|Research| DR[Deep Research]
        R -->|Learning| GL[Guided Learning]
        R -->|Questions| QG[Question Generator]
        R -->|Creative| CC[Content Creation]
    end

    subgraph SmartSolver["Smart Solver — Dual Loop"]
        SS --> A1[Analysis Loop]
        A1 --> A2[🔍 Investigate]
        A2 --> A3[📝 Note]
        A3 --> A4{Sufficient?}
        A4 -->|No| A2
        A4 -->|Yes| S5[Solve Loop]
        S5 --> S6[📋 Plan]
        S6 --> S7[⚡ Solve]
        S7 --> S8[✅ Check]
        S8 --> S9[📄 Format]
    end

    subgraph Recursive["Recursive Solver — 4 Patterns"]
        RS --> P1[Sequential]
        RS --> P2[Mixture]
        RS --> P3[Deliberation]
        RS --> P4[Distillation]
    end

The Smart Solver uses a two-phase approach for complex problem-solving:

Analysis Loop — Gathers information before solving:

• Investigate Agent: Searches the knowledge base, retrieves relevant chunks, examines document structure
• Note Agent: Summarizes findings, extracts key facts, identifies gaps in understanding

The loop repeats until sufficient context is gathered (configurable iteration limit).

Solve Loop — Produces the answer:

• Plan Agent: Outlines the solution strategy, identifies required steps
• Solve Agent: Executes the plan, generates the response
• Check Agent: Validates the response against the original query, checks for completeness
• Format Agent: Structures the final output (markdown, code blocks, citations)

Implements 4 collaboration patterns from the RecursiveMAS framework:

3-phase pipeline for comprehensive research tasks:

1. Decompose Phase: Breaks the research topic into sub-questions with dependencies
2. Parallel Research Phase: Sub-questions researched concurrently across the knowledge base
3. Report Compilation: Results synthesized into a structured report with source attribution

4-agent adaptive tutoring system:

2-agent pipeline for assessment creation:

• Generator Agent: Produces questions of varying difficulty from source material
• Validator Agent: Checks question quality, accuracy, and appropriate difficulty level

Three creative tools:

• Notebook: Structured document combining source material with AI-generated sections
• CoWriter: Collaborative writing with iterative refinement via instruction-guided edits
• IdeaGen: Brainstorming engine that generates novel ideas from topic seeds

Converts documents into a 4-layer knowledge structure:

erDiagram
    EPISODES {
        uuid id PK
        uuid device_id FK
        text content
        text context
        float importance
        timestamp created_at
        timestamp last_accessed
        int access_count
    }

    FACTS {
        uuid id PK
        uuid device_id FK
        text content
        float confidence
        text source_episode_id
        timestamp created_at
        timestamp last_validated
    }

    FACT_RELATIONSHIPS {
        uuid id PK
        uuid fact_a_id FK
        uuid fact_b_id FK
        text relationship_type
    }

    USER_PROFILES {
        uuid device_id PK
        jsonb preferences
        jsonb learning_style
        jsonb interaction_history
        timestamp updated_at
    }

    AGENT_OUTCOMES {
        uuid id PK
        uuid device_id FK
        text agent_type
        jsonb input
        jsonb output
        float success_score
        timestamp created_at
    }

    AGENT_STRATEGIES {
        uuid id PK
        text agent_type
        jsonb strategy
        float effectiveness
        int usage_count
        timestamp last_used
    }

    PROJECT_PROFILES {
        uuid id PK
        text project_name
        jsonb metadata
        jsonb document_stats
        timestamp updated_at
    }

    MEMORY_USAGE {
        uuid id PK
        uuid device_id FK
        text operation
        int tokens_used
        float latency_ms
        timestamp created_at
    }

    EPISODES ||--o{ FACT_RELATIONSHIPS : "generates"
    FACTS ||--o{ FACT_RELATIONSHIPS : "links"
    EPISODES }o--|| USER_PROFILES : "belongs_to"
    FACTS }o--|| USER_PROFILES : "belongs_to"
    AGENT_OUTCOMES }o--|| USER_PROFILES : "belongs_to"

Episodes capture interactions, decisions, and observations:

• Storage: Each episode includes content, context, importance score, and timestamp
• Retrieval Scoring: 0.6 × FTS5_full_text_rank + 0.4 × recency_decay
• Recency Decay: Exponential decay based on time since last access
• Access Tracking: Every recall increments access count and updates last_accessed

Facts are extracted from episodes via the local LLM:

• Extraction: Background LLM call extracts structured facts from episode content
• Confidence Scoring: Each fact gets a confidence score (0.0–1.0)
• Contradiction Detection: Jaccard similarity + negation analysis identifies conflicting facts
• Validation: Facts can be re-validated against new episodes

Auto-updated profiles tracking device-level preferences:

• Learning style preferences
• Interaction patterns
• Topic interests (inferred from query history)
• Response format preferences

Strategies learned from agent outcomes:

• Tracks which approaches work for which problem types
• Effectiveness scores updated after each agent run
• Strategies shared across users (global, not device-scoped)

Background tasks keep memory healthy:

• Decay: Hourly, 30-day half-life reduces importance of old, unreferenced memories
• Compaction: Merges similar episodes older than 90 days
• FTS5 Reindex: Periodic reindexing for optimal search performance
• Usage Tracking: Logs all memory operations for observability

• Style: Base-Nova — @base-ui/react primitives (NOT Radix UI)
• Configuration: frontend/components.json (base-nova, Tailwind v4, oklch)
• Components installed: badge, button, card, dialog, input, label, popover, scroll-area, select, separator, sheet, skeleton, sonner, switch, tabs, textarea, tooltip, accordion
• Theme: Dark-only oklch design tokens in app/globals.css
• Utility: cn() from lib/utils.ts (tailwind-merge + clsx)

• Website: sonner.emilkowal.ski
• License: MIT
• Integration: Unified toast system across all 8 pages. toast() from sonner, <Toaster /> in root layout.
• Pages migrated: chat, solve, research, cowriter, knowledge, guide, models, documents

• Website: tailwindcss.com
• License: MIT
• Integration: Utility-first CSS with oklch color system. No tailwind.config.ts — uses CSS-first configuration.
• PostCSS: @tailwindcss/postcss v4

• Website: lucide.dev
• License: ISC
• Integration: Icon library for all UI components. 1000+ consistent icons.

• Website: lmstudio.ai
• License: Proprietary (free for personal and commercial use)
• Integration: Primary local inference backend via OpenAI-compatible API. Chat completions, embeddings, and model management. DEEP uses stream_chat() API v1 endpoints.

• Website: ollama.ai
• License: MIT
• Integration: Alternative local inference backend. Same OpenAI-compatible API format.

• Repository: github.com/ggerganov/llama.cpp
• License: MIT
• Integration: Backend inference engine. TurboQuant+ has active PR preparation for upstream contribution.

Two OCR backends supported:

• pytesseract (default): Tesseract-based, requires system installation
• easyocr: GPU-accelerated, no system dependency, slower cold start

Metrics endpoint at GET /metrics exposes:

• Request counts and latencies (per endpoint)
• VRAM usage and pressure level
• Active model count per tier
• Memory system operations
• Error rates

Optional distributed tracing (disabled by default):

• Set OTEL_EXPORTER_OTLP_ENDPOINT to enable
• Graceful no-op when not configured
• Traces cover: query routing, retrieval, LLM calls, memory operations

# Backend
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
pip install pytest pytest-asyncio pytest-cov

# Frontend
cd frontend
npm install
npm install -D vitest @testing-library/react

• Services: Business logic in backend/app/services/. Each service is a module with async functions.
• Routers: HTTP endpoints in backend/app/routers/. Thin wrappers that delegate to services.
• State: Module-level singletons in state.py. Accessed via from app.state import ....
• Config: Pydantic Settings in config.py. All env vars loaded here.
• Components: React components in frontend/components/. Reusable, typed with TypeScript.
• Providers: React context providers in frontend/providers/. WebSocket and Memory.

1. Create backend/app/services/my_service.py
2. Define async functions (not classes) for each operation
3. Import state from app.state for shared singletons
4. Add router in backend/app/routers/my_router.py
5. Register router in backend/app/main.py
6. Write tests in backend/tests/test_my_service.py

1. Add route function in the appropriate router file
2. Use dependency injection for services
3. Add request/response models in backend/app/validation/
4. Write integration test in backend/tests/
5. Update this README with the new endpoint

Backend Dockerfile (backend/Dockerfile):

• Base: python:3.12-slim
• Installs system deps (tesseract, poppler)
• Copies requirements, installs Python packages
• Runs as non-root user
• Healthcheck via /api/v1/health

Frontend Dockerfile (frontend/Dockerfile):

• Base: node:22-slim
• Multi-stage build (deps → build → production)
• Output: standalone Next.js
• Runs as non-root user

9-job GitHub Actions pipeline:

Zero-downtime deployment using nginx:

1. Deploy new version to the inactive stack (blue or green)
2. Run healthchecks against the new stack
3. Switch nginx upstream to the new stack
4. Drain old stack connections
5. Shut down old stack

# Deploy blue-green
./scripts/deploy-blue-green.sh

# Nginx config
cat scripts/nginx-blue-green.conf

cd backend

# Run all tests
pytest

# With coverage
pytest --cov=app --cov-report=html

# Run specific test file
pytest tests/test_memory_service.py

# Verbose output
pytest -v

61 test files covering:

• Service unit tests (memory, retrieval, agents)
• Integration tests (API endpoints)
• Security tests (SSRF, path traversal, auth)
• Performance tests (memory latency targets)

cd frontend

# Run all tests
npm test

# Watch mode
npm test -- --watch

# Coverage
npm test -- --coverage

8 test files covering:

• Component rendering
• Provider behavior
• API client integration

# Run Locust load test
cd tests
locust -f locustfile.py --host=http://localhost:8001

# Headless mode (50 users, 5 min)
locust -f locustfile.py --host=http://localhost:8001 \
  --headless -u 50 -r 10 --run-time 5m

# Python dependencies
pip-audit

# Node.js dependencies
npm audit

# Container scanning
trivy image deep-backend:latest
trivy image deep-frontend:latest

DEEP monitors VRAM in real-time via pynvml and responds to 4 pressure levels:

KV cache quantization reduces VRAM usage for long-context inference:

• PolarQuant: Random rotation + Beta-distributed coordinates + Lloyd-Max scalar quantization
• Bit widths: 3-bit (aggressive) or 4-bit (balanced)
• Benefit: 40–50% VRAM reduction on KV cache with minimal quality loss
• Integration: Applied automatically when TURBOQUANT_ENABLED=True

• LRU Model Cache: Recently used models kept resident based on tier TTL
• Embedding Cache: Vector embeddings cached to avoid recomputation
• Query Cache: Repeated queries served from cache (configurable TTL)

3-tier semaphore system prevents VRAM overcommit:

• T1 Semaphore: 4 concurrent requests (always available)
• T2 Semaphore: 2 concurrent requests (after model is loaded)
• T3 Semaphore: 1 concurrent request (loaded on-demand, evicted after TTL)

3 methods supported (checked in order):

1. Header: X-DEEP-API-KEY: <token>
2. Bearer: Authorization: Bearer <token>
3. Query: ?token=<token>

Token is auto-generated on first startup, persisted to data/.auth_token. Constant-time comparison via hmac.compare_digest prevents timing attacks.

All outgoing HTTP requests are validated:

• DNS resolution checked before connection
• Cloud metadata endpoints blocked (169.254.169.254, fd00:ec2::254)
• Private IP ranges blocked (10.x, 172.16-31.x, 192.168.x, 127.x)
• Redirects followed with same validation

File operations use safe path resolution:

• safe_name(): Strips path separators and special characters from filenames
• safe_doc_id(): Validates document ID format (alphanumeric + hyphens only)
• resolve_within(): Ensures resolved path stays within allowed directory

SlowAPI integration with configurable limits:

• Default: 100 requests per minute per IP
• Configurable via UDIP_RATE_LIMIT
• Returns 429 with Retry-After header

All responses include:

• OS keyring integration (Windows Credential Manager / macOS Keychain / libsecret)
• Auth token auto-generated and persisted to data/.auth_token
• Token rotation via POST /api/v1/secrets/rotate
• No secrets in logs or error messages

Error messages are sanitized before response:

• Local file paths stripped (C:\Users\... → [REDACTED])
• Stack traces logged internally only
• Database connection strings redacted

Security events logged:

• Authentication successes and failures
• Rate limit violations
• SSRF blocked attempts
• Path traversal attempts
• Token rotations
• Backup and restore operations

Q: Does DEEP require an internet connection? A: No. DEEP is fully local-first. All inference, storage, and memory operations happen on your machine. Cloud providers are optional fallbacks.

Q: What GPU do I need? A: Minimum 6 GB VRAM. For the best experience, 12+ GB is recommended. TurboQuant KV cache quantization extends effective capacity by 40-50%.

Q: Can I use DEEP with Ollama instead of LM Studio? A: Yes. DEEP uses the OpenAI-compatible API format. Configure LLM_HOST to point to your Ollama endpoint.

Q: How is my data stored? A: All data is stored locally in SQLite (memory) and the file system (documents). No data is sent externally unless you explicitly configure a cloud provider.

Q: Can multiple users share a DEEP instance? A: DEEP uses device-scoped isolation (UUID v4 per device). Each device gets its own memory, episodes, and facts. Agent strategies are shared globally.

Q: What document formats are supported? A: PDF, DOCX, TXT, and MD. OCR support extends this to scanned PDFs and images via pytesseract or easyocr.

Q: How does the memory system differ from chat history? A: Chat history is a flat log. DEEP's memory extracts facts, detects contradictions, tracks importance, and decays old information. It's a structured knowledge base, not just a log.

Q: Can I use DEEP for code analysis? A: Yes. Upload codebases as documents. The PageIndex tree creates a hierarchical index, and agents can reason over code structure.

Q: How accurate is the fact extraction? A: Fact extraction uses the local LLM with a confidence threshold (default 0.2). Contradiction detection prevents conflicting facts. You can manually review and delete facts.

Q: Is there a web UI? A: Yes. Next.js frontend at http://localhost:3782 with 12 pages covering chat, agents, documents, knowledge, models, and settings.

Q: Can I run DEEP on a Mac? A: Yes. DEEP runs on macOS with Apple Silicon. LM Studio supports Metal acceleration. TurboQuant has MLX/Swift community collaboration for Apple Silicon optimization.

Q: How do I update DEEP? A: Pull the latest code and rebuild: git pull && docker compose up -d --build. For manual installs, pip install -r requirements.txt && npm install.

Q: What happens if the memory system fails? A: DEEP degrades gracefully. Memory operations return empty results, never crash the pipeline. The system continues to function without memory.

Q: Can I export my data? A: Yes. Backups are available via POST /api/v1/backup. The memory database is a standard SQLite file at data/memory/deep_memory.db.

Q: How do I contribute? A: Fork the repo, create a feature branch, make changes, run tests (pytest and npm test), and submit a PR. See Contributing section below.

Q: Is DEEP production-ready? A: DEEP includes production Docker configurations with hardened containers, resource limits, healthchecks, and blue-green zero-downtime deployment. The CI/CD pipeline includes security scanning and load testing.

Q: Can I customize the agent behavior? A: Agent strategies are stored in the agent_strategies table and evolve based on outcomes. You can also configure complexity scoring weights and retrieval modes.

Q: Does DEEP support multimodal input? A: OCR support enables image text extraction. For full multimodal support, configure a vision-capable model via a cloud provider.

Q: How do I debug issues? A: Set UDIP_LOG_LEVEL=DEBUG and UDIP_LOG_FORMAT=json in .env. Check structured logs with correlation IDs. The /api/v1/health endpoint reports system status.

DEEP builds upon the work of open-source projects and academic research. See ACKNOWLEDGEMENTS.md for full attribution, license compliance, and details on what was adopted from each foundation.

Unique innovations:

• TurboQuant KV cache quantization: 3-4 bit compression extending effective VRAM by 40-50%
• Complexity-scored routing: Weighted 4-signal scoring automatically selects the right agent and model tier
• Device-scoped memory: UUID v4 isolation ensures no cross-device data leakage
• Self-validating pipeline: Built-in validation framework with comprehensive test coverage
• Blue-green deployment: Zero-downtime updates for production self-hosting
• Component decomposition: Solve page 65% reduction, Models page 75% reduction via extraction
• Shared KB selector: Single component reused across Chat and Sources sidebars
• Collaboration pattern explanations: In-app UI explaining Sequential, Mixture, Deliberation, Distillation

• Unified Document Intelligence Pipeline — 12 pages, 38+ services, 556 backend tests
• 3-tier model management with VRAM-aware loading and eviction
• Dual-loop smart solver + recursive 4-pattern multi-agent solver
• 14-table persistent memory with fact extraction and contradiction detection
• Production Docker with read-only containers, capability dropping, blue-green deployment
• 11 inference providers (local + cloud) with auto-discovery
• TurboQuant KV cache quantization (3-4 bit)
• ARA 4-layer knowledge compilation
• CI/CD pipeline with 11 jobs (lint, test, security, Docker, SBOM)
• UI/UX overhaul — shadcn/ui design system, component decomposition, Sonner toasts
• Solve page decomposition (987→347 lines, 9 components)
• Models page decomposition (932→230 lines, 4 components + 1 utility)
• Shared KB selector component
• Collaboration pattern explanations in-app
• Skeleton loading states for knowledge and documents
• Autoresearch patterns (reference documentation only)
• Research acknowledgements and license compliance

• Multi-document ARA knowledge graph visualization
• Voice input and speech-to-text integration
• Plugin system for custom agent definitions
• Collaborative knowledge bases (multi-device shared KB)
• Automatic model recommendation based on query patterns
• Export memory to standard formats (JSON-LD, RDF)
• Native Apple Silicon (MLX) backend integration
• Web search integration for grounding
• Mobile companion app for memory recall on-the-go

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (pytest and npm test)
5. Run linters (ruff check and npm run lint)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

DEEP License — Personal Use Only. See LICENSE for full text.

Commercial use requires a separate license. Contact via GitHub.

DEEP incorporates code and algorithms from projects under the following licenses. All requirements are satisfied:

DEEP's use of research foundations is for attribution and acknowledgment purposes. No proprietary code from these projects is redistributed. DEEP's original code is licensed under the DEEP License (personal use only).

Made with ❤️ by ShinShekai for all the local AI enthusiasts.