TypeScript SDK

The SDK is the recommended way to embed Aionis into a Node or TypeScript Agent host. It wraps the product facade APIs and keeps guide, feedback, measure, and snapshot payloads bounded.


npm install @aionis/sdk

Runtime Connection


import { createAionisClient } from "@aionis/sdk";
 
const aionis = createAionisClient({
  baseUrl: process.env.AIONIS_URL ?? "http://127.0.0.1:3001",
  apiKey: process.env.AIONIS_API_KEY,
  tenant_id: "default",
  scope: "checkout-migration",
});

In Lite mode, apiKey is usually omitted because the Runtime is local-first and loopback-bound by default. The SDK still sends both Authorization: Bearer and x-api-key when a key is configured, so the same client shape can survive a future service deployment.

Ordinary Memory

Use remember for preferences, facts, and general project memory. Ordinary memory does not automatically become execution tree state.


await aionis.remember({
  kind: "preference",
  text: "Prefer small patches and verify before broad refactors.",
  memory_lane: "private",
  owner_agent_id: "worker-1",
});

Execution Memory

Use the execution helper when the memory is about a run, a branch, an outcome, or a handoff.


await aionis.execution.observeStep({
  agent_id: "worker-1",
  run_id: "run-20250615-001",
  task_signature: "checkout-migration",
  title: "Legacy adapter attempt failed",
  summary: "The legacy adapter path touched unrelated modules and was rejected.",
  outcome: "failed",
  target_files: ["src/checkout/legacyAdapter.ts"],
});

Execution memory is where Aionis has the strongest product difference: it can separate current active paths from failed branches, contested memory, stale premises, and rehydrate-only evidence.

Compile Agent Context


import { agentPromptFromGuide } from "@aionis/sdk";
 
const guide = await aionis.execution.guideForRole({
  agent_id: "worker-1",
  role: "worker",
  run_id: "run-20250615-001",
  task_signature: "checkout-migration",
  query_text: "Continue the checkout migration without extending the failed legacy path.",
  context_mode: "compact_agent",
});
 
const prompt = agentPromptFromGuide(guide);
const result = await agent.run(prompt);

The guide response can include:

Surface	Meaning
`use_now`	Memory Aionis allows to directly guide the next action.
`inspect_before_use`	Memory that may be relevant but needs verification.
`do_not_use`	Memory that should not influence the next action.
`rehydrate`	Memory pointers where raw evidence may be needed on demand.
`memory_use_receipt`	Compact audit of use/suppress decisions.
`guide_trace_id`	Attribution key for outcome feedback.

Attribute Feedback

Feedback is the loop that makes Aionis different from retrieval-only memory. Only memory exposed by a guide can receive guide-attributed feedback.


import { feedbackFromGuide } from "@aionis/sdk";
 
const usedMemoryIds = result.usedMemoryIds ?? [];
 
if (usedMemoryIds.length > 0) {
  await aionis.feedback(feedbackFromGuide({
    guide,
    run_id: "run-20250615-001",
    outcome: "positive",
    reason: "The Agent followed the active path and avoided the failed branch.",
    used_memory_ids: usedMemoryIds,
    used_surface: "use_now",
    actor: "worker-1",
  }));
}

If your Agent did not actually use a memory, do not send it as used. Aionis uses that distinction to build admission data.

Measure And Snapshot


import {
  traceDerivedSkillCandidatesFromMeasure,
  traceDerivedSkillReviewItemsFromMeasure,
} from "@aionis/sdk";
 
const measure = await aionis.execution.measureRun({
  run_id: "run-20250615-001",
  task_signature: "checkout-migration",
  after_guide: guide,
  sufficient_evidence: true,
});
 
const traceSkillCandidates = traceDerivedSkillCandidatesFromMeasure(measure);
const traceSkillReviewItems = traceDerivedSkillReviewItemsFromMeasure(measure);
 
const snapshot = await aionis.execution.snapshotRun({
  run_id: "run-20250615-001",
  task_signature: "checkout-migration",
  guide,
  measure_result: measure,
  include_markdown: true,
});

measure is for product effect. snapshot is for operator replay. Neither requires sending full prompt payloads into your own logs.

traceSkillCandidates are the raw Runtime contracts. traceSkillReviewItems are compact review queue projections with skill name, applicability conditions, procedure steps, acceptance checks, evidence refs, and the required safety gate. Both stay out of Agent prompts and do not mutate Runtime state; use them for review, dashboarding, or later procedure promotion gates.

The SDK repository includes a minimal Trace-to-Skill review demo:


npm run build
npm run example:trace-to-skill

Source: examples/trace-to-skill-candidate.mjs .

Full Minimal Example

The repository includes a runnable minimal Agent loop:

docs/mgbench/minimal-agent.ts

Run the packaged quickstart:


npm run -s runtime:quickstart:sdk

Guide: AIONIS_SDK_QUICKSTART.md .