Repository Runtime

Turn a folder of Markdown files into a queryable knowledge layer that an AI agent (like Hermes) can search — instead of loading every file into its context window.

It indexes Markdown into a local SQLite database with full-text search, metadata, and a relationship graph, then exposes that index two ways:

• a CLI for humans and scripts, and

• an MCP server so AI agents call search_documents / read_document / get_relationships as native tools.

Goal: an AI-first knowledge layer — structured, queryable memory for software agents. Non-goals: it is not a vector DB, a Git replacement, a doc generator, an IDE, a project-management tool, or an LLM.

Built with

This project was orchestrated end-to-end inside Hermes Agent (Nous Research). The coding work was driven by a sequence of models during free-usage testing in Hermes:

1. gpt-oss — local LLM (initial build)

2. nemotron-3-ultra

3. gpt-5.6-terra

4. Hy3 — final iteration (free-usage testing)

Related MCP server: ai-brain

Why use it? (with vs. without)

On a large KB this is often 10–50× fewer tokens per question, with more accurate answers.

Quick start

git clone <your-fork-url> repository-runtime
cd repository-runtime

# 1. Install (a venv is recommended so the MCP launcher can find deps)
python3 -m venv .venv
. .venv/bin/activate
pip install -e .

# 2. Index the bundled sample corpus (or your own folder)
repo-runtime index docs-example --force

# 3. Search it
repo-runtime document-search "getting started" --mode keyword

repo-runtime is installed as a console script; you can also run it as python3 -m runtime.cli ….

Use it from Hermes Agent (MCP)

The MCP server is launched by scripts/repo-runtime-mcp, which resolves paths relative to itself and serves the folder in REPO_RUNTIME_KB (defaults to the bundled docs-example/).

# make the launcher executable (once)
chmod +x scripts/repo-runtime-mcp

# point it at YOUR Markdown folder (optional; defaults to docs-example/)
export REPO_RUNTIME_KB=/absolute/path/to/your/markdown

# register with Hermes (use an absolute path to the launcher)
hermes mcp add repo-runtime --command "$(pwd)/scripts/repo-runtime-mcp"
hermes mcp test repo-runtime      # should report: Connected! Found 7 tool(s)

Then just ask Hermes naturally — "search the knowledge base for X and summarize it" — and it will use the tools instead of reading files.

Tools exposed (read-only "viewer" role): search_documents, read_document, search_entities, read_entity, get_relationships, traverse_graph, shortest_path.

See USAGE.md for the full guide (CLI reference, search modes, re-indexing, troubleshooting, security notes).

Requirements

• Python 3.10+

• Dependencies from requirements.txt / pip install -e . (click, PyYAML, fastapi, uvicorn, pydantic, jsonschema, lark)

• Optional: sentence-transformers for semantic/hybrid vector ranking (without it, search cleanly degrades to keyword/BM25)

• Optional: mcp to test the server with the official MCP client

Running the tests

pip install pytest
python3 -m pytest -q

License

See LICENSE.