How do I use Archon-KB?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Archon-KB What's the SMBIOS Type 17 memory serial format?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Archon-KB

by DeFexNN

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

🏛️ ARCHON-KB

High-Performance Technical Knowledge Base & MCP Server

Deterministic Graph-RAG • PostgreSQL 17 • pgvector (HNSW) • Reciprocal Rank Fusion • Systems & Reverse Engineering

Python 3.10+ PostgreSQL 17 pgvector HNSW MCP Protocol License: MIT

⚡ Overview

Archon-KB is an industrial-grade, deterministic Technical Knowledge Base and Model Context Protocol (MCP) server engineered specifically for systems programming, kernel architecture, hardware specifications, and reverse engineering research.

Naive RAG pipelines fail in low-level engineering domains: they slice code blocks across arbitrary token counts, butcher SMBIOS structs, drop IOCTL codes, and hallucinate entity links. Archon-KB solves this at the database engine layer by combining:

Hierarchy-Preserving AST Markdown Parser: Retains full heading ancestry, code blocks, tables, and exact line-level provenance with zero data loss.
Domain-Specific Entity Graph Extractor: Automatically identifies IOCTLs, WMI classes, NT native APIs, SMBIOS table types, drivers, devices, and RVAs.
5-Stage Hybrid Retrieval Pipeline: Exact Match + GIN Full-Text Lexical Search + pgvector HNSW Cosine Similarity fused via Reciprocal Rank Fusion (RRF).
Token-Dense FastMCP Server: Native MCP integration with AI agents (Claude Desktop, Antigravity, Cursor, Windsurf).

Related MCP server: Qurio MCP Server

🔬 Architecture & Retrieval Pipeline

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"]

🌟 Key Capabilities

1. Zero-Hallucination Technical Entity Extraction

Extracts and indexes domain entities out-of-the-box:

Kernel IOCTLs & FSCTLs: Standard codes and raw hex values (e.g. 0x2D1400, 0x800021DC).
Firmware & SMBIOS: Complete SMBIOS specification tables (Types 0 to 127: BIOS, BaseBoard, Processor, OEM Strings, Memory Serials).
WMI Classes & Namespaces: root\cimv2, root\wmi, properties, and PowerShell CIM invocation methods.
Native & Win32 APIs: Nt*, Zw*, Rtl*, Ob*, Io*, DeviceIoControl, GetSystemFirmwareTable.
Drivers & Device Objects: System drivers (.sys), kernel devices (\Device\...).
Disassembly RVAs: Relative virtual addresses for binary inspection.

2. Multi-Provider Embedding Engine

Local Deterministic Hasher: Built-in 384-dimensional unit vectorizer with zero external dependencies.
FastEmbed / Sentence-Transformers: Plug-and-play support for BAAI/bge-small-en-v1.5 or any HuggingFace model.
Configurable Vector Dimensions: Fully adjustable via EMBEDDING_DIM environment variable.

3. Strict Provenance (Line-Accurate Auditing)

Every entity and assertion links back to its exact document:

Source file path & SHA256 hash
Full heading breadcrumb path
Exact line numbers (start_line to end_line)
Verbatim source quote snippet

🚀 Quickstart

Prerequisites

Python 3.10+
PostgreSQL 17 (with pgvector extension recommended)

1. Start PostgreSQL with pgvector (Docker)

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

2. Clone & Install

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

3. Initialize Database Schema

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

4. Ingest Technical Documents

# 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/

5. Verify Database Integrity

python scripts/validate_integrity.py

🔌 MCP Client Configuration

Archon-KB implements the standard Model Context Protocol via FastMCP. Add it to your AI toolchain in seconds:

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "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"
      }
    }
  }
}

Google Antigravity / Cursor / Windsurf

Add to your IDE's MCP configuration (mcp_config.json):

{
  "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"
      }
    }
  }
}

🛠️ MCP Tools Reference

When connected, AI agents gain access to the following native tools:

Tool	Parameters	Description
`lookup_technical_entity`	`identifier: str`	Fast direct lookup for exact identifiers (IOCTLs, WMI, APIs, RVAs). Returns complete entity card in 1 call.
`search_technical_knowledge`	`query: str, limit: int`	5-stage hybrid search combining lexical GIN + vector HNSW via RRF. Returns matched entities and code chunks.
`get_kb_health_status`	(none)	Returns real-time health status, document counts, chunk counts, and relationship metrics.

📊 Benchmarks & Health Check

Output from scripts/validate_integrity.py:

======================================================================
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
======================================================================

📁 Repository Structure

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

⚙️ Environment Variables

Variable	Default	Description
`PGHOST`	`localhost`	PostgreSQL host
`PGPORT`	`5432`	PostgreSQL port
`PGDATABASE`	`technical_kb`	PostgreSQL database name
`PGUSER`	`postgres`	PostgreSQL username
`PGPASSWORD`	`postgres`	PostgreSQL password
`EMBEDDING_MODEL`	`local-semantic-384`	Model name or embedding provider
`EMBEDDING_DIM`	`384`	Embedding vector dimensions
`KB_RECOGNIZED_FOLDERS`	(defaults)	Comma-separated analysis workspace folder names

🛡️ License

Available Tools

3 tools

get_kb_health_statusGet Kb Health StatusC

Returns the current health status, document counts, and integrity metrics of the Technical KB.

Name	Required	Description	Default
`project_path`	No
`confirm_project`	No
`project_context`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden, yet it only says data is "returned." It does not state permission requirements, cost/rate limits, behavior when the KB is missing or unconfigured, or why confirm_project/project_context would be needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler; the resource and output payload are stated immediately. It is efficient, though its brevity edges into under-specification rather than crispness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be re-explained, but three undocumented parameters plus no annotations and no usage guidance leave the agent without enough information to call the tool correctly (e.g., when confirm_project must be true).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across three parameters, and the description adds no meaning for any of them. The phrase "of the Technical KB" faintly implies a target scope, but project_path, confirm_project, and project_context are entirely unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

A specific verb ("Returns") plus a concrete resource set: health status, document counts, and integrity metrics of the Technical KB. Its read-only diagnostics role is naturally distinct from lookup/search siblings, though it never names them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of the sibling tools (lookup_technical_entity, search_technical_knowledge) that would be the alternatives for retrieval tasks. The agent must infer that this is a diagnostics call.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lookup_technical_entityLookup Technical EntityC

Zero-hallucination lookup for a specific technical identifier. Returns canonical properties, implementation methods, graph relationships, and source provenance.

Name	Required	Description	Default
`identifier`	Yes
`project_path`	No
`confirm_project`	No
`project_context`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral-disclosure burden. It lists return categories, but does not state that the operation is read-only, whether it has side effects, what permissions are required, or how project confirmation behaves.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences and is front-loaded with the lookup purpose. "Zero-hallucination" is somewhat promotional, but it does not materially waste space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, which reduces the need to describe return values in detail. However, for a four-parameter lookup with no annotations and no schema descriptions, the definition is incomplete because it leaves the project-related parameters and usage conditions unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% with four parameters. The description only implicitly covers the required identifier and says nothing about project_path, confirm_project, or project_context, so it does not compensate for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: lookup a specific technical identifier/entity. The phrase "specific technical identifier" distinguishes it from the search-oriented sibling, though it does not explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by "specific technical identifier" versus a general search, but the description gives no explicit when-to-use, when-not-to-use, or alternative-tool guidance. It also does not explain when the project-related parameters should be supplied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_technical_knowledgeSearch Technical KnowledgeC

5-stage hybrid retrieval across the knowledge base: Combines exact identifier matching, lexical full-text (GIN), and pgvector cosine similarity via RRF.

Name	Required	Description	Default
`limit`	No
`query`	Yes
`project_path`	No
`confirm_project`	No
`project_context`	No

Output Schema

Name	Required	Description
No output parameters

TDQS

C2.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It usefully discloses the hybrid retrieval mechanics—exact matching, lexical full-text, pgvector cosine similarity, and RRF—but omits important behavior such as read-only safety, latency/rate limits, result ordering, and how project scoping or confirmation parameters affect results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, front-loaded, and free of filler. However, the phrase '5-stage' is not fully explained, and the brevity contributes to missing operational guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value details are less necessary. But for a five-parameter hybrid search tool with zero schema description coverage and no annotations, the description does not provide enough information to invoke it correctly, especially around project scoping and confirmation behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across five parameters, and the description does not explain any parameter meanings. It never clarifies query, limit, project_path, confirm_project, or project_context, leaving most invocation semantics undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: search technical knowledge via hybrid retrieval across the knowledge base. It clearly states what the tool does, but does not differentiate it from lookup_technical_entity, which may also handle exact identifier lookups.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus lookup_technical_entity or get_kb_health_status. It also does not indicate when a plain keyword search is appropriate versus exact identifier matching or project-scoped retrieval.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv1.0.0Oct 24, 2026
- First observedget_kb_health_status
- First observedlookup_technical_entity
- First observedsearch_technical_knowledge

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored 2026-10-24 13:50 across 3 tools

Disambiguation4/5

lookup_technical_entity and search_technical_knowledge both retrieve technical info, but the descriptions clearly separate exact-identifier canonical lookup from broad 5-stage hybrid search. get_kb_health_status is unambiguously distinct (operational metrics only).

Naming Consistency4/5

All three follow a snake_case verb_noun pattern (get_/lookup_/search_ + object). The 'kb' abbreviation in get_kb_health_status is a minor deviation from the other two using full domain nouns, but the convention is still readable and predictable.

Tool Count4/5

Three focused tools suit a read-only technical KB retrieval server: health, point lookup, and search cover the core surface without bloat. It sits near the thin edge, but each tool earns its place with a distinct role.

Completeness3/5

Read paths are well covered (search + exact lookup + health), but there is no way to enumerate or browse entities, list available entity types/document sets, or fetch related entities except via lookup. Agents hitting an unknown identifier must fall back to search, which is a notable gap for a KB server.

Resources

Related MCP Connectors

ColdState — Deterministic Knowledge Infrastructure A
ai.coldstate
Deterministic knowledge for AI agents: search, fetch, cite and verify a 48M-entry knowledge base.
Search RAG Systems Knowledge & Memory
161
https://cold-api.coldstate.ai/mcp
ISHOB Knowledge Archive B
com.ishob
License-checked research archive and technical-spec search for AI agents. Pay per call via x402.
Agent Orchestration AI & Machine Learning Cryptocurrency
431
https://api.ishob.com/mcp
Ragora A
io.github.mregmi
Search your knowledge bases from any AI assistant using hybrid RAG.
RAG Systems Search Knowledge & Memory
2
https://mcp.ragora.app/mcp
embedded-docs A
ai.byteask
Page-cited retrieval for embedded docs, datasheets, MISRA, CMSIS, and RTOS references.
Embedded system Documentation Access
3226
https://mcp.byteask.ai/mcp

Related MCP Servers

Nexus MCP Server
Search Web Scraping Browser Automation
rcdelacruz
A
license
A
quality
Not graded
maintenance
Enables hybrid web search and intelligent content extraction, combining semantic search with documentation-optimized reading that strips noise and returns clean, token-efficient context for AI agents.
Updated 8 months ago (2026-03-08 01:55 UTC)
2
MIT
Qurio MCP Server
RAG Systems Search
irahardianto
A
license
Not graded
quality
D
maintenance
Enables AI coding assistants to search and retrieve information from a locally ingested knowledge base using hybrid search, grounded in user-curated documentation.
Updated 9 months ago (2026-02-15 22:06 UTC)
16
MIT
KernelMind MCP
RAG Systems Code Analysis Documentation Access
Reinazhard
A
license
A
quality
D
maintenance
Enables AI agents to query Linux kernel source code, git history, LKML discussions, Patchwork patches, and documentation with evidence-ranked results, citations, and explicit assumptions or contradictions.
Updated 3 months ago (2026-08-02 11:42 UTC)
16
GPL 2.0
vhdl-rag-mcp
RAG Systems Code Analysis Documentation Access
ru551n
A
license
A
quality
A
maintenance
Provides coding agents with hybrid semantic and exact-identifier search across VHDL source, documentation, and general code, with cross-referencing and exact source attribution.
Updated a day ago (2026-11-02 10:08 UTC)
8
1
MIT