Quickstart

This guide gets a local Aionis Runtime and product API running on your machine, then shows how to connect SDK, HTTP, MCP, AIFS, or native plugins. The goal is to complete one governed Agent loop:

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

Aionis is local-first today. It is designed to sit beside your Agent host and compile governed context for that host.

Prerequisites

The Lite Runtime defaults to loopback and local unauthenticated use, which keeps the first install fast for local Agent development.

One-command Install

The fastest path is the installer package:

npx @aionis/create@latest

The installer clones the Runtime, installs Runtime dependencies, writes a local .env, runs the Runtime build check, and starts the no-key first-value demo. SDK, MCP, and Claude Code integrations are published from their own package repositories and connect to this Runtime through the product API.

For the full SDK quickstart with recall-backed guide output:

OPENAI_API_KEY="your-key" npx @aionis/create@latest --provider openai --quickstart sdk

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

Optional Claude Code Plugin

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

npx @aionis/create@latest .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 will receive Aionis context before prompts and Aionis will record execution evidence after tool use. The plugin path installs user-level hooks and MCP tools, so future projects do not need manual hook setup.

Local Repository Setup

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

Run the first-value demo without an embedding key:

npm run -s runtime:demo:first-value

Then 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"

Run the SDK quickstart:

npm run -s runtime:quickstart:sdk

That quickstart 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.