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.

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:

Shell

Authorization: Bearer acm_...

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.

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.

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 admins on paid plans can switch writes to Candidate review path in organization settings. 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

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

Developer Memory API

ACT-R Verbs

Authentication

Pricing And Fair Use

Retrieve

Encode

Write Mode

Event Ingestion

Control

Next