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.

Machine-Readable Resources

Agents and developer tools should start with:

Shell

npm install @achiral/chiro

For command-line workflows:

Shell

npm install -g @achiral/cli
achiral login

Shell

pnpm add @achiral/chiro

Shell

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.

API Surface Summary

The SDK mirrors the Memory API's stable operation model:

Retrieve activated context before a model answers.
Encode useful facts, events, decisions, and preferences.
Reinforce memory that helped a task succeed.
Suppress stale or risky memory when it should lose influence.
Explain provenance before trusting or debugging a memory.
Delete memory through tombstones when it should no longer appear in normal recall.

Use the organization-level client for application memory. Use agent-scoped paths when an agent slug is configured on the client. Shelby Memory Agents remain the product surface for durable agent identity, lifecycle, billing boundaries, audit, and agent-bound tokens.

Environment Variables

Shell

export ACHIRAL_API_KEY=acm_...
export ACHIRAL_BASE_URL=https://your-org.achiral.ai/v1

The SDK can also receive those values directly through the Chiro constructor. Keep API keys scoped to the smallest set of permissions the integration needs.

Permissions

memory:read allows retrieval and recall.
memory:write allows encoding and event ingestion.
memory:control allows reinforcement, suppression, and provenance inspection.
memory:delete allows tombstoning.

Event Ingestion Notes

Developer events are useful for deploys, incidents, CI runs, pull requests, support tickets, and product events. They should be written as evidence, not as unverifiable conclusions.

Implementation Notes For Agents

When a coding agent adds Achiral memory to an app, it should:

Install @achiral/chiro.
Read ACHIRAL_API_KEY and ACHIRAL_BASE_URL from environment variables.
Retrieve relevant context before the model answers or acts.
Pass returned memory records or an assembled context block to the model.
Encode durable facts, events, and decisions after the app learns something useful.
Reinforce records that helped and suppress records that are stale or risky.
Prefer framework-neutral SDK calls over framework-specific packages.