Quickstart

This guide gets a local Aionis Runtime running on your machine, then shows how to connect SDK, HTTP, MCP, AIFS, or native plugins. The goal is to put governed memory in front of a real Agent loop:

observe -> guide -> agent action -> feedback -> measure -> snapshot

Aionis runs beside your Agent host and compiles governed context for that host.

Prerequisites

The Runtime defaults to loopback for local Agent development.

One-command Install

The fastest path is the guided product CLI:

npx aionis setup

The setup command clones the Runtime, installs Runtime dependencies, writes a local .env, and prints the next commands for starting the Runtime and connecting an Agent host. Choose an embedding provider during setup so stored memory recall works immediately.

SDK, MCP, AIFS, and native hook integrations are published from their own package repositories and connect to this Runtime through the product API.

For a non-interactive install with OpenAI-compatible embeddings:

OPENAI_API_KEY="your-key" npx aionis setup --provider openai --yes

For MiniMax embeddings:

MINIMAX_API_KEY="your-key" npx aionis setup --provider minimax --yes

If you already cloned the repository, use the local workflow below.

Claude Code Plugin

If your first target is Claude Code, install Runtime into a side directory:

npx aionis setup .aionis-runtime

Then start Runtime:

cd .aionis-runtime
npm run -s lite:start

Now run Claude Code from your project:

claude

Inside Claude Code, install the plugin:

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

Claude Code receives Aionis context before prompts, and Aionis records execution evidence after tool use. The plugin installs user-level hooks and MCP tools, so new projects can use the same Runtime configuration.

Local Repository Setup

git clone https://github.com/ostinatocc/Aionis.git
cd Aionis
npm install

Configure embeddings:

export EMBEDDING_PROVIDER="openai"
export OPENAI_API_KEY="your-openai-key"

MiniMax is also supported:

export EMBEDDING_PROVIDER="minimax"
export MINIMAX_API_KEY="your-minimax-key"

Optional: run the SDK verification flow after the Runtime is configured:

npm run -s runtime:quickstart:sdk

That flow exercises the product path:

1. remember writes ordinary scoped memory.
2. observeStep records execution evidence.
3. guideForRole compiles governed Agent context.
4. feedbackFromOutcome attributes the result to memory that was actually exposed by the guide.
5. measureRun reports whether memory helped or created risk.
6. snapshotRun creates an operator-facing replay view.

What Success Looks Like

A successful run prints a JSON result with fields like:

{
  "prompt_preview": "AIONIS EXECUTION CONTEXT...",
  "execution_context_contract": "aionis_execution_agent_context_v1",
  "memory_use_receipt_visible": true,
  "used_memory_ids": ["mem_..."],
  "snapshot_visible": true
}

The important part is the contract shape:

Choose Your First Loop

Source guide: AIONIS_QUICKSTART_MATRIX.md .

Minimal SDK Loop

import {
  agentPromptFromGuide,
  createAionisClient,
  feedbackFromGuide,
} from "@aionis/sdk";
 
const aionis = createAionisClient({
  baseUrl: "http://127.0.0.1:3001",
  scope: "my-project",
});
 
await aionis.remember({
  kind: "preference",
  text: "Do not reuse failed migration branches as current instructions.",
});
 
const guide = await aionis.guide({
  query_text: "Continue the migration from the current accepted path.",
  context_mode: "compact_agent",
});
 
const prompt = agentPromptFromGuide(guide);
const result = await agent.run(prompt);
const usedMemoryIds = result.usedMemoryIds ?? [];
 
if (usedMemoryIds.length > 0) {
  await aionis.feedback(feedbackFromGuide({
    guide,
    run_id: result.runId,
    outcome: result.ok ? "positive" : "negative",
    reason: result.summary,
    used_memory_ids: usedMemoryIds,
    used_surface: "use_now",
  }));
}

Common First-run Issues

Next

• Follow the full Get Started path.
• Build with Execution Memory.
• Connect a TypeScript host with the SDK guide.
• Add Memory Firewall in front of Mem0 or a vector DB with the Memory Firewall guide.
• Use Claude Code or Cursor through MCP.