Architecture

GNO is a local knowledge indexing and search system built on SQLite.

System Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                                   User                                       │
│                       (developer, researcher, writer)                        │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                    ┌─────────────────â”ŧ─────────────────┐
                    │                 │                 │
                    â–ŧ                 â–ŧ                 â–ŧ
              ┌──────────┐     ┌──────────────┐   ┌───────────┐
              │   CLI    │     │  MCP Server  │   │  AI Agent │
              │  (gno)   │     │  (gno mcp)   │   │  (Claude) │
              └──────────┘     └──────────────┘   └───────────┘
                    │                 │                 │
                    └─────────────────â”ŧ─────────────────┘
                                      │
                                      â–ŧ
              ┌───────────────────────────────────────────────────────────────┐
              │                      GNO Core                                  │
              │  ┌──────────────┐  ┌────────────┐  ┌────────────────────────┐ │
              │  │  Ingestion   │  │  Pipeline  │  │   LLM Layer            │ │
              │  │  (walker,    │  │  (search,  │  │   (embed, rerank, gen) │ │
              │  │   chunker)   │  │   fusion)  │  │   (node-llama-cpp)     │ │
              │  └──────────────┘  └────────────┘  └────────────────────────┘ │
              └───────────────────────────────────────────────────────────────┘
                                      │
                                      â–ŧ
              ┌───────────────────────────────────────────────────────────────┐
              │                    Storage Layer                               │
              │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐ │
              │  │   SQLite     │  │    FTS5      │  │    sqlite-vec        │ │
              │  │  (documents, │  │   (BM25)     │  │   (vector KNN)       │ │
              │  │   chunks)    │  │              │  │   (optional)         │ │
              │  └──────────────┘  └──────────────┘  └──────────────────────┘ │
              └───────────────────────────────────────────────────────────────┘
                                      │
                                      â–ŧ
              ┌───────────────────────────────────────────────────────────────┐
              │                    File System                                 │
              │          ~/notes    ~/work/docs    ~/papers                    │
              │           (collections configured by user)                     │
              └───────────────────────────────────────────────────────────────┘

Data Flow

Ingestion Pipeline

File on disk
    │
    â–ŧ Walker (glob patterns, exclude lists)
    │
    â–ŧ Hash source content (SHA-256 → sourceHash)
    │
    ├─[ sourceHash unchanged ]─â–ē Skip (file not modified)
    │
    â–ŧ Converter (MIME detection → Markdown)
    │
    â–ŧ Canonicalize (NFC, normalize whitespace)
    │
    â–ŧ Hash canonical markdown (→ mirrorHash)
    │
    ├─[ mirrorHash exists ]─â–ē Reuse content (deduplication)
    │
    â–ŧ Chunker (~800 tokens, 15% overlap)
    │
    â–ŧ Store (SQLite: documents, content, chunks, FTS)
    │
    â–ŧ [Optional] Embed chunks (llama.cpp → vectors)

Search Pipeline

User query
    │
    â–ŧ Detect query language (franc, 30+ languages)
    │
    ├─[ BM25-only mode ]─â–ē searchBm25 only
    │
    â–ŧ BM25 Search (FTS5 full-text)
    │
    â–ŧ Embed query (llama.cpp)
    │
    â–ŧ Vector Search (sqlite-vec KNN)
    │
    â–ŧ [Optional] Query expansion (LLM variants)
    │
    â–ŧ RRF Fusion (reciprocal rank, k=60)
    │
    â–ŧ [Optional] Rerank (cross-encoder)
    │
    â–ŧ Results (sorted by blended score)

Key Components

Storage

Table Purpose
documents Source file tracking (path, hash, docid)
content Canonical markdown by mirrorHash
content_chunks Chunked text (800 tokens each)
content_fts FTS5 virtual table for BM25
content_vectors Embeddings (optional)

Content Addressing

GNO uses content-addressed storage:

  • sourceHash = SHA-256 of original file content
  • mirrorHash = SHA-256 of canonical markdown

Multiple source files with identical canonical content share the same chunks and vectors. This deduplicates storage and speeds up indexing.

LLM Models

All models run locally via node-llama-cpp:

Model Purpose Default
Embed Generate vector embeddings bge-m3-Q4 (1024 dims)
Rerank Cross-encoder scoring bge-reranker-v2-m3-Q4
Gen Answer generation Qwen3-1.7B-Q4

Models are GGUF-quantized for efficiency. First use triggers automatic download.

Search Modes

Mode Description
BM25 Keyword matching via FTS5
Vector Semantic similarity via embeddings
Hybrid BM25 + vector with RRF fusion
Reranked Hybrid + cross-encoder reordering

Graceful Degradation

GNO works with reduced capabilities when components are missing:

Component If Missing Behavior
sqlite-vec Extension not loaded BM25 search only
Embed model Not downloaded Vector search disabled
Rerank model Not downloaded Skip reranking
Gen model Not downloaded --answer disabled

Run gno doctor to check component status.

File Locations

Linux (XDG standard): | Location | Purpose | |———-|———| | ~/.config/gno/index.yml | Configuration | | ~/.local/share/gno/index-default.sqlite | Database | | ~/.cache/gno/models/ | Model cache |

macOS: | Location | Purpose | |———-|———| | ~/Library/Application Support/gno/config/index.yml | Configuration | | ~/Library/Application Support/gno/data/index-default.sqlite | Database | | ~/Library/Caches/gno/models/ | Model cache |

Run gno doctor to see resolved paths.

Technical Notes

For implementation details, see: