Skip to content

About

Local knowledge search for coding agents: GPU hybrid search and reranking with source citations, plus saved decisions and session captures, served by one shared MCP daemon.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Mainframe MCP

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

Why Mainframe

  • 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.

Quick start

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.

1. Install

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 .venv

Activate 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.

2. Choose your projects

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.

3. Start and search

mainframe serve

Leave that terminal running. In another terminal using the same environment:

mainframe status
mainframe search "deployment checks and rollback steps" --detailed

First 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.

Connect your agent

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-mcp

For Codex CLI, the same command shape writes ~/.codex/config.toml:

codex mcp add mainframe -- mainframe-mcp

which 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.

Use from a terminal

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 down

Captures 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.

Troubleshooting

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.

For agents

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.

How it works

One shared Mainframe daemon indexes project Markdown and saved captures. Harrier embeddings and keyword search find candidates; Qwen reranks them and returns passages with source citations to your agent or terminal.

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.

Models and hardware

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.

Configuration and privacy

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.enabled sends 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 decision or note capture is eligible for ordinary search in every project, regardless of paths.include_projects. Keep captures, configuration, and logs outside public Git.
  • Local access. The daemon binds to loopback. Set service.token to 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.

Development

Work from a clone of this public repository:

python -m pip install -e ".[test]"
python -m pytest tests/ -q

Tests 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.

License

MIT.

About

Local knowledge search for coding agents: GPU hybrid search and reranking with source citations, plus saved decisions and session captures, served by one shared MCP daemon.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages