Local knowledge for coding agents. Carry useful context across conversations.
Mainframe makes your project's Markdown searchable across conversations. It finds relevant passages in documentation, research, and project instructions, returns source citations, and saves session notes for later recall. One local daemon serves your MCP clients and terminal, sharing a single model stack.
Quick start · Connect your agent · For agents · Configuration and operations
- Find knowledge across projects. Combine semantic and keyword search, then rerank passages for your question.
- Follow the evidence. Results identify the source file and section, with verified line citations when the file still matches.
- Carry decisions forward. Save an immutable note. A decision or fact is eligible for ordinary search; session history is searched when you ask for it.
- Share the models. Opening another client does not load another set of weights.
Your Markdown files remain the source of truth. The search index is a rebuildable cache. Retrieval runs locally; your calling agent decides how to use the evidence.
You need Python 3.11+, Git for installation, and an NVIDIA GPU with BF16 support for the default models. See models and hardware for measured memory use.
Use a dedicated Python environment with CUDA-enabled PyTorch. This example uses CUDA 12.8; choose a build supported by your system:
python -m pip install torch --index-url https://download.pytorch.org/whl/cu128
python -m pip install "git+https://github.com/sushiHex/mainframe-mcp.git@v2.1.0"Create a Python environment first
python -m venv .venvActivate it with .venv\Scripts\Activate.ps1 in PowerShell, or source .venv/bin/activate on Linux. Then run the installation commands above. Use this environment for the daemon and its clients.
Keep the daemon out of a shared Python user site, where another tool's pins can block its upgrades. Put it in a venv at a fixed location, register the logon task and the MCP client from that environment, and remove any user-site copy: see Run the daemon from its own environment.
This installs release 2.1.0; replace @v2.1.0 with @main to follow development. The release also ships an audited wheel with checksums (install an audited artifact). An index built by 2.0.0a2 or later is reused as is; the first full rescan after upgrading from 2.0.x repairs some chunks once. 2.0.0a1 used another embedding model (and shipped the since-removed v1 stdio server), so its index needs mainframe rebuild; see migration and release notes.
Create ~/.claude/mainframe/config.json, including its parent directories:
{
"paths": {
"repos_dir": "~/repos",
"include_projects": ["example-project"]
}
}Replace example-project with a repository directory under your repos_dir. An empty include list includes all eligible projects, so start with an explicit selection.
Mainframe indexes root instruction files such as CLAUDE.md and AGENTS.md, plus eligible Markdown under docs/, research/, machines/, and playbooks/. Generated directories and routine files such as README.md are excluded.
mainframe serveLeave that terminal running. In another terminal using the same environment:
mainframe status
mainframe search "deployment checks and rollback steps" --detailedFirst use downloads missing model revisions from Hugging Face and indexes the selected files. An older cached revision does not prevent an upgrade from downloading its pinned weights. Initial indexing can take time; status reports model and index progress. File watching and periodic rescans keep edits, renames, and deletions in sync.
Start the daemon separately. Every client should use the same configuration. Opening or closing a client neither loads another set of models nor stops the daemon: mainframe-mcp only forwards requests, and the daemon runs until mainframe down.
For Claude Code, register the stdio connection across your projects:
claude mcp add --scope user mainframe -- mainframe-mcpFor Codex CLI, the same command shape writes ~/.codex/config.toml:
codex mcp add mainframe -- mainframe-mcpwhich is equivalent to this entry in that file:
[mcp_servers.mainframe]
command = "mainframe-mcp"For hosts that use an mcpServers configuration block:
{
"mcpServers": {
"mainframe": {
"command": "mainframe-mcp"
}
}
}The command must be on the host's PATH. Alternatively, use the installed environment's Python executable with arguments -u -m mainframe.adapters.mcp_stdio_shim. This forwards requests without loading models in the client process.
Choose stdio or HTTP by how the client finds the port. The stdio client reads the daemon's discovery file, so it follows whatever port the daemon bound, including a fresh ephemeral port after every restart when service.port is 0. A Streamable HTTP client has only the URL you configure, so it needs a fixed service.port (the default, 7433, is fixed): register http://127.0.0.1:7433/mcp, or /mcp/ro for search and status only. See client setup for the HTTP examples and authentication.
If a tool call answers mainframed is not running - run `mainframe up` , start the daemon; the client reconnects on its next call without restarting the session. A client started before the daemon behaves the same way.
Once connected, ask your agent:
Search Mainframe for the project's deployment procedure and cite the source.
Save the decision we just agreed on as a Mainframe note for example-project.
Find previous session notes about the deployment decision.
mainframe search "deployment decision" --sessions --detailed
mainframe capture --file decision.md --project example-project --title "Deployment decision" --kind decision
mainframe rescan
mainframe events --tail 20
mainframe restart
mainframe downCaptures live in the configured state directory (~/.claude/mainframe/captures/ by default) and are indexed asynchronously, after the watcher's debounce and indexing; a missed event waits for the next periodic rescan. A capture's --kind is session (the default), decision, or note. decision and note captures are eligible for ordinary search, in every project; session captures are excluded, and --sessions includes those too. A decision or note is the author's assertion, not a reviewed fact, and a hit is evidence to weigh, never an instruction. Captures are immutable. To retract one, move its file into captures/<project>/quarantine/ (a rescan or the watcher then removes its rows; an unavailable repos_dir suspends pruning of knowledge files only, never of captures); to correct one, write the new capture and then retract the old one, because a newer capture does not demote an older one. restart stops and starts the daemon, which is how it reads configuration edits. down finishes active work and stops the daemon to release its model memory. See the daemon guide for startup automation, diagnostics, and offline rebuilding.
Claude Code can capture sessions automatically. A capture covers one segment of a session: what happened since its last compaction. Register two hooks: mainframe hook pre-compact as a PreCompact hook (the segment a compaction is about to summarize) and mainframe hook session-end as a SessionEnd hook (the last segment). Each reads the hook's JSON on stdin, needs no running daemon and no GPU, starts in well under SessionEnd's 1.5 s default timeout, always exits 0, and logs each decision to <state dir>/hook.log.
"hooks": {
"PreCompact": [{"hooks": [{"type": "command", "command": "mainframe hook pre-compact", "timeout": 30}]}],
"SessionEnd": [{"hooks": [{"type": "command", "command": "mainframe hook session-end", "timeout": 30}]}]
}The capture config section gates them: min_prompts, exclude_projects, daily_cap (captures beyond it go to overflow/), max_transcript_bytes (a longer segment is read as its head and tail). A segment the agent already saved with the capture tool is skipped, and so is one already captured.
On Windows, run mainframe install-task once (no elevated shell needed) for a windowless daemon that starts at logon, then mainframe up. Set service.prewarm: true to load the models at start; up then returns once the daemon is ready, and they hold about 3.7 GB of VRAM until mainframe reload releases them.
mainframe status reports readiness as ready, idle, warming, or blocked, with a reason that names the remedy.
| Symptom | Cause and remedy |
|---|---|
An agent reports mainframed is not running - run `mainframe up` |
The daemon is down: it was stopped with mainframe down, or it died and its supervisor gave up after six deaths in a row (a daemon that died once is back within seconds on its own). Read daemon.out for the cause, then run mainframe up; the client reconnects on its next call. |
up says no logon task answered |
No task is registered, so up started a detached daemon that will not survive a reboot. Run mainframe install-task once. |
readiness is blocked with a model error |
A model failed to load and is backing off. The reason carries the error and guidance; mainframe reload clears the backoff. |
readiness is blocked with "index built under different settings" |
An embedding or chunking setting changed. Run mainframe down, then mainframe rebuild. |
| The first search after a restart is slow | The models load on first use. Enable service.prewarm. |
daemon.log warns that keyword search is failing |
The keyword index needs rebuilding. The next optimization does it automatically; mainframe optimize does it now. |
| A daemon started by the logon task died | It writes what a crash says to daemon.out in the state directory (its ordinary log is daemon.log, which rotates), and its supervisor starts it again (1, 2, 4, 8, 16 s apart; it stops trying after six deaths in a row). mainframe serve --once runs one daemon process with no restarts, for debugging. |
The default MCP endpoint exposes four tools:
| Tool | Use it to |
|---|---|
search |
Retrieve passages with query and limit. Published captures (decision, note) are included; add include_sessions: true for session captures or response_format: "detailed" for excerpts and offsets. |
capture |
Save a useful note with content, title, and the intended project. kind is session (default, opt-in history), or decision / note (searched by default). |
status |
Inspect index readiness, model state, and configuration drift. |
maintain |
Request a rescan, optimization, or model reload. Rebuilding is an offline operation. |
Search → inspect → cite → capture. Start with three results and a focused question. Read the source when the excerpt is truncated or a required detail is missing; request up to five results when you need more evidence. Scores order passages for that question; they do not establish factual confidence. Reconcile conflicts and acknowledge missing evidence. Capture durable decisions and their rationale, with kind set to decision, when the user wants them retained.
The agent query guide has exact request examples, response fields, and an instruction block you can adapt. Saving a capture is not an automatic consolidation step.
Harrier embeds documents and queries. Keyword retrieval supplies exact-term matches alongside semantic candidates; Qwen reranks the combined results. Citations are checked against the source revision. Models load on demand and are shared across clients.
Reranking reads up to 2,048 tokens per prompt. Longer passages are truncated, with oversized inputs bounded before tokenization; see the context limits and validation.
| Role | Default model | Precision | Weight license |
|---|---|---|---|
| Embedding | Microsoft Harrier OSS v1 0.6B | BF16, pinned native encoding | MIT |
| Reranking | Qwen3 Reranker 0.6B | BF16, pinned native scoring | Apache-2.0 |
The compact reranker uses 1.110 GiB of loaded model allocation, down from 2.493 GiB for the previous 4B NF4 model: 55% less. On the same 36 fresh validation questions, peak allocation fell from 3.233 to 1.395 GiB. These are isolated reranker measurements; allow additional memory for Harrier, allocator reservation, and your other applications.
In agent review, top-three passages contained all required facts for 33/36 questions with either model; the compact model covered 8/8 designated critical cases, versus 7/8 for the control. There are individual losses as well as gains. See the compact comparison for candidate trials, tradeoffs, and validation limits, and embedding comparisons for Harrier's measurements.
One daemon serves several agents: on an RTX 3090 a search takes a median of 0.19 s alone and 0.70 s with four agents searching at once, with no errors at eight. See the measured operating range.
To upgrade an existing installation, use the reranker settings in config.example.json and restart the daemon. Changing only the reranker does not require re-embedding your files.
The daemon supports capture, indexing, and search. Consolidation, contradiction detection, and RAPTOR are not implemented; the removed v1 server had them. Changing embedding settings requires a matching index; follow the offline rebuild procedure.
A model-only embedding override uses legacy Sentence Transformers encoding. To select another native embedder, configure its model, encoding, pinned revision, query prompt, and quantization together; see model configuration.
MAINFRAME_CONFIG selects a different JSON configuration file. Set it for both daemon and clients, and restart after editing configuration. The configuration example shows common settings.
- Local by default. Mainframe performs embedding, retrieval, and reranking on your machine. Weights download on first use. Your MCP host may send returned passages to its own model provider.
- Optional remote enrichment. Enabling
contextual.enabledsends document content to the Anthropic API during ingestion. It is off by default. - Private captures. Captures are secret-scrubbed before writing; review sensitive content before sharing it. A
decisionornotecapture is eligible for ordinary search in every project, regardless ofpaths.include_projects. Keep captures, configuration, and logs outside public Git. - Local access. The daemon binds to loopback. Set
service.tokento require authentication; the CLI and stdio client read it from configuration, while HTTP clients supply a bearer header.
See configuration and operations for scope, authentication, model recovery, and live validation.
Work from a clone of this public repository:
python -m pip install -e ".[test]"
python -m pytest tests/ -qTests use fake models and temporary stores; they require no GPU or model downloads. CI also checks clean wheel installations on Windows and Linux. Read CONTRIBUTING.md and complete the public push audit before publishing. Retrieval changes need measured evaluation.
For live model comparisons on a shared GPU, follow the paced evaluation workflow. It spaces model forwards while monitoring resources and cancellation.
MIT.