MCP

Use MCP when you want Claude Code, Cursor, or another MCP client to expose Aionis tools without rewriting the host Agent loop first.

For Claude Code, prefer the Claude Code lifecycle integration when you want Aionis to run automatically before prompts and after tool use. MCP remains the interactive tool bridge.

The main product surface here is Execution Memory. aionis_context compiles the accepted route, blocked/reference-only branches, rehydrate pointers, and receipt metadata into an Agent-facing contract. aionis_govern_memory is the separate Memory Firewall path for hosts that already have candidates from Mem0, Zep, vector DBs, markdown, logs, or another backend.


npx @aionis/mcp@latest \
  --base-url http://127.0.0.1:3001 \
  --scope-from workspace \
  --workspace-id-store user

The MCP bridge talks to a running Aionis Runtime and exposes a small set of tools for execution memory, external memory governance, measurement, and replay.

Claude Code Example


/plugin marketplace add https://github.com/ostinatocc/aionis-claude-code
/plugin install aionis@aionis-claude-code
/aionis:doctor

The plugin gives Claude Code MCP tools plus lifecycle hooks. Use raw MCP only for hosts that do not support Claude Code plugins:


claude mcp add --transport stdio --scope project aionis -- \
  npx -y @aionis/mcp@latest \
  --base-url http://127.0.0.1:3001 \
  --scope-from workspace \
  --workspace-id-store user

Available Tools

Tool	Purpose
`aionis_context`	Compile governed execution memory for the current Agent turn.
`aionis_record_step`	Record a planner/worker/verifier/reviewer step and optional feedback.
`aionis_handoff`	Record branch-aware handoff for cross-session continuation.
`aionis_remember`	Store ordinary project memory.
`aionis_govern_memory`	Govern external memory candidates through admission surfaces.
`aionis_measure`	Measure guide and feedback impact for a run.
`aionis_snapshot`	Return an operator snapshot.
`aionis_flight_recorder`	Replay what memory the Agent could see at decision time.
`aionis_health`	Check Runtime reachability.

Typical Coding-Agent Flow

Call aionis_context before a task turn to get governed context.
Run the Agent with the returned context.
Call aionis_record_step after meaningful actions or verifier results.
Call aionis_handoff at session boundaries.
Call aionis_measure and aionis_snapshot for operator review.

For the smallest useful trial, run only:


aionis_context -> Agent action

For a better demo, add:


aionis_context -> Agent action -> aionis_record_step -> aionis_flight_recorder

`aionis_context`

Use this when the Agent asks “what should I know before continuing?”


{
  "run_id": "run-001",
  "task_signature": "checkout-migration",
  "agent_id": "worker-1",
  "role": "worker",
  "query_text": "Continue the checkout migration from the accepted path.",
  "context_mode": "compact_agent",
  "repo_state": {
    "existing_files": ["src/checkout/adapter.ts"],
    "missing_files": ["src/checkout/bundledDev.ts"]
  }
}

The repo_state field is optional but useful. It lets Aionis render missing active targets as pending work instead of letting the Agent silently fall back to old files.

`aionis_record_step`

Use this after tool calls, test runs, verifier results, or branch decisions.


{
  "run_id": "run-001",
  "task_signature": "checkout-migration",
  "agent_id": "verifier-1",
  "role": "verifier",
  "title": "Verifier rejected legacy route",
  "summary": "The legacy adapter touched unrelated modules.",
  "outcome": "failed",
  "target_files": ["src/checkout/legacyAdapter.ts"]
}

MCP Boundary

MCP is a bridge. Your MCP client owns the Agent loop and tool execution. Aionis owns memory governance and audit surfaces. Claude Code hooks add the lifecycle layer when you need automatic context injection and execution recording.

Guide: AIONIS_MCP.md .