Quickstart

This guide gets a local Aionis Runtime, SDK, and optional MCP bridge running on your machine. The goal is not just to store a memory. 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. It is not a hosted multi-tenant control plane.

One-command Install

The fastest path is the installer package:

MINIMAX_API_KEY="your-key" npx @aionis/create@latest --provider minimax --quickstart sdk

The installer clones the Runtime, installs the workspace packages, writes a local .env, builds the SDK/MCP packages, and runs the selected quickstart.

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

Local Repository Setup

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

Configure embeddings:

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.