repository-runtime
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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_relationshipsas 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:
gpt-oss— local LLM (initial build)nemotron-3-ultragpt-5.6-terraHy3— final iteration (free-usage testing)
Related MCP server: ai-brain
Why use it? (with vs. without)
Without the runtime | With the runtime | |
Finding info | Agent loads whole files into context and skims | Agent calls |
Tokens/question | Every file read in full — tens of thousands of tokens | One small query result + the one doc it needs |
Precision | Answer buried in noise; cross-file links missed | BM25/hybrid ranking + graph surface the right passage |
Scaling | Degrades as the repo grows (context limit) | Flat — search cost is independent of repo size |
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 keywordrepo-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-transformersfor semantic/hybrid vector ranking (without it, search cleanly degrades to keyword/BM25)Optional:
mcpto test the server with the official MCP client
Running the tests
pip install pytest
python3 -m pytest -qLicense
See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Personal context for every AI: search, read, and write back to your private Markdown library.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI agents to search local Markdown documents using natural language, with automatic indexing and section-level retrieval.1017 npm1MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants like Claude and Codex to read, write, search, and traverse Markdown notes stored in a self-hosted knowledge base.-
- AlicenseAqualityDmaintenanceEnables AI assistants to search, read, and traverse Markdown note vaults (Obsidian-compatible) with full-text search, backlinks, knowledge graphs, and a persistent memory system for cross-session context.1613 npm4MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to query and interact with a graph database of markdown notes, extracting entities like wikilinks, mentions, and hashtags.MIT