Docs · LLMs and developers
Version3.14.0Public 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:
- OpenAPI specification
- Well-known OpenAPI description
- API catalog
- Auth.md agent authentication discovery
- LLM index
- Achiral CLI
- Achiral CLI source
- Authenticated MCP server
- MCP discovery endpoint
- Well-known MCP manifest
- MCP public tool schemas
- MCP protected resource metadata
ACT-R Verbs
Use the ACT-R-native verbs as the primary API language. Natural aliases stay available for readability and compatibility.
| Canonical verb | Natural alias | Endpoint |
|---|---|---|
| Retrieve | Recall | POST /v1/memory/retrieve |
| Encode | Remember | POST /v1/memory |
| Reinforce | none | POST /v1/memory/:id/reinforce |
| Suppress | none | POST /v1/memory/:id/suppress |
| Explain | Inspect provenance | GET /v1/memory/:id/provenance |
| Delete | Tombstone | DELETE /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:
Authorization: Bearer acm_...For command-line workflows, install the official Achiral CLI:
npm install -g @achiral/cli
achiral loginThe 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:
| Operation | Scope |
|---|---|
| Retrieve memories | memory:read |
| Encode memories | memory:write |
| Ingest developer events | memory:write |
| Reinforce, suppress, and inspect provenance | memory:control |
| Tombstone memories | memory: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
POST /v1/memory/retrieve{
"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:
{
"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:
POST /v1/memory/recall
POST /v1/memory/searchAgent-scoped retrieval is available through:
POST /v1/memory/agents/:agentSlug/retrieveNatural aliases:
POST /v1/memory/agents/:agentSlug/recall
POST /v1/memory/agents/:agentSlug/searchAchiral 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
POST /v1/memory{
"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:
POST /v1/memory/agents/:agentSlugSend 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.
| Mode | Behavior |
|---|---|
| Direct write | encode() writes directly into durable memory and can be retrieved immediately. |
| Candidate review path | encode() creates a memory candidate that must be reviewed before promotion. |
Event Ingestion
POST /v1/memory/events{
"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.
POST /v1/memory/:id/reinforce{
"reason": "selected by answer synthesis",
"actor": "sdk"
}POST /v1/memory/:id/suppress{
"reason": "superseded by incident INC-2042",
"actor": "developer"
}GET /v1/memory/:id/provenanceDELETE /v1/memory/:idDELETE 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:
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