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.

What's new — 2026-11-04

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/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

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_tokens

ZONE_C_or_D_pruning_cost = 0 ← always zero cost net_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: . 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:

| 2,000 tok | 9,015 | 5,215