@aionis/mcp

MCP stdio bridge for Aionis execution memory.

Docs: https://docs.aionis.work/integrations/mcp

Use this package when you want Claude Code, Cursor, or another MCP client to try Aionis without rewriting the host Agent loop first. MCP is the fastest public trial path for Aionis Execution Memory: connect the bridge, call aionis_context, and let the Agent continue from governed state instead of raw chat history.

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

Start a local Runtime first:

npx @aionis/create@latest
cd Aionis
npm run -s lite:start

Environment form:

AIONIS_BASE_URL=http://127.0.0.1:3001 \
AIONIS_TENANT_ID=default \
AIONIS_SCOPE_FROM=workspace \
npx @aionis/mcp@latest

Use --scope my-project when your host already knows the exact memory boundary. Use --scope-from workspace for coding-agent clients so Aionis derives a stable project scope from .aionis/workspace.json. If the MCP client launches outside the repo, add --repo-root /absolute/path/to/repo. Git root, git remote, and cwd identities are stored as aliases for the same ws:<name>:<id> scope, so starting from a non-git directory and running git init later does not split the execution memory boundary.

Tools

The server exposes stable product tools, not internal Runtime packets:

aionis_context is compiler-first. It calls Runtime guide through the SDK, then renders the same aionis_execution_agent_context_v1 contract that SDK users get from compileExecutionAgentContext(). The top-level agent_prompt field is kept for MCP clients that only want prompt text; richer clients should read structuredContent.execution_context.

It accepts context_mode: "compact_agent" when an MCP client needs a shorter Runtime guide, and budget_profile, max_prompt_chars, repo_state, and additional_instructions when the host can provide execution-environment facts. For example, pass repo_state.missing_files so Aionis can tell the Agent that a missing active target is pending work rather than stale memory.

For Claude Code or Cursor demos, the recommended first loop is:

aionis_context -> Agent action -> aionis_record_step -> aionis_flight_recorder

Use this flow:

1. Use aionis_record_step as a planner to record the accepted plan, active targets, acceptance checks, and execution boundary.

2. Use aionis_record_step again for any rejected branch as outcome: "failed" with the rejected target files.

3. Ask aionis_context for the worker/reviewer context before implementation.

4. Use aionis_flight_recorder after the run to replay which plan memories and failed branches were visible at decision time.

This is the MCP shape of Aionis Plan as Memory Asset: the MCP client can use a strong planner once, then let later workers continue from adjudicated execution memory instead of raw chat history.

The tool returns these structured fields in structuredContent:

Use aionis_govern_memory when an MCP client already has memories from Mem0, Zep, Supermemory, Pinecone, pgvector, Chroma, Weaviate, LangGraph Store, markdown, logs, or another backend and needs Aionis to decide which ones may direct the Agent:

{
  "query_text": "Continue without reusing failed branches.",
  "mode": "firewall",
  "candidates": [
    {
      "external_memory_id": "mem0:current",
      "source_backend": "mem0",
      "text": "Current accepted target is packages/api/src/checkout.ts.",
      "authority": {
        "source_trust": "trusted",
        "scope": "project",
        "evidence_requirement": "none"
      },
      "lifecycle_hint": "current"
    }
  ]
}

Use aionis_flight_recorder after a run to inspect the read-only incident replay report. The report includes memory IDs and attribution surfaces, but excludes raw prompt text and raw memory payloads.

Related MCP server: LedgerMem MCP Server

Claude Code / Cursor Config

Use the MCP client's command/args configuration:

{
  "mcpServers": {
    "aionis": {
      "command": "npx",
      "args": [
        "-y",
        "@aionis/mcp@latest",
        "--base-url",
        "http://127.0.0.1:3001",
        "--scope-from",
        "workspace"
      ],
      "env": {
        "AIONIS_TENANT_ID": "default"
      }
    }
  }
}

Zed/Zcode-style clients use context_servers:

{
  "context_servers": {
    "aionis": {
      "command": "npx",
      "args": [
        "-y",
        "@aionis/mcp@latest",
        "--base-url",
        "http://127.0.0.1:3001",
        "--scope-from",
        "workspace"
      ],
      "env": {
        "AIONIS_TENANT_ID": "default"
      }
    }
  }
}

When the host starts MCP from a non-repo cwd, add:

"--repo-root",
"/absolute/path/to/your/repo"

All Agent roles that use the same derived scope can share Aionis execution memory across sessions: planner records plan assets, worker asks aionis_context, verifier records outcomes, and reviewer can inspect the run via aionis_flight_recorder.

Start a local Runtime first:

cd Aionis
npm run -s lite:start

For deeper host integration, use @aionis/sdk. The MCP bridge is the drop-in path; the SDK is the full application integration path.

Claude Code / Cursor walkthrough: https://docs.aionis.work/integrations/mcp

Runnable proof artifacts: https://docs.aionis.work/examples