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