Osiris

[OSIRIS — Cache-aware context engine & state governor for AI agents]

OSIRIS

[PyPI] [npm] [Python] [License]

Cache-aware context engine & state governor for AI agents. Standard MCP server, local-first, independent of any model provider.

OSIRIS makes AI agents cheaper, faster, and more reliable: fewer tokens, fewer loops, zero unnecessary tools, and zero loss of context.

OSIRIS does not replace your other MCP servers (filesystem, Git, GitHub, shell, browser…). It coexists alongside them and drastically cuts what they cost in prompt context.

1. The Core Architectural Constraint

An MCP server never sees the final prompt assembled by the client host. It only sees what the agent sends to it. Therefore, OSIRIS cannot:

The promise is honest: OSIRIS provides stable state and an enforceable safety contract, not a client prompt builder.

2. Sealed Manifest — The Core Design

osiris.plan returns a deterministic block (~120 tokens) that the agent carries at a fixed position in its context window:

OSIRIS/1 task=7c3f obj="fix PowerShell profile bug" plan=3/7inv=4 files=6 refs=9 dec=2 budget=okSEAL=sha256:3f9a1c…c21b

The SEAL is a SHA256 digest of stable zones. The agent passes it on every turn to osiris.observe: OSIRIS recomputes and detects any state drift immediately.

This is OSIRIS's passive transport: even if the agent stops calling tools, it carries the essential state cleanly.

Three Hashes Because Prompt Cache is Prefix-Based

head_hash   = sha256(system_head ‖ rules)                       immutablezoneB_hash  = sha256(objective ‖ global_plan ‖ tool_contract)   quasi-stabletail_hash   = sha256(constraints ‖ pinned_decisions)           append-onlyprefix_hash = sha256(head_hash ‖ zoneB_hash)                   ← cached prefixzoneA_hash  = sha256(head_hash ‖ tail_hash)                    ← full ZONE A

Appending a constraint or decision changes tail_hash but not prefix_hash: the prompt cache holds, only the new tokens are prefilled.

Rewriting a pinned decision is explicitly caught: OSIRIS checks collection identity, flagging a semantic break (semantic_break: true, cause: pinned_rewrite).

3. The 6 MCP Tools

Access footprint: 1,019 tokens of schemas and descriptions in model context (measured via bench/run_bench.py). Paid on task start, amortized across the session — pays off on the very first turn with ≥800 token payloads.

osiris.observe combines logging, loop protection, payload externalization, memory registry, and automated pruning in a single call so the agent always reports back seamlessly.

Extended Operations

Resources & Prompts

• osiris://task/{task_id}/manifest — Active zones, drift status, objective
• osiris://task/{task_id}/status — Real-time context pressure
• osiris://ref/{ref} — Raw byte content of any referenced payload
• Prompt osiris/task-resume — Clean agent recovery template after crashes

4. Architecture

┌──────────────────────────────────────────────────────────────┐│  Agent (Claude Code, Cursor, MiniMax Code, Codex, Cline…)   ││  Context: system │ tools │ OSIRIS MANIFEST │ history         │└───────────────────────────┬──────────────────────────────────┘                            │  MCP stdio — 6 tools, ~1,019 tok schema                            ▼┌──────────────────────────────────────────────────────────────┐│  osiris-mcp  (server.py)                                     ││  plan · precheck · observe · recall · checkpoint · handoff   │└───────────────────────────┬──────────────────────────────────┘                            │┌───────────────────────────▼──────────────────────────────────┐│  core/                                                        ││   task_state  Typed TaskState (objective, plan, decisions)    ││   memory     Typed memory registry by kind and scope         ││   refs       Content-addressed store (verified on read)      ││   prefix     Zones, 3-hash system, drift, PrefillPlan        ││   prune      Reversible externalization, 4 modes             ││   query      Server-side payload filtering (grep, range...)  ││   compaction trim / compact / clear (lossless)               ││   pressure   Context pressure metrics & tracking             ││   loopguard  Fingerprinting, 5 loop patterns detection       ││   invariants TOML rule engine (guard rails)                  ││   compass    Tool Compass (dynamic relevance scoring)        ││   handoff    Executable agent delegation contracts           ││   events     Append-only event journal + checkpoints         ││   ledger     Tokens / cost / savings / OSIRIS overhead       ││   fileops    Sandboxed file inspection (roots, size limits)  ││   redact     Secret scrubbing before any hashing             ││   policy     Budget policies & token enforcement             │└───────────────────────────┬──────────────────────────────────┘                            ▼        ~/.osiris/osiris.db  +  ~/.osiris/reports/

5. Memory Model

Deterministic, typed, content-addressable memory — not an opaque vector database.

TaskState├── objective      immutable├── constraints[]  append-only├── decisions[]    append-only, pinned verbatim├── plan           completed / active / remaining steps├── files{}        path, SHA-256 hash, mtime, last access, ref├── tool_results{} cache_key, ref, size, token cost, TTL├── failures{}     error signature, tool, args hash, attempts, lesson├── lessons[]      general behavioral rules learned├── handoffs{}     cross-agent delegation contracts└── budget         estimated vs consumed tokens and cost

Scopes: task → project → agent → global.

6. Cache-Aware Pruning

Security Invariant: Pruning moves payload data to content-addressed refs (mem://sha256:…). It NEVER deletes.

ZONE_A_pruning_cost = pruned_tokensZONE_C_or_D_pruning_cost = 0                      ← always zero costnet_savings = pruned_tokens − (prefix_tokens × P(cache_dead) × prefix_pruned)

7. LoopGuard Protection

fingerprint = sha256(tool ‖ canonical_args ‖ result_signature)

8. Invariants (Guard Rails)

Define project safety rules in .osiris/invariants.toml:

[[invariant]]id = "tests-before-commit"when = { tool = "git.commit" }require = { state = "tests_passed" }message = "Cannot commit while tests are failing"
[[invariant]]id = "no-test-edit"when = { path_glob = "tests/**" }verdict = "block"message = "Modifying test suites requires explicit approval"

9. Lossless Verification & Non-Loss Proof

OSIRIS guarantees full auditability for offloaded data:

1. Self-verifying refs: mem://sha256:<hash>. Reads re-verify data integrity against the hash before returning.
2. Zero deletion paths: data is relocated to the local store, never pruned permanently.
3. Reproducible audit:
   bash

   python -m osiris audit --task <task_id>

   Outputs cryptographic proof of non-loss:
   json

   {"lossless": true, "items_externalized": 14, "items_verified": 14, "items_missing": 0, "integrity_violations": []}

10. Verified Benchmarks

Real measurements from python bench\run_bench.py running an automated coding workflow:

• Access Cost: 1,019 tokens of schemas, amortized across session tasks.
• Session Net Gate: PASS (Worst-case net across full suite: +951 tokens).
• At 20,000 tokens: +71.46% net savings on context usage.

11. Quick Start

cd D:\MCP-Osirisuv venv --python 3.12 .venvuv pip install --python .venv\Scripts\python.exe -e ".[dev]"

CLI Verification

.venv\Scripts\python.exe -m pytest tests -q        # Run test suite (77 passed).venv\Scripts\python.exe -m ruff check src tests    # Code linting.venv\Scripts\python.exe -m osiris health           # Server health check.venv\Scripts\python.exe -m osiris audit --task t_1 # Cryptographic non-loss proof.venv\Scripts\python.exe bench\run_bench.py         # Reproduce benchmarks

Registration as MCP Server

Add to your client configuration (mcp.json):

{  "mcpServers": {    "osiris": {      "command": "D:\\mcp-osiris\\.venv\\Scripts\\python.exe",      "args": ["-m", "osiris"],      "env": {        "OSIRIS_HOME": "C:\\Users\\Tech\\.osiris",        "OSIRIS_ROOTS": "D:\\mcp-osiris"      }    }  }}

12. Installation

From PyPI (recommended)

pip install mcp-osiris          # or: uv pip install mcp-osirismcp-osiris                      # runs the MCP server on stdioosiris health                   # CLI verificationosiris-dashboard --port 8770    # Control Plane (dashboard)

From npm (no Python setup)

npx -y osiris-mcp

The npm package is a stdio launcher. It resolves the Python runtime in this order — OSIRIS_PYTHON → uvx → python3 → python — and runs the PyPI package mcp-osiris.

From source

git clone https://github.com/MlkBlk-IT/osiris.gitcd osirisuv venv --python 3.12 .venvuv pip install --python .venv\Scripts\python.exe -e ".[dev]"

MCP client configuration

{  "mcpServers": {    "osiris": {      "command": "npx",      "args": ["-y", "osiris-mcp"],      "env": {        "OSIRIS_HOME": "~/.osiris",        "OSIRIS_ROOTS": "/path/to/project"      }    }  }}

License

MIT © 2026 Malik Belkacemi (MLKBLK-IT)