osiris

OSIRIS

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:

What we would want	What a standard MCP server can actually do
Write directly into the prompt	Produce canonical state and have the agent carry it
Erase past conversation turns	Decide what to externalize for future turns
Hide another MCP server's tools	Recommend via Tool Compass
Hard-cap prompt tokens	Block an action (invariants, budget enforcement)

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/7
inv=4 files=6 refs=9 dec=2 budget=ok
SEAL=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)                       immutable
zoneB_hash  = sha256(objective ‖ global_plan ‖ tool_contract)   quasi-stable
tail_hash   = sha256(constraints ‖ pinned_decisions)           append-only
prefix_hash = sha256(head_hash ‖ zoneB_hash)                   ← cached prefix
zoneA_hash  = sha256(head_hash ‖ tail_hash)                    ← full ZONE A

Change	Verdict	Cache Cost
head_hash	CRITICAL DRIFT	Full re-prefill
zoneB_hash	Minor drift	Re-prefill delta only
tail_hash (append)	Normal growth	Re-prefill delta only
Pinned item rewritten	CRITICAL DRIFT (semantic)	Cache intact, task state corrupted

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.

Tool	Role	Typical Response
osiris.plan	Start / update / resume / status of a task; produces sealed manifest	~160 tok
osiris.precheck	Authorize or deny an action (invariants, budget, deduplication)	~70 tok
osiris.observe	Log actions, loop detection, offload large data, update memory	~50 tok
osiris.recall	Rehydrate refs (server-side filtered: grep, range, outline)	variable
osiris.checkpoint	Snapshot, resume, completion report, reversible compaction	~80 tok
osiris.handoff	Executable delegation contracts and structured results	~200 tok

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

Call	Behavior
osiris.observe(kind="dropped", result=<ref>)	Drop receipt: agent confirms payload was evicted from prompt → token savings are proven and credited
osiris.observe(kind="head"|"contract", result=…)	Records system prompt head / client contract and detects cache-busting volatile tokens (timestamps, UUIDs)
osiris.recall(op="grep"|"range"|"head"|"tail"|"outline"|"aggregate"|"jsonl")	Server-side filtering: only requested matches enter the context window
osiris.plan(mode="status")	Context pressure breakdown (measured vs declared vs unknown)
osiris.checkpoint(mode="compact"|"trim"|"clear")	Reversible session compaction preparation
osiris.precheck → suggest_alternative	Active collision resolution for duplicate 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_tokens
ZONE_C_or_D_pruning_cost = 0                      ← always zero cost
net_savings = pruned_tokens − (prefix_tokens × P(cache_dead) × prefix_pruned)

Mode	Trigger	Evicts	Cache Impact	Use Case
cache_ttl (default)	Δt > TTL	C/D, and A/B only if cache expired	Neutral	Recommended default
conservative	Very high threshold	Working zone (C/D) only	Zero	High-cost API models
balanced	Moderate threshold	C/D + cold historical turns	Zero	Standard agent workflows
aggressive	Low threshold	Everything rehydratable	Minor prefill risk	Fast local LLMs

---

7. LoopGuard Protection

fingerprint = sha256(tool ‖ canonical_args ‖ result_signature)

Detection	Trigger Signal	Verdict
Exact duplicate	Identical fingerprint	suggest_alternative
Repeated failure	Same error signature (≥3 times)	block + required_action
Loop pattern	Same error across varying args	warn
Oscillation	Alternating A/B/A/B pattern	warn
Runaway	N calls with zero state progress	warn / block

---

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:

   python -m osiris audit --task <task_id>
   

   Outputs cryptographic proof of non-loss:

   {"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:

Payload Size	Baseline Context	Fixed OSIRIS	Adaptive OSIRIS	Net Improvement	OSIRIS Mode	Overhead
200 tok	1,583	2,687	1,651	−4.30%	bystander	34 tok
800 tok	3,851	3,755	3,261	+15.32%	light	1,810 tok
2,000 tok	9,015	5,229	5,233	+41.95%	standard	2,492 tok
5,000 tok	20,979	8,171	8,168	+61.07%	standard	2,439 tok
20,000 tok	82,135	23,427	23,440	+71.46%	full	2,422 tok

• 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-Osiris
uv venv --python 3.12 .venv
uv 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-osiris
mcp-osiris                      # runs the MCP server on stdio
osiris health                   # CLI verification
osiris-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.git
cd osiris
uv venv --python 3.12 .venv
uv 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"
      }
    }
  }
}

Variable	Default	Role
OSIRIS_HOME	~/.osiris	SQLite database, reports, caches
OSIRIS_ROOTS	(empty)	Roots allowed for file reading (; separated)
OSIRIS_CACHE_TTL_S	300	Cache TTL (seconds)
OSIRIS_PRUNE_THRESHOLD_TOKENS	40000	Prune threshold
OSIRIS_DISPATCH_ONLY	0	1 → exposes only osiris.call

---

License

MIT © 2026 Malik Belkacemi (MLKBLK-IT)