A Rust-native knowledge graph engine with pointer-based RAG (Retrieval-Augmented Generation), hybrid search, and temporal truth — designed for use as a Model Context Protocol (MCP) server in AI-assisted development workflows.

• Pointer-based RAG: Retrieve relevant code/doc nodes without pulling full content; fetch only when needed
• Hybrid search: Full-text search (FTS5), vector/embedding similarity, and literal pattern matching
• Temporal fact store: Record and query time-scoped facts (decisions, constraints, learnings, API contracts)
• Knowledge graph: File and symbol relationships built from workspace crawling and chunking
• MCP server: Exposes tools via the Model Context Protocol for use with AI coding assistants (e.g. GitHub Copilot, Claude, Cursor)
• Token accounting: Tracks token savings from pointer-based retrieval vs. full file reads
• Env-var validation: Scans source files and config files for environment variable definitions and usages; detects typos and dead config via hermes_validate_env / hermes_check_consistency
• Auto-reindex: Background thread periodically re-indexes the workspace (configurable via HERMES_AUTO_INDEX_INTERVAL_SECS)

src/
├── bin/hermes.rs       # MCP server entry point (stdio transport)
├── lib.rs              # Public API surface
├── schema.rs           # SQLite schema definitions
├── graph.rs            # Knowledge graph core
├── graph_builders.rs   # Graph construction helpers
├── graph_queries.rs    # Graph traversal queries
├── pointer.rs          # Pointer node types and resolution
├── accounting.rs       # Token savings accounting
├── embedding.rs        # (Optional) Gemini embedding client — not used by default
├── temporal.rs         # Temporal fact store
├── mcp_server.rs       # MCP protocol implementation
├── mcp_tools_validation.rs # hermes_validate_env / hermes_check_consistency tools
├── ingestion/
│   ├── mod.rs          # Ingestion orchestration
│   ├── crawler.rs      # Workspace file crawler
│   ├── chunker.rs      # Code/text chunking
│   ├── hash_tracker.rs # File change detection
│   └── env_scanner.rs  # Environment variable discovery (config_registry)
└── search/
    ├── mod.rs          # Unified search interface
    ├── fts.rs          # Full-text search (SQLite FTS5)
    ├── vector.rs       # Vector similarity search
    └── literal.rs      # Literal/regex pattern search

• Rust 1.75+
• No external services required — vector search works locally out of the box
• (Optional) A Gemini API key if you want to use the higher-quality EmbeddingGenerator (see src/embedding.rs)

cargo build --release

To keep the index fresh after branch switches and merges, use repository hooks:

git config core.hooksPath .githooks
chmod +x .githooks/reindex.sh .githooks/post-merge .githooks/post-checkout

On Windows (PowerShell):

git config core.hooksPath .githooks

chmod is not required on Windows when using Git for Windows.

What this enables:

• post-merge: runs hermes index after merge/pull
• post-checkout: runs hermes index after branch checkout

You can temporarily disable hook-triggered reindex by setting:

HERMES_SKIP_HOOK_REINDEX=1

PowerShell equivalent:

$env:HERMES_SKIP_HOOK_REINDEX = "1"

HERMES_PROJECT_ROOT=/path/to/your/project ./target/release/Hermes --stdio

Add to .vscode/mcp.json:

{
  "servers": {
    "hermes": {
      "type": "stdio",
      "command": "/path/to/hermes/target/release/Hermes",
      "args": ["--stdio"],
      "env": {
        "HERMES_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

See LICENSE.