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


const measure = await aionis.execution.measureRun({
  run_id: "run-20250615-001",
  task_signature: "checkout-migration",
  after_guide: guide,
  sufficient_evidence: true,
});
 
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.

Full Minimal Example

The repository includes a runnable minimal Agent loop:

docs/examples/minimal-agent.ts

Run the packaged quickstart:


npm run -s runtime:quickstart:sdk

Guide: AIONIS_SDK_QUICKSTART.md .