AchiralAchiral

Docs · LLMs and developers

Version3.14.0

Public Memory API endpoints for ACT-R retrieval, encoding, developer event ingestion, and memory control.

Developer Memory API

The Developer Memory API exposes Achiral's ACT-R memory substrate under /v1/memory: retrieval, encoding, event ingestion, activation-aware ranking, reinforcement, suppression, tombstoning, and provenance-preserving writes.

If you need agent-bound runtime/memory access, use Shelby Memory Agents. Shelby Agents are the separate product surface for durable agent identities, scoped runtime access, lifecycle, audit, billing boundaries, and agent-bound tokens.

Machine-Readable Resources

Use these URLs when wiring agents, SDKs, gateways, or API discovery tooling:

ACT-R Verbs

Use the ACT-R-native verbs as the primary API language. Natural aliases stay available for readability and compatibility.

Canonical verbNatural aliasEndpoint
RetrieveRecallPOST /v1/memory/retrieve
EncodeRememberPOST /v1/memory
ReinforcenonePOST /v1/memory/:id/reinforce
SuppressnonePOST /v1/memory/:id/suppress
ExplainInspect provenanceGET /v1/memory/:id/provenance
DeleteTombstoneDELETE /v1/memory/:id

POST /v1/memory/recall is the friendly retrieval alias. POST /v1/memory/search remains available as a compatibility alias for existing callers.

Authentication

Use an Achiral Context Access Token:

Shell
Authorization: Bearer acm_...

For command-line workflows, install the official Achiral CLI:

Shell
npm install -g @achiral/cli
achiral login

The Memory API uses organization-level API tokens with explicit memory scopes. Agent-scoped paths are supported when you pass an agent slug, but tokens that are bound to agents cannot access memories outside their allowed agents. For a first-class agent-bound runtime, head to Shelby Memory Agents.

When Memory API environments are enabled, create a separate token for Test and Production. The token selects the environment while the organization base URL stays the same. Do not send an environment name or ID in a header or request body. Tokens without an environment binding are rejected and must be recreated in the intended environment.

Required scopes:

OperationScope
Retrieve memoriesmemory:read
Encode memoriesmemory:write
Ingest developer eventsmemory:write
Reinforce, suppress, and inspect provenancememory:control
Tombstone memoriesmemory:delete

Pricing And Fair Use

The Memory API is included with Achiral workspace seat pricing for normal developer use. There are no memory-credit packs or public per-endpoint overage meters in V1.

Founder workspaces include light developer evaluation under existing Founder plan limits.

The Memory API uses the org-wide Chiro memory layer. For memory-augmented inference on Founder, bring an OpenAI-compatible model endpoint or upgrade; Achiral-hosted inference remains bounded by the workspace plan.

High-volume patterns move to Custom capacity planning instead of surprise usage billing. Examples include large CI/security streams, observability firehoses, high-frequency automated recall, long-retention bulk imports, dedicated Weaviate capacity, private infrastructure, and SLA-backed throughput.

Test and Production have separate usage counters and limits. See Memory API environments for the default limits and API reference for the HTTP rate-limit contract.

For agent-bound runtime/memory access, use Shelby Memory Agents; Shelby pricing remains separate.

Retrieve

HTTP
POST /v1/memory/retrieve
JSON
{
  "query": "How does JWT key rotation work?",
  "limit": 8
}

Set includeContext: true when you want the same private runtime context block that Achiral can inject into memory-augmented inference:

JSON
{
  "query": "How should the auth service rotate JWT keys?",
  "includeContext": true,
  "contextMode": "full"
}

The response includes retrieved memories and can add a context object with systemBlock and retrieval stats. Use this when your application brings its own model runtime but still wants Achiral to assemble scoped memory context.

Natural aliases:

HTTP
POST /v1/memory/recall
POST /v1/memory/search

Agent-scoped retrieval is available through:

HTTP
POST /v1/memory/agents/:agentSlug/retrieve

Natural aliases:

HTTP
POST /v1/memory/agents/:agentSlug/recall
POST /v1/memory/agents/:agentSlug/search

Achiral resolves the organization from the token and the agent from the path, X-Achiral-Agent, or SDK configuration. Agent-bound tokens cannot access memories outside their allowed agents.

Encode

HTTP
POST /v1/memory
JSON
{
  "text": "The auth service rotates JWT signing keys every 7 days.",
  "subject": "auth-service",
  "memoryKind": "architecture",
  "confidence": 0.92
}

Natural SDK alias: remember().

Agent-scoped encoding is available through:

HTTP
POST /v1/memory/agents/:agentSlug

Send Idempotency-Key for retry-safe writes.

Write Mode

The Memory API defaults to Direct write: authenticated memory:write calls become durable memory immediately.

Organization owners and admins on paid plans can switch writes to Candidate review path under Memory > Core Memories (/memory/core), beside the candidate review queue. Founder workspaces use Direct write only. Use candidate review for noisy, low-trust, user-generated, or auto-inferred memories that should be approved before they become durable retrievable memory.

ModeBehavior
Direct writeencode() writes directly into durable memory and can be retrieved immediately.
Candidate review pathencode() creates a memory candidate that must be reviewed before promotion.

Event Ingestion

HTTP
POST /v1/memory/events
JSON
{
  "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"
  }
}

Developer events enter Achiral's generic ingestion pipeline, become BusinessEvent records, and can stage durable memory candidates.

Natural SDK alias: events.ingest().

Control

Use memory control endpoints when an application needs to mark which memories were useful, hide stale or unsafe memories, inspect why a memory exists, or remove a memory.

HTTP
POST /v1/memory/:id/reinforce
JSON
{
  "reason": "selected by answer synthesis",
  "actor": "sdk"
}
HTTP
POST /v1/memory/:id/suppress
JSON
{
  "reason": "superseded by incident INC-2042",
  "actor": "developer"
}
HTTP
GET /v1/memory/:id/provenance
HTTP
DELETE /v1/memory/:id

DELETE tombstones memory instead of erasing it. Tombstoned memory is kept for provenance and audit, but it is removed from normal retrieval.

Agent-scoped control is available through the same path form:

HTTP
POST /v1/memory/agents/:agentSlug/:id/reinforce
POST /v1/memory/agents/:agentSlug/:id/suppress
GET /v1/memory/agents/:agentSlug/:id/provenance
DELETE /v1/memory/agents/:agentSlug/:id

Next