SearchOS: a multi-agent search runtime that keeps research state outside the chat

The problem SearchOS targets: research questions that are tables, not sentences

Most search agents answer a question by iterating over a conversation. You ask, the model searches, reads, searches again, and eventually writes a paragraph. That works for "who won the 2025 title" and falls apart for "top-5 universities per subject in the 2025 QS rankings, with application deadlines", which is the example in the README. The second question is not one lookup. It is a grid of entities and attributes, and the interesting failure is not a wrong sentence, it is a missing cell nobody noticed.

SearchOS is built for that second shape. The README describes the project as unifying "single-fact lookups to full-domain research" under what it calls citation-grounded relational schema completion. The practical claim is narrower and more useful: the question becomes a normalized entity × attribute table, and the system keeps dispatching until every cell holds a sourced value. Recall comes before polish.

The intended user is someone who already writes scripts against search APIs and model APIs, not an end user typing into a box. The pyproject classifiers list Intended Audience :: Developers and Intended Audience :: Science/Research, and the dependency list is a normal Python agent stack: langgraph, langchain, langchain-openai, langchain-anthropic, pydantic, httpx, fastapi. If you want a hosted product, this is the wrong layer.

SOCM: search state as a system asset rather than conversation history

The central design decision is what the README calls SOCM, Search-Oriented Context Management. It keeps three things in one persistent state shared by all agents: the task queue, the evidence graph, and the coverage map. Because that state is a system asset rather than a transcript, it can be snapshotted, restored and replayed. The repository release notes from 2026-07-09 describe sessions returning with conversation, progress, evidence and live activity intact.

This matters because the usual agent failure mode is context death. A long research run exceeds the window, the early findings get summarized away, and the agent re-searches things it already found. Moving the queue and the evidence out of the message list removes that failure by construction. The cost is that you now own a state store and its lifecycle, and the README does not document rollback of a partially written evidence graph.

On top of that state, sub-agents run pipelined and in parallel. The README describes search → open → find stages overlapping across agents so wall-clock time approaches the slowest single chain rather than a serial sum. Each agent's extraction middleware writes (entity, attribute, value, source) tuples into the evidence graph, which is why every cell can carry a citation. A sensor layer watches every tool call for five kinds of loop or stall; it reminds first and re-dispatches from a different angle if the problem persists.

Installing SearchOS and running a first query from the terminal

The README gives a three-line quick run. The installer prepares the Python environment, the bundled Access Skill dependencies, Chromium, and the web frontend. Run it from the repository root, then activate the virtual environment it creates and pass a query to the searchos command.

./install.sh
source .venv/bin/activate
searchos "Top-5 universities per subject in the 2025 QS rankings, with application deadlines"

The first run launches a setup wizard. According to the README you pick a model provider (vendor coding plans, pay-as-you-go APIs, or local deployment), paste an API key, and you are running. Running searchos with no query opens the full-screen TUI, which the README says shows task dispatch, tool streams and the coverage map growing in real time. That TUI is built on Textual, which is a declared dependency.

Secrets go in a .env file copied from .env.example. That file is explicit that it holds only keys; every other setting lives in web_settings.json, written by the wizard, the web settings page, or TUI commands like /effort, /skill, /search and /config. The example lists provider variables including ZHIPU_API_KEY, KIMI_API_KEY, DASHSCOPE_API_KEY, ARK_API_KEY, DEEPSEEK_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY and OPENROUTER_API_KEY, plus search backends SERPER_API_KEY and TAVILY_API_KEY. Keep only the lines you use.

./web/start.sh

The README states this brings up the REST/WS API on port 8000 and the web frontend on port 3000, where you can launch searches from a browser and watch a live agent wall and coverage map. Note that langchain-anthropic is a core dependency rather than an optional extra, because the pyproject comments say vendor coding plans such as GLM, Kimi, MiniMax, Qwen and Doubao are reached through Anthropic-protocol endpoints.

Where SearchOS breaks: anti-bot walls, quotas, and the alpha label

The honest limitation is that SearchOS does not own the web. It reaches it through search backends and through skills, and the README's own framing of access skills is that they crack anti-bot and login-walled sites. That is a maintenance treadmill, not a solved problem. Any site that changes its bot detection breaks the corresponding skill, and the repository has no release history retrieved here, so there is no versioned changelog telling you when a skill last worked.

Quota is the second constraint. A recall-first dispatcher keeps targeting empty cells until they fill. On a question with a large entity set and a slow or expensive search backend, that is a cost profile you have to measure yourself. The README's evaluation claims are for WideSearch and GISA, including a Set F1 improvement of 13.4 over the next-best baseline on enumeration questions. Those are benchmark conditions with a fixed backend, not your backend.

The third is maturity. pyproject.toml sets version 0.1.0 and classifies the project as Development Status :: 3 - Alpha. The README does not document rollback for a corrupted evidence graph, and it does not document what happens when a run is interrupted mid-wave. It is also the wrong tool for a one-fact lookup: the coverage map, the evidence graph and the parallel dispatch are overhead when the answer is a single string, and a plain model call with web search will be cheaper and faster.

SearchOS compared with a general-purpose research agent

The nearest alternative in this space is a general-purpose deep-research agent, the kind that takes a question, plans a few sub-questions, browses, and writes a report. The difference is not quality, it is where the state lives and what the output is. A report-writing agent produces prose, and the failure mode is a confident paragraph with a weak citation somewhere in it. SearchOS produces a filled table whose empty cells are visible, with a source attached to each value by the extraction middleware.

That changes what you can do with the result. A table can be diffed against last week's run, exported, or checked cell by cell. A report cannot be checked without reading it. The trade-off is that SearchOS needs the question to have a relational shape. Ask it something that is genuinely one narrative answer and you have paid for a grid you do not need.

The other difference is provider posture. SearchOS treats multi-provider access as a first-class concern: the README says SF_PROVIDER connects any vendor in one line, and the .env.example enumerates roughly a dozen vendor key variables plus local deployment through Ollama or vLLM. If you are already committed to one vendor's agent product, that flexibility buys you nothing and you should stay where you are.

Licence, upgrade cost and what a version bump would touch

SearchOS is MIT licensed, and pyproject.toml declares license = "MIT" with the classifier OSI Approved :: MIT License. MIT is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and licence text travel with it. Note that the repository also carries a LEGAL.md at the top level, which the README does not explain. Read it before shipping anything derived from the access skills, since skills that interact with bot-protected sites can carry obligations the MIT grant over the Python code does not address. That is a question for your own counsel, not something this article can settle.

Upgrade cost is dominated by the state formats. SOCM holds the task queue, the evidence graph and the coverage map; if a future version changes the shape of any of those, saved sessions and any tooling you built on top of the exported evidence will need migration. The README does not describe a migration path. Because the project is at 0.1.0, pinning a specific commit is the safer default than tracking main, and the .env.example already gives you a clean seam for secrets: keys live in .env, everything else lives in web_settings.json.

There are no releases retrieved for this repository, so there is no published upgrade cadence to plan against. The last push was on 2026-07-22, which is the only recency signal available here.

Editorial conclusion

Adopt SearchOS if your questions are enumerable and you need per-cell citations: rankings, per-entity attribute tables, multi-hop lookups where a missing row is visible. Do not adopt it for single-fact lookups, for offline environments, or if you cannot attach a model API key, since the setup wizard and .env.example both assume a provider. Before committing, verify three things: that a full run finishes inside your search-backend quota, that the access skills actually clear the login-walled sites your domain depends on, and that the default provider connection in web_settings.json points at a model you are licensed to use. The repository is at version 0.1.0 and classifies itself as Development Status :: 3 - Alpha, so treat the coverage map and evidence graph formats as moving targets and pin a commit rather than tracking main.

Frequently asked questions

Official sources

1. antins-labs/SearchOS on GitHub
2. Issues
3. License: MIT
4. Project website
5. README