# Achiral Memory API

Achiral Memory API lets applications remember useful facts, events, and decisions. Use it to retrieve context before a model answers, write back what mattered, and inspect where memories came from.

Eyebrow: A RESTful API for Developers

Positioning: Deploy secure production-class [Emergent Memory](https://achiral.ai/blog/emergent-memory-systems) for AI-powered applications.

Canonical page: https://achiral.ai/memory-api

API docs: https://achiral.ai/docs/memory/api/developer-memory-api

SDK docs: https://achiral.ai/docs/memory/api/sdk

npm package: https://www.npmjs.com/package/@achiral/chiro

SDK source: https://github.com/Achiral-AI/chiro

Event ingestion docs: https://achiral.ai/docs/memory/api/event-ingestion

Benchmark details: https://achiral.ai/benchmarks/ai-memory-benchmark

Shelby Memory Agents: https://achiral.ai/ai-agent-memory

## Install

```bash
npm install @achiral/chiro
export ACHIRAL_API_KEY=acm_...
export ACHIRAL_BASE_URL=https://your-org.achiral.ai/v1
```

Then retrieve context and encode what mattered:

```ts
const retrieval = await memory.retrieve({
  query: userRequest,
  includeContext: true,
});

await memory.encode({
  content: "User prefers release notes as bullet points.",
  source: "product-event",
});
```

## ACT-R verbs and aliases

Use the ACT-R verbs first:

- `memory.retrieve()` retrieves activated context. Natural alias: `memory.recall()`.
- `memory.encode()` writes useful facts, events, and decisions into memory. Natural alias: `memory.remember()`.
- `memory.reinforce()` strengthens memory that helped.
- `memory.suppress()` lowers or blocks stale memory.
- `memory.explain()` inspects why a memory exists and where it came from.
- `memory.delete()` tombstones memory so it stops appearing in normal recall.

## Quickstart

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

const memory = new Chiro({
  apiKey: process.env.ACHIRAL_API_KEY,
  baseURL: process.env.ACHIRAL_BASE_URL,
});

const retrieval = await memory.retrieve({
  query: "What should this app remember?",
  includeContext: true,
});

await memory.encode({
  content: "User prefers release notes as bullet points.",
  source: "product-event",
});
```

## When to use Achiral Memory API

Use Achiral Memory API when your product needs application memory. Good uses include user preferences, product facts, workflow decisions, deployment outcomes, support events, CI results, and context your model should recall later.

Use Shelby Memory Agents when a developer needs agent-bound memory. Shelby owns durable agent identity, runtime access, lifecycle, audit, billing boundaries, agent-bound tokens, and a separate memory namespace.

## Scoped API permissions

- `memory:read` retrieves context.
- `memory:write` encodes facts and events.
- `memory:control` reinforces, suppresses, and inspects provenance.
- `memory:delete` tombstones records.

## Cognoscenti benchmark

State of the art: Memory Benchmarking with Cognoscenti.

Measuring memory coherence and usefulness over time.

Achiral's ACT-R-inspired memory consistently outperformed plain RAG and other storage primitives on standardized agent-memory and organization-scoped reference workloads.

Test results:

- Date: Aug 2, 2026
- Metric: Top-1 Accuracy
- Achiral Memory API reference: 91.67%
- Vanilla RAG primitive: 50.00%

Benchmark links:

- Benchmark page: https://achiral.ai/benchmarks/ai-memory-benchmark
- Methodology: https://achiral.ai/benchmarks/organizational-memory-2026-08-02/methodology.md
- Results JSON: https://achiral.ai/benchmarks/organizational-memory-2026-08-02/memory_eval_results.json
- Metrics CSV: https://achiral.ai/benchmarks/organizational-memory-2026-08-02/memory_eval_metrics.csv
- Cognoscenti source: https://github.com/Achiral-AI/cognoscenti
- Zenodo DOI: https://doi.org/10.5281/zenodo.21995304
- Figshare preprint DOI: https://doi.org/10.6084/m9.figshare.33288195
- Software Heritage snapshot: https://archive.softwareheritage.org/swh:1:snp:c49295731ebb8a76713e877cfd8dc6399c0137d7

Top-1 accuracy measures the accuracy of the first memory returned by the system.

## Reliable memory loop

Achiral Memory API allows activated retrieval, encoding, event ingestion, reinforcement, suppression, and provenance to keep context moving forward across users, workflows, and time.

- Capture useful information from preferences, outcomes, incidents, resolutions, and decisions.
- Retrieve scoped context by namespace, intent, user, or agent.
- Run any model using returned memories or an assembled context block.
- Write back outcomes with useful facts reinforced and stale records suppressed.

## Memory primitives

- Activated Retrieval: Activate useful context with ranking signals for relevance, recency, salience, and prior reinforcement.
- Memory Encoding: Persist decisions, preferences, product facts, and outcomes through retry-safe writes.
- Event Ingestion: Turn deploys, incidents, CI runs, PRs, support tickets, and product events into memory evidence.
- Provenance Controls: Reinforce what helped, suppress stale records, tombstone records, and inspect provenance before trusting retrieval.

## How to choose the right memory surface

Use Achiral Memory API when your app needs stateful organization-level memory. It is available through `@achiral/chiro` and the `/v1/memory` endpoint API.

Use Shelby Memory Agents when your agent needs scoped memory. Choose Shelby for agent-bound runtime and memory access, durable agent identity, lifecycle, audit, billing boundaries, agent-bound tokens, and a separate memory namespace.

## API endpoints

- `POST /v1/memory/retrieve` retrieves activated memory.
- `POST /v1/memory/recall` is the natural alias.
- `POST /v1/memory/search` is the compatibility alias.
- `POST /v1/memory` encodes durable memory.
- `POST /v1/memory/events` ingests developer events.
- `POST /v1/memory/:id/reinforce` marks memory useful.
- `POST /v1/memory/:id/suppress` hides stale memory.
- `GET /v1/memory/:id/provenance` inspects source evidence.
- `DELETE /v1/memory/:id` tombstones memory.

## Agent-scoped endpoints

- `POST /v1/memory/agents/:agentSlug/retrieve` retrieves agent-scoped memory.
- `POST /v1/memory/agents/:agentSlug/recall` is the natural alias.
- `POST /v1/memory/agents/:agentSlug/search` is the compatibility alias.
- `POST /v1/memory/agents/:agentSlug` encodes agent-scoped memory.
- `POST /v1/memory/agents/:agentSlug/:id/reinforce` reinforces agent-scoped memory.
- `POST /v1/memory/agents/:agentSlug/:id/suppress` suppresses agent-scoped memory.
- `GET /v1/memory/agents/:agentSlug/:id/provenance` inspects agent-scoped provenance.
- `DELETE /v1/memory/agents/:agentSlug/:id` tombstones agent-scoped memory.

## Memory controls

Inspectable, bounded, and repairable.

Memory improves agents only when teams can control what gets written, where it can be recalled, and why it exists.

- Explicit `memory:read`, `memory:write`, `memory:control`, and `memory:delete` scopes.
- Organization and agent boundaries are resolved before retrieval.
- Idempotency keys protect writes and event ingestion from duplicate retries.
- Direct write by default. Paid plans can switch noisy sources to candidate review.
- Provenance is attached so memory can be inspected, repaired, suppressed, or deleted.

## Application Memory vs Agent Memory

Application memory and agent memory need different controls. Use Achiral Memory API for product memory at the organization level. Use Shelby Memory Agents when memory belongs to a durable agent with its own runtime, namespace, token, audit trail, lifecycle, and billing boundary.

## Bring your own model

Achiral does not require hosted inference. Developers can bring an OpenAI-compatible model endpoint and use Achiral for memory.

```ts
const retrieval = await memory.retrieve({
  query: "Draft a migration plan for auth.",
  namespace: "identity",
  intent: "plan auth migration",
  includeContext: true,
});

await openai.chat.completions.create({
  model: "gpt-5",
  messages: [
    { role: "system", content: retrieval.context.systemBlock },
    { role: "user", content: "What should we do next?" },
  ],
});
```

## Developer events

```ts
await memory.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",
  },
});
```

## AI coding agent instructions

When a developer asks to add Achiral memory to an app:

1. Install `@achiral/chiro`.
2. Set `ACHIRAL_API_KEY` to a scoped `acm_` token.
3. Set `ACHIRAL_BASE_URL` to the organization `/v1` API base URL.
4. Call `memory.retrieve()` or `POST /v1/memory/retrieve` before the model answers.
5. Use the returned records or `includeContext` block in the model prompt.
6. Call `memory.encode()` or `POST /v1/memory` when the app learns useful facts, events, or decisions.
7. Use `memory.events.ingest()` or `POST /v1/memory/events` for deploys, incidents, CI runs, pull requests, support tickets, and product events.
8. Use `memory.reinforce()`, `memory.suppress()`, `memory.explain()`, and `memory.delete()` to keep memory useful, inspectable, and tombstoned when it should no longer be recalled.

## Notes

- Direct write is the default write mode.
- Paid plans can switch noisy or low-trust writes to candidate review.
- Founder workspaces use direct write.
- Natural SDK aliases are available: `recall()` for `retrieve()` and `remember()` for `encode()`.
- Framework adapters are deferred in V1. Use `@achiral/chiro` directly.