flowchart TD
    Query["User / Agent Query (e.g. 'IOCTL 0x800021DC' or 'SMBIOS Type 17')"] --> Stage1["1. EXACT IDENTIFIER MATCH (+2.5 Boost)\nDirect match on Canonical Name, Aliases, IOCTL Hex, RVAs"]
    Query --> Stage2["2. LEXICAL FULL-TEXT SEARCH\nPostgreSQL GIN tsvector + ts_rank_cd"]
    Query --> Stage3["3. VECTOR COSINE SIMILARITY\npgvector <=> HNSW Index (384-dim Embeddings)"]
    
    Stage1 --> Fuse["4. RECIPROCAL RANK FUSION (RRF)\nRRF Score = 1.0 / (k + rank) + Boost"]
    Stage2 --> Fuse
    Stage3 --> Fuse
    
    Fuse --> Stage4["5. KNOWLEDGE GRAPH TRAVERSAL\nExtracts: CONTAINS, CALLS, USES, MAPS_TO_WMI, HAS_PROPERTY"]
    Stage4 --> Stage5["6. VERBATIM PROVENANCE INJECTION\nLine-accurate citations, heading paths, and code excerpts"]
    Stage5 --> Output["Token-Dense Entity Card + Context Chunks"]

docker run -d \
  --name archon-postgres \
  -e POSTGRES_DB=technical_kb \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  pgvector/pgvector:pg17

git clone https://github.com/DeFexNN/archon-kb.git
cd archon-kb
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
# source .venv/bin/activate

pip install -r requirements.txt

# Using psql:
psql -h localhost -U postgres -d technical_kb -f migrations/init.sql

# Ingest single markdown document:
python scripts/import_file.py examples/sample_hardware_kernel_doc.md

# Or ingest an entire directory recursively:
python scripts/import_directory.py path/to/your/research_notes/

python scripts/validate_integrity.py

{
  "mcpServers": {
    "archon-kb": {
      "command": "python",
      "args": [
        "C:\\Archon-KB\\src\\mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "C:\\Archon-KB",
        "PGHOST": "localhost",
        "PGPORT": "5432",
        "PGDATABASE": "technical_kb",
        "PGUSER": "postgres",
        "PGPASSWORD": "your_password"
      }
    }
  }
}

{
  "mcpServers": {
    "archon-kb": {
      "command": "C:\\Users\\<USER>\\AppData\\Local\\Programs\\Python\\Python313\\python.exe",
      "args": [
        "C:\\Archon-KB\\src\\mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "C:\\Archon-KB"
      }
    }
  }
}

======================================================================
ARCHON-KB INTEGRITY & HEALTH AUDIT REPORT
======================================================================
Total Documents:                     47
Total Structural Chunks:          5,260
Total Extracted Entities:           898
Total Entity Properties:            430
Total Retrieval Methods:            210
Total Knowledge Relationships:      200
Total Evidence Citations:         4,120

Vector Embeddings Health:
  * Entities with Vector:           898 / 898 (100.0%)
  * Chunks with Vector:           5,260 / 5,260 (100.0%)

Provenance Integrity:
  * Entities with Direct Evidence:  898 / 898 (100.0%)

Total Database Disk Footprint:    89 MB
======================================================================

archon-kb/
├── config/
│   └── mcp_clients_example.json   # Ready-to-use client JSON configurations
├── docs/                          # Placeholder for your local markdown files
├── examples/
│   └── sample_hardware_kernel_doc.md # Reference technical specification
├── migrations/
│   └── init.sql                   # PostgreSQL 17 DDL + pgvector schema
├── scripts/
│   ├── import_file.py             # Single document ingestion engine
│   ├── import_directory.py        # Recursive bulk directory ingester
│   ├── reindex.py                 # Full database re-chunker & re-embedder
│   ├── test_search.py             # Terminal CLI search testing utility
│   └── validate_integrity.py      # Health & zero data loss auditor
├── src/
│   ├── config.py                  # Centralized configuration loader
│   ├── mcp_server.py              # FastMCP server with stdio/sse transports
│   ├── api/
│   │   ├── kb_service.py          # High-level Knowledge Base API
│   │   └── llm_tools.py           # Token-dense LLM search interface
│   ├── embeddings/
│   │   └── embedding_engine.py    # Multi-backend vectorizer (Hash/ST/FastEmbed)
│   ├── extraction/
│   │   └── entity_extractor.py    # Technical regex & graph link extractor
│   ├── normalization/
│   │   └── normalizer.py          # Entity deduplication & conflict tracker
│   ├── parser/
│   │   └── markdown_parser.py     # AST heading, table & code block parser
│   └── retrieval/
│       └── hybrid_search.py       # 5-Stage RRF Hybrid Retrieval Engine
├── tests/
│   ├── test_extractor_fixtures.py # Entity extraction test cases
│   ├── test_parser_fixtures.py    # Structural parsing test cases
│   └── test_retrieval_rrf.py      # Reciprocal Rank Fusion test cases
├── .env.example
├── .gitignore
├── LICENSE
├── pyproject.toml
├── README.md
└── requirements.txt