Chiro SDK

@achiral/chiro is the canonical JavaScript and TypeScript SDK for the Achiral Memory API.

It is framework-neutral. Use it from Node, Next.js route handlers, Express, Fastify, Hono, Cloudflare Workers, Vercel AI SDK tools, CLIs, and backend jobs.

For agent-bound runtime/memory access, use Shelby Memory Agents. Shelby Agents are the separate product surface for durable agent identities and agent-bound tokens.

Founder workspaces can evaluate the Memory API under existing Founder plan limits. For memory-augmented inference on Founder, bring an OpenAI-compatible model endpoint or upgrade.

Shell

npm install @achiral/chiro

# or
pnpm add @achiral/chiro

# or
yarn add @achiral/chiro

ACT-R Verbs

Use the ACT-R-native verbs first:

Canonical SDK verb	Natural alias	Job
`retrieve()`	`recall()`	Bring activated context forward before a model answers.
`encode()`	`remember()`	Turn useful facts, events, or decisions into memory.
`reinforce()`	none	Strengthen memory that helped.
`suppress()`	none	Reduce or block stale, unsafe, or low-trust memory.
`explain()`	none	Inspect why a memory exists and where it came from.
`delete()`	none	Tombstone memory so it no longer appears in normal recall.

TypeScript

import { Chiro } from "@achiral/chiro";

const chiro = new Chiro({
  apiKey: process.env.ACHIRAL_API_KEY!,
  baseURL: "https://acme.achiral.ai/v1",
  agent: "api-sentinel",
});

await chiro.encode({
  text: "The auth service rotates JWT signing keys every 7 days.",
  subject: "auth-service",
  memoryKind: "architecture",
  confidence: 0.92,
});

const memories = await chiro.retrieve({
  query: "How does JWT key rotation work?",
  namespace: "auth-service",
  intent: "debug production auth incident",
  limit: 8,
});

Use includeContext when your app brings its own model runtime but wants Achiral to assemble the private memory context block:

TypeScript

const retrieval = await chiro.retrieve({
  query: "What should I know before editing auth?",
  includeContext: true,
  contextMode: "full",
});

console.log(retrieval.context.systemBlock);

encode() follows the organization's Memory API write mode. The default is Direct write, which makes trusted API writes durable immediately. Paid-plan organization admins can switch to Candidate review path for noisy, low-trust, user-generated, or auto-inferred memories. Founder workspaces use Direct write only.

Memory Controls

TypeScript

await chiro.reinforce("mem_123", {
  reason: "used in the final answer",
  actor: "api-sentinel",
});

await chiro.suppress("mem_123", {
  reason: "superseded by the new runbook",
});

const provenance = await chiro.explain("mem_123");

await chiro.delete("mem_123");

When agent is configured on the client, retrieve, encode, reinforce, suppress, explain, and delete use agent-scoped /v1/memory/agents/:agentSlug/... paths. The natural aliases recall() and remember() use the same paths. Agent-bound runtime access is handled by Shelby Memory Agents.

Use namespace to keep memory for different apps, services, teams, or environments separate. Use intent to say why the current recall or write is happening.

Events

TypeScript

await chiro.events.ingest({
  type: "deployment.completed",
  source: "github-actions",
  subject: "api-service",
  text: "api-service commit abc123 deployed to production.",
  metadata: {
    repo: "acme/api-service",
    sha: "abc123",
    environment: "production",
  },
});

OpenAI-Compatible Chat

TypeScript

await chiro.chat({
  model: "chiro",
  messages: [
    { role: "user", content: "What should I know before touching auth?" },
  ],
});

For streaming chat, use streamChat() or pass stream: true.

TypeScript

const stream = await chiro.streamChat({
  model: "chiro",
  messages: [
    { role: "user", content: "What should I know before touching auth?" },
  ],
});

Frameworks

Do not install framework-specific Chiro packages for V1. Use @achiral/chiro directly.

Framework adapters, if published later, are thin distribution shims over this SDK. They do not define Achiral memory semantics.