Osiris
Context governor for coding agents: sealed task state, loop guard and payload offloading
The repository was last updated 12 days ago and is published under MIT.
- Pricing
- Open source
- Platforms
- CLI, self-hosted, macOS
- Runs
- Locally
- GitHub stars
- 2
- Last commit
- 12 days ago
- Language
- Python
Similar MCP servers
About Osiris
Osiris is an open-source MCP server for ai models and llm tooling. It runs locally on your machine and is started by your AI client.
OSIRIS starts from an honest constraint: an MCP server never sees the final prompt, only what the agent sends it. So instead of editing the prompt, it produces a short deterministic manifest of about 120 tokens that the agent carries, sealed with a SHA-256 digest. On each turn the agent passes the seal back, and a mismatch reveals state drift. Separate hashes for head, plan and tail zones show whether a change breaks the prompt cache or merely appends.
Six tools cover the loop: plan, precheck, observe, recall, checkpoint and handoff. Large payloads are stored by reference and recalled with server-side grep, range, head, tail, outline, aggregate or jsonl filters so only matches reach the context. Other modules detect repeated-action loops (warn at 3, block at 5), enforce invariants from a TOML file, scrub secrets before hashing and keep a ledger of tokens, cost and savings. The tool schemas cost about 1,019 tokens.
It is local-first and independent of any model provider, stores state in SQLite under ~/.osiris, and is published on npm (osiris-mcp) and PyPI (mcp-osiris). It works alongside other MCP servers rather than replacing them.
Install
Run in a terminal
claude mcp add osiris -- npx -y osiris-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"osiris": {
"command": "npx",
"args": [
"-y",
"osiris-mcp"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"osiris": {
"command": "npx",
"args": [
"-y",
"osiris-mcp"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"osiris": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"osiris-mcp"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"osiris": {
"command": "npx",
"args": [
"-y",
"osiris-mcp"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"osiris": {
"command": "npx",
"args": [
"-y",
"osiris-mcp"
]
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
OSIRIS_HOMERepertoire d'etat OSIRIS : base SQLite, rapports, caches. Defaut ~/.osiris.OSIRIS_ROOTSRacines autorisees pour la lecture de fichiers, separees par ';'. Vide = aucune lecture de fichier.OSIRIS_CACHE_TTL_STTL du cache en secondes.OSIRIS_PRUNE_THRESHOLD_TOKENSSeuil de prune en tokens.OSIRIS_DISPATCH_ONLY1 = n'expose que l'outil osiris.call (table d'outils stable pour le prefix cache).
Tools this server provides (6)
Taken from the project documentation; the running server may differ.
- osiris.plan
- Starts, updates, resumes or reports on a task and returns the sealed manifest.
- osiris.precheck
- Authorizes or denies an action against invariants and budget.
- osiris.observe
- Logs actions, detects loops and offloads large data.
- osiris.recall
- Rehydrates references with server-side filtering.
- osiris.checkpoint
- Snapshots, resumes and compacts a session.
- osiris.handoff
- Creates delegation contracts and structured results.
What it does
- Sealed manifest
- A small SHA-256-sealed state block that exposes drift.
- Cache-aware hashing
- Tells cache-breaking changes from harmless appends.
- Server-side recall
- Filters stored payloads with grep, range, outline and more.
- Loop guard
- Detects repeated actions and escalates from warning to block.
- Invariants and budgets
- Allows or denies actions based on rules and budgets.
- Honest ledger
- Records tokens, cost, savings and its own overhead.
- Delegation contracts
- Hands off tasks with executable contracts and structured results.
Good for
- Keep a long coding task consistent across context resets
- Cut token use from large tool outputs
- Stop an agent repeating the same failing action
- Hand a subtask to another agent with a clear contract
Pricing
Open source
License badge in the repository; free to run locally.
Osiris FAQ
Does it replace other MCP servers?
No. It coexists with servers such as filesystem, Git and shell and reduces what they cost in context.
Can it edit my prompt?
No. The README says an MCP server cannot see or rewrite the final prompt; it provides state the agent carries.
How many tools does it expose?
Six: plan, precheck, observe, recall, checkpoint and handoff.
Where does it keep data?
In ~/.osiris by default, set with OSIRIS_HOME, using SQLite.
Is Osiris free?
Yes. Osiris is open source, so you can use and self-host it for free.
How do I add Osiris to Claude Code?
Run this command in your terminal: claude mcp add osiris -- npx -y osiris-mcp
What are the best alternatives to Osiris?
The closest alternatives to Osiris are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.


