ROMS

By Buzburg.

Stop re-explaining your project to every AI.

Your useful knowledge is scattered across notes, manuals, code, PDFs and past work. ROMS brings it into one local library—then helps you find the right evidence, carry it into another AI conversation, and turn repeatable work into reusable skill drafts.

Give your local AI something worth knowing. Search your documents, select the passages that matter, and build a task brief you can paste into any assistant. When you want more, connect an agent to draft and retain task-specific procedures from your indexed knowledge.

Try ROMS · Download source · Portable task briefs · Local skill agent

What you can do with ROMS

• Bring the files you already have. Import notes, source code, logs, uneven CSV, PDFs, modern Office documents and images. Local OCR recovers text from scans.
• Find it even when you barely remember it. Keyword matching, typo handling and semantic retrieval share one search. Results retain source references.
• Carry context between assistants. Select up to eight search passages, add your task and constraints, then preview, copy or download a cited Markdown brief. Assembling the brief needs no generation model or client integration.
• Turn recurring work into reusable skills. Imported guides become procedural drafts. The optional local agent can also create and save a tailored candidate from an ordinary task request, reuse it, and revise it when sources change.
• Keep the evidence attached. Saved candidates retain original constraints, source identity and revision-specific feedback. Changed sources withhold stale drafts; detected conflicts produce questions before another candidate is saved.
• Keep your library local. Search, embeddings and OCR run locally after setup. You choose what to copy into another client; that client's data settings apply.

Try it with a deployment guide, a project README and a few troubleshooting notes. Search for the task you're working on, build a brief, and start your next AI conversation with relevant evidence already in hand.

How task briefs work · Knowledge-derived skills · Task-specific skills and their limits

Search benchmarks cover specific fixtures and machines. Historical timings do not describe the current search backend or promise production speed or accuracy. See the results and limits.

The lightweight Python demos and preparation tools are tested on Windows and Linux with Python 3.11 and 3.12. The full Mojo search environment targets x86-64 Linux/WSL2. Python remains the adapter for file formats, model inference and MCP; ROMS is not a pure-Mojo application. Optional operating-system integrations are separate from the core search setup.

Choose your starting point

Goal	Start here	Requirements
Try a controlled recovery demo	No-install demo	Python only; no model or network
Import and search your own files	Local knowledge workspace	Linux/WSL2, Pixi, compiled Mojo kernels and local embeddings
Carry selected evidence into any assistant	Portable task brief	The knowledge workspace; no generation model needed for export
Give an AI client access to knowledge	MCP connection	The search environment plus an MCP-compatible client
Prepare a task for human review	Portable harness	Python and the lightweight CI dependencies

Download the source above, or clone the repository:

git clone https://github.com/Buzburg/ROMS.git
cd ROMS

Run the commands below from this directory. The source checkout contains neither prebuilt Mojo binaries nor embedding weights. The first full setup needs network access for packages and the embedding model; search and OCR then run locally.

Five parts

Part	Purpose
Decision Maker	Rank supplied options, return structured results and abstain when configured thresholds are not met. The current backend uses heuristics; its scores are not calibrated probabilities of correctness.
RAG	Find relevant document passages through keyword and vector search, with source references and bounded context.
OKF	Import local knowledge files, preserve document metadata and update their search indexes.
MCP	Let a compatible agent call registered tools and read resources through one local server.
Skills	Supply reusable Markdown playbooks. Generated drafts need review before activation.

The workflow is request → knowledge and skills → decision → proposed next step → operator approval → separately configured execution. The preparation API implements the first four steps. It does not execute the proposal or approve itself. See the component map.

Try one useful thing first

From a downloaded or cloned checkout, use Python 3.11 or 3.12 (the tested versions):

python -I -S -B scripts/demo_first_run.py

No installation, account, model, GPU or network connection is needed. The demo creates a temporary invoice program, introduces a known bad edit and runs a real failing check. ROMS extracts the error from the log, locates the function and restores the original file. The check must pass again before the temporary files are removed and success is reported.

Add --json to inspect the original failure log, compacted log, source location and before/after file hashes. The demo accepts no path to your project. It demonstrates controlled recovery, not autonomous repair or safe rollback of concurrent edits. Verification scope.

Prepare a task for review

The harness uses the lightweight dependencies in requirements-ci.txt. On Linux:

python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements-ci.txt
.venv/bin/python roms.py harness --request examples/harness-request.json
.venv/bin/python -B scripts/demo_harness.py

On Windows (PowerShell):

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-ci.txt
.\.venv\Scripts\python.exe roms.py harness --request examples/harness-request.json
.\.venv\Scripts\python.exe -B scripts/demo_harness.py

Python 3.11 also works. These commands use the environment explicitly; activation is optional. The harness guide explains request fields, database setup and examples.

The harness demo uses a temporary synthetic knowledge index and selected skill to exercise real retrieval and the public CLI. It prints its checks and removes the fixture afterward.

Preparation retrieves keyword matches from an existing OKF index, reads explicitly selected Markdown skills, and evaluates supplied choices through the current Decision Maker. Retrieval uses the indexed snapshot; it does not revalidate the original documents. The response includes source hashes, a bounded context, a decision or abstention, and a proposed next step. It always reports approval_required: true and execution_allowed: false.

This path does not call a model, use the network, run tools, edit documents or save topic-discovery records. SQLite may use normal coordination sidecars. It is a preparation step for a caller or operator to review, not a complete autonomous execution loop.

Other command-line tools

The existing utility CLI uses Python's standard library:

python roms.py --help
python roms.py index --path .
python roms.py lookup --query invoice_total_cents
python roms.py pack --costs "50,40,30" --values "100,60,50" --budget 70 --required 2

Commands for advisory decisions, memory, log compaction and snapshots are listed in --help. Utilities can write local state under data/prefrontal/; set ROMS_DATA_DIR to use another data directory. Snapshot restoration writes files and validates saved paths and content. Older unbound snapshots require manual recovery; read the recovery boundaries before applying a snapshot to a real workspace.

Standalone Decision Maker utilities can also persist topic discovery under ROMS_STATE_DIR (default ~/.roms). Harness preparation disables that persistence.

Add knowledge in your browser

On x86-64 Linux or WSL2, install Pixi and use the repository's locked environment throughout:

pixi install --locked
pixi run python scripts/build_search_native.py
pixi run python -c "from app.config import get_embedding_model; get_embedding_model()"
pixi run python roms.py knowledge

The model-loading command provisions the default CPU embedding model before the first import. Keep using pixi run python so ROMS sees the packages installed by Pixi. Open the private local link printed in the terminal. Drop files, select a folder, or paste text. Imports show progress and retry controls; restarting resumes interrupted jobs from retained originals. Search, headings and a source-linked glossary share the same index. Import guide and limits.

Alternatively, use a Python 3.11/3.12 virtual environment with python -m pip install -r requirements.txt mojo==1.1.0, build with python scripts/build_search_native.py, and launch with python roms.py knowledge. In that route, every python must be the environment's executable, and Tesseract with English data plus Poppler must be installed separately. Pixi includes them.

Connect an MCP client

Complete the search setup above, then start the Python MCP server:

pixi run python roms.py mcp

This command uses stdio and waits for MCP messages. For clients with an mcpServers configuration, use the absolute path to the same environment's Python:

{
  "mcpServers": {
    "roms": {
      "command": "/absolute/path/to/ROMS/.pixi/envs/default/bin/python",
      "args": ["/absolute/path/to/ROMS/roms.py", "mcp"]
    }
  }
}

If you installed with pip instead, use /absolute/path/to/ROMS/.venv/bin/python. Configure the client to launch inside WSL when using the Linux environment from Windows; a Windows process cannot directly execute this Linux Python binary.

See the search setup guide for supported formats and extraction limits.

Startup initializes the database, indexes supported files in knowledge/, starts the watcher and loads only explicitly enabled local plugins. ROMS uses only pinned local Q8 embeddings on CPU; first use may download model files. The 768-dimensional index defaults to data/embeddinggemma-q8.db. Re-ingest your knowledge into this new index when upgrading from the legacy embedding backend; old databases are preserved. Review security and data handling before connecting an agent.

Reference repositories used for design inspiration are not required installations. See the dependency guide for what the runtime actually uses. Test tools are separate: install requirements-dev.txt when running the full test suite, or use pixi run -e dev test-search for native search checks.

Useful registered interfaces

Task	Interface
Export selected evidence for another assistant	prepare_knowledge_brief with task, selected chunk IDs and constraints
Create or revise a task-skill candidate	create_task_skill, revise_saved_task_skill with a configured local generation endpoint
Prepare a reviewable request	roms_prepare_harness with request_json
Search knowledge	search_knowledge_base — one local adaptive engine, shared by chat, grounded context and the Mojo entry point
Import status	get_knowledge_ingestion_status — unreadable files, recovered-data notes and OCR diagnostics; search and intake guide
Queue files or pasted text	queue_knowledge_path, queue_knowledge_text
Track imports and retry failures	knowledge_import_progress, retry_knowledge_import
Browse headings and definitions	knowledge_table_of_contents
Add or refresh documents	add_knowledge_document, reload_knowledge, list_knowledge_documents
Retain and recall project lessons	memory_retain, memory_recall, memory_get, memory_prepare_context
Record or revise lesson evidence	memory_record_verification, memory_correct, memory_retract, memory_forget
Get an advisory decision	roms_decide, roms_noul, roms_score
Find tools and skills	search_tools, list_skills
Read a skill	Resource skills://{skill_name} or prompt get_skill_playbook
Inspect logs and source locations	roms_sieve_compact, roms_symdex_lookup

MCP starts in read_only mode: search and recall work immediately, while authoring tools require ROMS_MCP_PROFILE=local. Rewind and permanent deletion additionally require ROMS_MCP_ALLOW_DESTRUCTIVE=1. See MCP settings for plugin opt-in and request limits.

The server advertises the full tool list and schemas on connection. The harness tool uses the server's configured database and skills directory; it does not accept arbitrary paths. Other tools can write knowledge, change lessons, author skills or restore files. Caller-supplied verification records are not authenticated test results.

Troubleshooting

Symptom	What to check
ModuleNotFoundError after installing dependencies	Run with pixi run python, or the exact virtual-environment Python used for installation.
“Build the required Mojo search module”	Build in that environment with python scripts/build_search_native.py, then restart ROMS and its MCP client process.
Model loading fails offline	Run python scripts/fetch_embedding.py while online using the same user and Hugging Face cache as the service, then enable HF_HUB_OFFLINE=1.
A scan or image cannot be imported	Check Tesseract English data and pdftoppm; inspect the job error or get_knowledge_ingestion_status. OCR cannot recover every scan.
A changed file still returns old content	A failed update retains the previous index while the watcher retries with backoff capped at 60 seconds. Inspect ingestion status and resolve persistent errors; reload_knowledge retries immediately.
Deleted files still appear in search	The watcher and reload_knowledge remove deleted managed files after a complete scan. If the folder is unavailable or a scan fails, the old index is preserved. Independently imported snapshots remain until explicitly removed.
MCP authoring tools are denied	The default profile is read_only. Enable ROMS_MCP_PROFILE=local only for a client you intend to grant write access.

See search setup, MCP settings and snapshot recovery for detailed boundaries.

Status and limits

ROMS is a developer project for a trusted local operator. Its Python tools, native components and optional integrations have different prerequisites and verification scopes.

• Decision scores and retrieved text can be wrong. They do not establish truth or grant permission to change a system.
• Local plugins run with the server's permissions. Skills and retrieved documents are untrusted input to the agent.
• The optional model gateway needs a separately configured inference service. Installing ROMS does not install model weights or an operating system.
• Dataset export does not train a model. Routing prototypes do not establish measured model-quality improvements.
• Benchmark reports cover specific fixtures and machines. No general latency, token-saving or GPU-performance guarantee is made. The planned 128 GB machine needs its own qualification.

Verification

The no-install demo has standard-library regression checks. For the commands in this section, use your environment's Python (.venv/bin/python on Linux or .\.venv\Scripts\python.exe on Windows), or prefix python with pixi run:

python -m unittest discover -s tests -p test_first_run_demo.py -v

After installing requirements-ci.txt in your environment:

python -m pytest tests/test_first_run_demo.py tests/test_prefrontal_integration.py tests/test_decisions_jev_laya.py tests/test_release_safety.py tests/test_memory.py tests/test_context.py -q

For native search, document extraction and the local knowledge interface:

pixi run -e dev python scripts/build_search_native.py
pixi run -e dev python -m pytest tests/test_search_native.py tests/test_search_upgrades.py tests/test_messy_ingestion.py tests/test_knowledge_intake.py -q

The October 20 review records verified checks, the index-freshness fixes and recommended follow-up work. The harness guide records its checks, and the CI workflow defines the portable test matrix. Native builds and live-model checks have separate prerequisites.

More documentation

The Linux/Omarchy workshop adds staged changes, registered validation and operator-approved promotion. It requires its own configured runtime and confinement components; those execution features are not established by the portable preparation command or a positive decision score.

• Release summary
• Harness request and response contract
• Component map and experimental boundaries
• Project lessons and evidence
• Native context selection and scoped measurements
• Search setup and supported documents
• Current search verification
• Retrieval correctness
• Workshop, build evidence and runtime integrations
• Omarchy test-build setup and voice setup
• Chat data handling and security boundaries

License

Apache-2.0. Copyright 2026 Buzburg LLC. Third-party licenses and acknowledgements remain in NOTICE and the relevant source directories.

For local 8-bit embeddings, see setup and verification.