Open-source tool · Agent memory and context engineering

ContextOS: memory, retrieval routing and context reasoning for agents

ContextOS is a Python MCP server and CLI that gives AI agents memory, routes retrieval by how fast data changes and adds a reasoning step between retrieval and generation. A companion benchmark tests markdown memory against RAG and graph approaches.

ContextOS on GitHub ↗Benchmark on GitHub ↗Preprint on Zenodo ↗

Project: ContextOS v0.2.0
Built: Mar 2026
Code: Public on GitHub, install from source
Stack: Python, MCP, BM25, vector search, GraphRAG
Research: Preprint on Zenodo, Mar 2026

The idea

Agent frameworks retrieve context and generate answers, but they rarely reason about what they retrieved. Memory, retrieval, planning and orchestration usually live in separate projects.

At the same time, the industry is settling on markdown files such as llms.txt as memory for language models, without much testing of how that holds up on complex, multi-step questions.

The work

How we built it, step by step

Built the memory and tool layerContextOS exposes 67 MCP tools in 8 groups: memory, retrieval, cognition, router, indexer, planning, orchestration and document intelligence. It builds on several open-source projects and credits them in the README.
Routed retrieval by data churnThe Retrieval Router sorts sources into live, warm and cold. Live data is pulled from the API, warm data uses BM25 or vector search with freshness, and cold data uses full vector search.
Kept indexes currentThe Index Lifecycle Manager re-indexes on write, detects embedding model drift, quarantines schema changes and uses circuit breakers and heartbeats.
Added a cognition layerVersion 0.2.0 adds 6 primitives, including active forgetting, reasoning-depth calibration and productive contradiction, that run between retrieval and generation.
Designed the Markdown Fallacy BenchmarkThe benchmark compares flat markdown, vector RAG, GraphRAG and a hybrid on a synthetic Google Ads MCC portfolio of 3 accounts and 15 campaigns. It uses 50 queries at 3 levels of difficulty across Claude Sonnet, GPT-4o and Gemini Flash.
Published the methodScoring is deterministic, with inter-rater scripts included. The preprint is on Zenodo; the repo shows the method and predicted results, not measured ones.

What it does

67 MCP tools in 8 groups
Churn-aware retrieval router
Index lifecycle management with drift detection
6 cognition primitives
Google Ads MCP as an example source
Benchmark harness for markdown vs RAG vs GraphRAG
CITATION.cff and wiki

How people find it

Public GitHub repo, install from source (not on PyPI)
MCP server for Claude, Cursor and other clients
Zenodo preprint with DOI
Docker compose for the benchmark

Questions

Questions people ask about this work

Is markdown or llms.txt good enough as memory for an AI agent?

That is the question our benchmark is built to test, comparing flat markdown with vector RAG, GraphRAG and a hybrid on multi-step Google Ads questions. The repo publishes the method and predicted results, not measured results yet. The preprint is on Zenodo.

How do I give an AI agent long-term memory with MCP?

Run a memory server that the agent calls as tools. ContextOS provides memory, retrieval and planning tools over MCP. Install it from the GitHub repo, since it is not on PyPI.

What is churn-aware retrieval?

It means choosing how to fetch data based on how often it changes. ContextOS pulls fast-changing data straight from the API, uses search with a freshness signal for data that changes sometimes and uses full vector search for stable data.

Services in this project

AI implementation AI search optimization

More work