Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OSIRIS start a sealed task to fix the login bug and precheck any retries"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
Related MCP server: knitbrain
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…c21bThe 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.
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 AChange | Verdict | Cache Cost |
| CRITICAL DRIFT | Full re-prefill |
| Minor drift | Re-prefill delta only |
| Normal growth | Re-prefill delta only |
Pinned item rewritten | CRITICAL DRIFT (semantic) | Cache intact, task state corrupted |
Appending a constraint or decision changes
tail_hashbut notprefix_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).
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 |
| Start / update / resume / status of a task; produces sealed manifest | ~160 tok |
| Authorize or deny an action (invariants, budget, deduplication) | ~70 tok |
| Log actions, loop detection, offload large data, update memory | ~50 tok |
| Rehydrate refs (server-side filtered: grep, range, outline) | variable |
| Snapshot, resume, completion report, reversible compaction | ~80 tok |
| 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.
Call | Behavior |
| Drop receipt: agent confirms payload was evicted from prompt → token savings are proven and credited |
| Records system prompt head / client contract and detects cache-busting volatile tokens (timestamps, UUIDs) |
| Server-side filtering: only requested matches enter the context window |
| Context pressure breakdown (measured vs declared vs unknown) |
| Reversible session compaction preparation |
| Active collision resolution for duplicate operations |
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
┌──────────────────────────────────────────────────────────────┐
│ 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/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 costScopes: task → project → agent → global.
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 |
|
| C/D, and A/B only if cache expired | Neutral | Recommended default |
| Very high threshold | Working zone (C/D) only | Zero | High-cost API models |
| Moderate threshold | C/D + cold historical turns | Zero | Standard agent workflows |
| Low threshold | Everything rehydratable | Minor prefill risk | Fast local LLMs |
fingerprint = sha256(tool ‖ canonical_args ‖ result_signature)Detection | Trigger Signal | Verdict |
Exact duplicate | Identical fingerprint |
|
Repeated failure | Same error signature (≥3 times) |
|
Loop pattern | Same error across varying args |
|
Oscillation | Alternating A/B/A/B pattern |
|
Runaway | N calls with zero state progress |
|
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"OSIRIS guarantees full auditability for offloaded data:
Self-verifying refs: mem://sha256:<hash>. Reads re-verify data integrity against the hash before returning.
Zero deletion paths: data is relocated to the local store, never pruned permanently.
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": []}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.
cd D:\MCP-Osiris
uv venv --python 3.12 .venv
uv pip install --python .venv\Scripts\python.exe -e ".[dev]".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 benchmarksAdd 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"
}
}
}
}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)npx -y osiris-mcpThe 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.
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]"{
"mcpServers": {
"osiris": {
"command": "npx",
"args": ["-y", "osiris-mcp"],
"env": {
"OSIRIS_HOME": "~/.osiris",
"OSIRIS_ROOTS": "/path/to/project"
}
}
}
}Variable | Default | Role |
|
| SQLite database, reports, caches |
| (empty) | Roots allowed for file reading ( |
|
| Cache TTL (seconds) |
|
| Prune threshold |
|
|
|
MIT © 2026 Malik Belkacemi (MLKBLK-IT)
Snapshot d'etat, ou cloture avec rapport, ou compaction.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | snapshot | final | compact | trim | clear. | snapshot |
| label | No | Etiquette. | |
| task_id | No | Tache. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It mentions compaction and final closure but does not disclose whether those modes are destructive, whether they require required permissions, how they affect existing state, or what happens with trim/clear modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no redundant filler, and it puts the main mode outcomes up front. It is efficient, though its extreme brevity makes it cryptic rather than richly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has multiple modes, three parameters, no annotations, and an output schema. The description omits the trim and clear modes, gives no safety or usage context, and does not explain when each mode is appropriate, leaving important gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description only partially restates the mode values and adds no syntax, constraints, or meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names three possible outcomes: state snapshot, closure with report, and compaction. However, it is terse and does not fully clarify the tool's scope, especially the distinction between checkpointing and the trim/clear modes listed in the schema, nor how it differs from siblings like osiris.handoff or osiris.precheck.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It lists mode outcomes but does not say which situations should trigger a checkpoint, a final closure, or compaction, and it names no sibling tools or explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Contrat de delegation (create), ou son resultat (complete/collect).
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | create | complete | collect. | create |
| files | No | Fichiers. | |
| result | No | Resultat (JSON). | |
| mission | No | Mission du sous-agent. | |
| must_know | No | Faits indispensables (remplacent le contexte parent). | |
| handoff_id | No | Handoff vise. | |
| allowed_tools | No | Outils. | |
| budget_tokens | No | Budget tokens. | |
| forbidden_actions | No | Interdits. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, yet it discloses nothing about side effects, whether a handoff persists, who can complete or collect it, or what happens if a result is collected twice. The one genuinely important behavior (must_know replaces the parent context) lives only in the schema, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with no padding, so nothing is wasted — but it is under-specified rather than concise, and the highest-value information (the three modes and what each returns) is compressed into parentheses rather than front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter, three-mode orchestration tool with no annotations, this description is far too thin; an output schema excuses explaining return values, but nothing else is covered. An agent cannot tell from this text how a create/complete/collect cycle is supposed to be sequenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline of 3 applies even though the description adds no parameter detail. Note the schema descriptions themselves are mostly one-word glosses ('Outils.', 'Interdits.'), so the effective documentation is thinner than coverage suggests, but the description is not the right place to fix that here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (a delegation contract / handoff) and enumerates three modes (create, complete, collect), which is more than a tautology. But it is one terse French sentence that never states what a 'contrat de delegation' actually is or produces, and it gives no differentiation from siblings like osiris.plan or osiris.checkpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical mode mapping is the only usage signal; there is no statement of when to choose create vs complete vs collect, no prerequisites, and no mention of the sibling tools an agent should consider instead. The agent must infer the workflow from the parameter names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Consigne une action : doublons, boucles, externalisation.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Arguments (JSON). | |
| kind | No | tool_result | payload | file | decision | constraint | lesson | test_result | failure | note | contract | head | dropped. | tool_result |
| path | No | Chemin (kind=file). | |
| seal | No | Seal (ecart = derive). | |
| tool | No | Outil. | |
| result | No | Resultat (ou ref, pour kind=dropped). | |
| status | No | ok | error | skipped. | ok |
| context_tokens | No | Taille declaree de ton contexte (0 = inconnu). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, yet it says nothing about persistence, whether the call mutates stored state, what 'seal (ecart = derive)' implies, or any side effects. 'Consigne' hints at a write, but the agent gets no confirmation of durability, idempotency, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence is front-loaded, but it is under-specified rather than concise. For a tool with 11 enumerated kind values and specialized fields like seal and context_tokens, one cryptic line does not earn its place as the entire description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the schema documents all params. But with no annotations and an opaque one-liner, an agent still lacks the context to know when this tool applies or what recording an 'action' with duplicates/loops/externalization actually means.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every one of the 8 parameters is documented in the schema, establishing the baseline of 3. The description adds no additional parameter meaning — the words 'doublons, boucles, externalisation' are not mapped to any field such as kind or seal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Consigne' (records/logs) plus 'une action' gives a bare bones of purpose, but the qualifier 'doublons, boucles, externalisation' is cryptic jargon that does not explain what is actually recorded or why. It fails to distinguish this tool from siblings like osiris.checkpoint or osiris.handoff, which plausibly also persist state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to call this versus osiris.checkpoint, osiris.recall, or osiris.handoff, and no prerequisites or exclusions. The agent must guess from the tool name alone that this is for logging an observation after an action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tache : plan, manifeste scelle. start | update | resume | status.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | start | update | resume | status. | start |
| steps | No | Etapes. | |
| task_id | No | Tache a reprendre. | |
| objective | No | Objectif. | |
| constraints | No | Regles. | |
| context_tokens | No | Tokens du contexte (0 = inconnu). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. "Manifeste scelle" cryptically implies immutability/sealing of a written plan, which is a genuine behavioral hint, but there is nothing about side effects per mode, whether 'start' persists state, what 'resume' requires, or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single short line with no filler, and the task label is front-loaded. However, telegraphic fragments and untranslated jargon ("manifeste scelle") make it read as compressed rather than efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A six-parameter, four-mode lifecycle tool with no annotations needs to explain mode-dependent parameter applicability and write semantics; the description does none of that. The output schema covers return values, but the behavioral gap remains large for a stateful planning tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains all six parameters (mode, steps, task_id, objective, constraints, context_tokens). The description adds only the mode enumeration, which duplicates the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Tache : plan, manifeste scelle" largely restates the tool name and adds an unexplained metaphor ("sealed manifest"). The mode list (start | update | resume | status) hints at a lifecycle manager, but the description never states a concrete verb+resource or distinguishes it from siblings like osiris.checkpoint or osiris.handoff.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The four mode names are listed but no condition is given for choosing among them, and no guidance distinguishes this tool from osiris.precheck, osiris.observe, or osiris.checkpoint. An agent must guess which mode and which sibling to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verifie une action avant qu'elle parte : invariant, doublon, budget.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Arguments (JSON). | |
| action | No | Action (ex: git.commit). | |
| reason | No | Pourquoi. | |
| task_id | No | Tache (vide = tache courante). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does add real behavioral content by naming the three validations performed (invariant, duplicate, budget), but it never says whether the tool blocks the action, what a negative verdict means, or whether calling it has side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler; the core intent arrives immediately. It is arguably too terse rather than padded, so it does not lose points for verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the schema covers all parameters. What remains missing is the decision semantics of a gate tool: whether a failed precheck should abort the action and whether human approval is involved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (action, args, reason, task_id) are already documented in the schema and the baseline is 3. The description adds nothing beyond the schema, not even a note that 'action' is the field being checked.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: it verifies an action before dispatch, and enumerates the three check families (invariant, doublon, budget). An agent can tell this is a pre-execution gate rather than a logging or planning tool, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"avant qu'elle parte" implies the timing (before the action is dispatched), which is implicit usage guidance. There is no explicit when-not, no mention of what to do if the check fails, and no routing against siblings like osiris.plan or osiris.checkpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rehydrate un ref, ou restitue l'etat / la memoire d'une tache.
| Name | Required | Description | Default |
|---|---|---|---|
| op | No | Operation de selection cote serveur quand `ref` est fourni : excerpt | grep | range | head | tail | outline | aggregate | jsonl. | |
| end | No | Derniere ligne (inclusive) pour op=range. | |
| ref | No | Ref (mem://...). | |
| kind | No | Type de memoire. | |
| query | No | Filtre texte (extrait cible si un ref est fourni). | |
| scope | No | task | project | agent | global. | |
| start | No | Premiere ligne (1-based) pour op=range. | |
| task_id | No | Tache. | |
| budget_tokens | No | Budget tokens. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden but says nothing about whether this is a read or write operation, side effects, token-budget limits, or permission requirements. The op/scope/budget_tokens parameters suggest server-side selection and token capping, which are not mentioned. The only disclosed trait is that memory is restored/rehydrated, which is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single sentence with no waste, but it is under-specified rather than genuinely concise. The two modes are packed into one clause without explaining how they map to ref versus task_id usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A 9-parameter tool with no annotations and multiple selection operations (excerpt, grep, range, head, tail, outline, aggregate, jsonl) needs a richer description than one vague sentence. The presence of an output schema removes the need to explain return values, but the operational modes and interactions between ref/op/scope/task_id remain entirely unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema documents all 9 parameters including the op enum-like values, scope, range, and query. The description only hints at 'ref' and 'task', so it adds nothing beyond the schema. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives two modes: 'rehydrate a ref' or 'restores the state/memory of a task', which conveys the general intent of memory/state retrieval. However, 'rehydrate' is jargon and the relationship between the 'ref' path and 'task' path is unclear. It does not differentiate this tool from sibling tools like osiris.observe or osiris.checkpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this versus the other memory tools, nor any exclusions or prerequisites. The agent must infer that recalling memory is appropriate by reading the schema, not the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0osiris.checkpointosiris.handoffosiris.observeosiris.planosiris.precheckosiris.recallScored across 6 tools
The tools mostly map to distinct lifecycle phases: precheck before an action, observe after it, recall memory, checkpoint state snapshots/closure, handoff delegation, and plan task planning. Some boundary blur exists because checkpoint and recall both involve task state, and several tools bundle multiple sub-actions, but overall the purposes are separable.
All tools follow the same osiris.<single_lowercase_concept> pattern with no mixing of casing or verb styles. The convention is predictable and readable across the entire set.
Six tools is well-scoped for an agent governance/lifecycle server. Each tool corresponds to a meaningful phase or contract, and the count avoids both thinness and excessive surface area.
The set covers the core lifecycle: pre-action checks, observation, recall, checkpointing/closure, delegation handoff, and task planning. Minor gaps exist around explicit listing/inspection or cancellation operations, but agents can likely work around them through recall/status modes.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
