---
title: "Chiro SDK"
description: "Install and use the framework-neutral @achiral/chiro SDK."
date: "2026-08-14"
modified: "2026-08-14"
reviewed: "2026-08-14"
---

# Chiro SDK

> Install and use the framework-neutral @achiral/chiro SDK.

Published on: 2026-08-14

Last updated on: 2026-08-14

`@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](https://achiral.ai/ai-agent-memory). 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:

- [OpenAPI specification](https://achiral.ai/openapi.json)
- [Well-known OpenAPI description](https://achiral.ai/.well-known/achiral-memory-api-openapi.json)
- [API catalog](https://achiral.ai/.well-known/api-catalog)
- [Auth.md agent authentication discovery](https://achiral.ai/auth.md)
- [Developer Memory API docs](https://achiral.ai/docs/memory/api/developer-memory-api)
- [Achiral CLI](https://www.npmjs.com/package/@achiral/cli)
- [Achiral CLI source](https://github.com/Achiral-AI/achiral.cli)
- [Authenticated MCP server](https://mcp.achiral.ai)
- [MCP discovery endpoint](https://mcp.achiral.ai/mcp)
- [Well-known MCP manifest](https://mcp.achiral.ai/.well-known/achiral-mcp.json)
- [MCP public tool schemas](https://mcp.achiral.ai/.well-known/achiral-mcp-tools.json)
- [MCP protected resource metadata](https://mcp.achiral.ai/.well-known/oauth-protected-resource)

```bash
npm install @achiral/chiro
```

For command-line workflows:

```bash
npm install -g @achiral/cli
achiral login
```

```bash
pnpm add @achiral/chiro
```

```bash
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. |

```ts
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:

```ts
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

```ts
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

```ts
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

```ts
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`.

```ts
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

```bash
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:

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