# Repository Runtime

Turn a folder of Markdown files into a **queryable knowledge layer** that an AI
agent (like [Hermes](https://hermes-agent.nousresearch.com)) 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](https://hermes-agent.nousresearch.com) (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)

---

## Why use it? (with vs. without)

| | Without the runtime | With the runtime |
|---|---|---|
| Finding info | Agent loads whole files into context and skims | Agent calls `search_documents("…")` → ranked hits with snippets |
| 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

```bash
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/`).

```bash
# 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](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

```bash
pip install pytest
python3 -m pytest -q
```

---

## License

See [LICENSE](LICENSE).