osiris

OSIRIS

面向 AI Agent 的缓存感知型上下文引擎和状态管理器。 标准 MCP 服务，本地优先，独立于任何模型提供商。

OSIRIS 让 AI Agent 更省钱、更快速、更可靠：减少令牌、减少循环、避免不必要的工具调用，并且不会丢失上下文。

OSIRIS 不会取代你的其他 MCP 服务（文件系统、Git、GitHub、shell、浏览器……）。它会与这些服务共存，大幅降低它们占用的提示词上下文成本。

---

1. 核心架构限制

MCP 服务永远无法看到客户端宿主组装的最终提示词。它只能看到 Agent 发给它的内容。因此，OSIRIS 无法：

我们希望实现的功能	标准 MCP 服务实际能做的事
直接写入提示词	生成规范状态，并由 Agent 携带
擦除之前的对话轮次	决定为后续轮次外置哪些内容
隐藏其他 MCP 服务的工具	通过 Tool Compass 提供建议
对提示词令牌数设定硬上限	阻止某个操作（不变量、预算执行）

OSIRIS 的承诺实事求是：它提供稳定状态和可强制执行的安全约定，而不是客户端提示词构建器。

---

2. 密封清单——核心设计

osiris.plan 会返回一个确定性区块（约 120 个令牌），由 Agent 携带，并放在上下文窗口中的固定位置：

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

SEAL 是稳定区域的 SHA256 摘要。Agent 每轮都会将它传递给 osiris.observe：OSIRIS 会重新计算并立即检测任何状态漂移。

这是 OSIRIS 的被动传输机制：即使 Agent 停止调用工具，也能完整携带关键状态。

使用三个哈希，因为提示词缓存基于前缀

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

变化	判定	缓存成本
head_hash	严重漂移	完整重新预填充
zoneB_hash	轻微漂移	仅重新预填充增量
tail_hash（追加）	正常增长	仅重新预填充增量
重写固定项	严重漂移（语义层面）	缓存完好，任务状态损坏

追加约束或决策会改变 tail_hash，但不会改变 prefix_hash：提示词缓存保持不变，只需预填充新令牌。

重写固定决策会被明确捕获：OSIRIS 会检查集合身份，并标记语义中断（semantic_break: true、cause: pinned_rewrite）。

---

3. 6 个 MCP 工具

上下文占用：模型上下文中的架构和描述共 1,019 个令牌（通过 bench/run_bench.py 测得）。在任务开始时支付，并在整个会话中摊销——只要负载达到 ≥800 个令牌，首次交互就能回本。

工具	作用	典型响应
osiris.plan	启动 / 更新 / 恢复任务；查看任务状态；生成密封清单	~160 tok
osiris.precheck	授权或拒绝操作（不变量、预算、去重）	~70 tok
osiris.observe	记录操作、检测循环、卸载大型数据、更新记忆	~50 tok
osiris.recall	重新载入引用（在服务端过滤：grep、范围、提纲）	不定
osiris.checkpoint	快照、恢复、完成报告、可逆压缩	~80 tok
osiris.handoff	可执行的委派契约和结构化结果	~200 tok

osiris.observe 将日志记录、循环防护、负载外置、记忆注册和自动裁剪整合到一次调用中，让 Agent 始终能无缝汇报。

扩展操作

调用	行为
osiris.observe(kind="dropped", result=<ref>)	丢弃回执：Agent 确认负载已从提示词中移除 → 可证实令牌节省量并计入收益
osiris.observe(kind="head"|"contract", result=…)	记录系统提示词头部 / 客户端契约，并检测会破坏缓存的易变令牌（时间戳、UUID）
osiris.recall(op="grep"|"range"|"head"|"tail"|"outline"|"aggregate"|"jsonl")	在服务端过滤：只有请求的匹配项才会进入上下文窗口
osiris.plan(mode="status")	上下文压力细分（实测值、声明值与未知值）
osiris.checkpoint(mode="compact"|"trim"|"clear")	可逆的会话压缩准备
osiris.precheck → suggest_alternative	对重复操作进行主动冲突解决

资源与提示词

• osiris://task/{task_id}/manifest — 活动区域、偏移状态、目标
• osiris://task/{task_id}/status — 实时上下文压力
• osiris://ref/{ref} — 任意引用负载的原始字节内容
• 提示词 osiris/task-resume — 崩溃后用于干净恢复 Agent 的模板

---

4. 架构

┌──────────────────────────────────────────────────────────────┐
│  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. 记忆模型

确定性、带类型、内容寻址的记忆——不是不透明的向量数据库。

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

作用域：task → project → agent → global。

---

6. 缓存感知裁剪

安全不变量：裁剪会将负载数据移至内容寻址引用（mem://sha256:…）。绝不会删除数据。

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)

模式	触发条件	移出内容	缓存影响	使用场景
cache_ttl（默认）	Δt > TTL	C/D；仅当缓存过期时移出 A/B	中性	建议作为默认选项
conservative	极高阈值	仅工作区（C/D）	无	高成本 API 模型
balanced	中等阈值	C/D + 冷历史轮次	无	标准 Agent 工作流
aggressive	低阈值	所有可重新载入的内容	轻微预填充风险	快速本地大模型

---

7. LoopGuard 防护

fingerprint = sha256(tool ‖ canonical_args ‖ result_signature)

检测类型	触发信号	判定
完全重复	指纹相同	suggest_alternative
重复失败	错误特征相同（≥3 次）	block + required_action
循环模式	参数不同但错误相同	warn
振荡	A/B/A/B 交替模式	warn
失控	N 次调用且状态毫无进展	warn / block

---

8. 不变量（防护栏）

在 .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. 无损验证与无损证明

OSIRIS 可确保所有卸载数据都完全可审计：

1. 自验证引用：mem://sha256:<hash>。读取数据时，会先根据哈希重新验证其完整性，再返回数据。
2. 零删除路径：数据会迁移到本地存储，不会被永久清除。
3. 可复现审计：

   python -m osiris audit --task <task_id>
   

   输出无损的加密证明：

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

---

10. 已验证的基准测试

使用 python bench\run_bench.py 运行自动化编码工作流得出的实际测量结果：

负载大小	基线上下文	固定模式 OSIRIS	自适应模式 OSIRIS	净提升	OSIRIS 模式	开销
200 tok	1,583	2,687	1,651	−4.30%	旁观	34 tok
800 tok	3,851	3,755	3,261	+15.32%	轻量	1,810 tok
2,000 tok	9,015	5,229	5,233	+41.95%	标准	2,492 tok
5,000 tok	20,979	8,171	8,168	+61.07%	标准	2,439 tok
20,000 tok	82,135	23,427	23,440	+71.46%	完整	2,422 tok

• 访问成本：1,019 个 token 的架构定义，会在整个会话的任务间分摊。
• 会话净收益门槛：通过（完整测试套件中最差情况下的净收益：+951 个 token）。
• 在 20,000 个 token 时：上下文用量净节省 +71.46%。

---

11. 快速开始

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

CLI 验证

.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

注册为 MCP 服务

将以下内容添加到客户端配置（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. 安装

从 PyPI 安装（推荐）

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)

从 npm 安装（无需配置 Python）

npx -y osiris-mcp

npm 包是一个 stdio 启动器。它会按以下顺序解析 Python 运行时：OSIRIS_PYTHON → uvx → python3 → python，并运行 PyPI 包 mcp-osiris。

从源代码安装

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 客户端配置

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

变量	默认值	作用
OSIRIS_HOME	~/.osiris	SQLite 数据库、报告、缓存
OSIRIS_ROOTS	(空)	允许读取文件的根目录（以 ; 分隔）
OSIRIS_CACHE_TTL_S	300	缓存 TTL（秒）
OSIRIS_PRUNE_THRESHOLD_TOKENS	40000	清理阈值
OSIRIS_DISPATCH_ONLY	0	1 → 仅公开 osiris.call

---

许可证

MIT © 2026 Malik Belkacemi (MLKBLK-IT)