@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, Codex-style tools, or another MCP client to use Aionis without rewriting the host Agent loop first. 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 setup
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 the MCP transport for the canonical SDK AgentContext. It calls execution.guideAgentContextForRole(), returns the same top-level agent_prompt, and exposes a prompt-free aionis_execution_agent_context_v1 audit view under structuredContent.execution_context. MCP clients should pass only top-level agent_prompt to an Agent; richer clients can also read the structured execution context and receipts for host logic.

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 instance, 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, Cursor, or another MCP host, 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 rejected or superseded evidence with the target files and validation result.

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

4. Use aionis_flight_recorder after the run to replay which plan memories, boundaries, and rehydrate pointers 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 from the current accepted implementation state.",
  "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: Memclaw

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

Generated proof artifacts: https://docs.aionis.work/research