Cognix Overview

Cognix is a local-first personal knowledge system. It ingests raw files from an immutable vault, extracts and chunks text, builds a hybrid semantic index, and answers questions through a lightweight web UI. Answers are grounded in retrieved evidence with inline citations and a confidence score.

The stack is intentionally understandable: FastAPI backend, React + TypeScript frontend, SQLite for operational state, ChromaDB for vector search, and a retrieval pipeline you can follow line by line.

What Cognix Does

1. Ingest — scans data/raw/, parses every file type, chunks text into 450-word overlapping windows, embeds each chunk, stores everything in SQLite + ChromaDB
2. Retrieve — hybrid search combining filename matching, keyword matching, SQLite vector cosine search, and ChromaDB semantic search, merged with Reciprocal Rank Fusion
3. Answer — synthesizes a grounded response from the top retrieved chunks, with a confidence score and source list
4. Audit — intelligence pipeline detects knowledge gaps, contradictions, and stale content; writes nightly briefings to wiki/_intelligence/

Supported File Types

Ingest skips node_modules, __pycache__, .git, dist, build, binary files, and minified assets automatically.

Embedding Backends

Configurable via COGNIX_LOCAL_EMBEDDING_BACKEND:

Model Providers

Cognix routes synthesis calls through a provider cascade (skips any with blocked status):

Keys are read from environment variables first (OPENAI_API_KEY, ANTHROPIC_API_KEY), then from SQLite provider_settings.

Answer Styles

Quick Start

scripts/start_cognix.sh
# Opens http://127.0.0.1:5173/

Project Layout

backend/
  app/
    main.py              FastAPI app + router mounts
    db/schema.sql        SQLite v1 schema
    db/schema_v2.py      V2 migration runner
    services/
      retrieval.py       Hybrid retrieval pipeline
      llm.py             Answer synthesis + provider cascade
      intelligence/      Gap, contradiction, staleness detectors
      outputs.py         Draft output management
      compiler.py        Source summary wiki generation
    parsers.py           File type parsers (v4)
    chunking.py          Sliding window chunker
    embeddings.py        Hash + sentence-transformers + OpenAI
    providers.py         Provider settings + test
    config.py            All COGNIX_* env vars
frontend/
  src/
    pages/
      Ask.tsx            Q&A interface
      Ingest.tsx         Ingest runner + file/job tables
      Outputs.tsx        Draft output management
      Intelligence.tsx   Findings, gaps, contradictions, concept graph
      Health.tsx         Health score + findings
      Settings.tsx       Profile, providers, background services
config/                  Source, model, budget, priority YAML config
data/raw/               Immutable source vault
data/processed/         Extracted text cache
data/chroma/            ChromaDB vector store
wiki/
  sources/              Per-file summaries (auto-generated)
  outputs/analysis/     Saved Q&A drafts
  _health/              Health reports
  _intelligence/        Nightly briefings
  concepts/             Compiled concept pages

Background Services

Three services, all off by default and controllable from the Settings UI:

Next Steps

• Architecture — retrieval pipeline, database schema, intelligence system, and configuration reference