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.

For the authoritative map of SDK methods, Runtime APIs, Agent-facing outputs, and operator-only surfaces, see SDK and API Surface Matrix.


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 invalidated routes, contested memory, stale premises, and rehydrate-only evidence.

Compile Agent Context


const guide = await aionis.guideAgentContext({
  consumer_agent_id: "worker-1",
  run_id: "run-20250615-001",
  query_text: "Continue the checkout migration from the current accepted route.",
  context_mode: "compact_agent",
  task_context_profile: "coding_verifier",
  context: {
    task_signature: "checkout-migration",
  },
}, {
  guide_mode: "full_power",
}, {
  task: {
    run_id: "run-20250615-001",
    task_signature: "checkout-migration",
    goal: "Continue the checkout migration from the current accepted route.",
  },
});
 
const prompt = guide.agent_prompt;
const result = await agent.run(prompt);

task_context_profile is selected by your host or adapter. It lets the same Runtime render context for different task postures without changing governance:

Task posture	Profile
Coding task with validators or acceptance checks	`coding_verifier`
Source-grounded long-memory QA	`long_qa`
Planner/worker/verifier/reviewer handoff	`multi_agent_handoff`
Plan-execute-validate-repair loop	`loop_engineering`
File or document identity workflow	`document_integrity`

If omitted, Aionis uses general.

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 the same guide result 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 preserved the current state.",
    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 verification:


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

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

Task context profile guide: Task Context Profiles.

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 .