Memory API

The Memory API exposes two surfaces: an OpenAI-compatible inference gateway for external clients, and session-authenticated memory routes for the Achiral workspace.

Authentication

Surface	Auth	Scope
/v1/* inference gateway	Bearer MCP access token such as acm_...	Token must include inference:chat
/api/user/memory/*	Signed-in workspace session	Current user in the current organization
/api/organizations/:id/memory/*	Signed-in workspace session	Organization owner or admin
/api/memory/*	Signed-in workspace session plus memory permissions	Knowledge read, write, or delete permission by route

The gateway always exposes the public model id chiro. Internal provider and registry names are intentionally hidden from clients.

Inference gateway

The inference gateway is the external, OpenAI-compatible memory endpoint. It authenticates an organization token, verifies the request organization, injects private organization memory, forwards the request to the model layer, and can optionally write the completed turn back into memory.

Method	Path	Purpose
GET	/v1/health	Liveness check. No auth required.
GET	/v1/models	Return the single public model id, chiro.
POST	/v1/chat/completions	Run a memory-augmented chat completion. Supports streaming and non-streaming responses.

How do I call the memory inference endpoint?

export ACHIRAL_MEMORY_ENDPOINT="https://your-slug.achiral.ai/v1"
export ACHIRAL_MCP_TOKEN="acm_..."

curl "$ACHIRAL_MEMORY_ENDPOINT/chat/completions" \
  -H "Authorization: Bearer $ACHIRAL_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-achiral-memory: auto" \
  -d '{
    "model": "chiro",
    "messages": [
      {"role": "user", "content": "What changed in our onboarding workflow this week?"}
    ],
    "temperature": 0.2,
    "max_tokens": 600
  }'

How do I list available models?

export ACHIRAL_MEMORY_ENDPOINT="https://your-slug.achiral.ai/v1"
export ACHIRAL_MCP_TOKEN="acm_..."

curl "$ACHIRAL_MEMORY_ENDPOINT/models" \
  -H "Authorization: Bearer $ACHIRAL_MCP_TOKEN"

{
  "object": "list",
  "data": [
    {
      "id": "chiro",
      "object": "model",
      "created": 1783276800,
      "owned_by": "achiral"
    }
  ]
}

User memory

User memory routes power the signed-in account memory view. They are not token-authenticated public API routes; call them from the workspace with the user's session.

Method	Path	Purpose
GET	/api/user/memory	Return the signed-in user's memory summary in the current organization.
PUT	/api/user/memory/candidates/:weaviateId	Approve or reject a user-scoped core memory candidate.
POST	/api/user/memory/automation-rules/:templateId/unsuppress	Clear the caller's personal suppression cooldown for one automation rule.
POST	/api/user/memory/automation-rules/:templateId/require-approval	Require or remove personal approval for one automation rule.

How do I approve or reject my own memory candidate?

const response = await fetch("/api/user/memory/candidates/mem_123", {
  method: "PUT",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    action: "approve",
    collection: "UserPreferences",
  }),
});

const result = await response.json();

action must be approve or reject. collection is required because memory candidates can live in different Weaviate collections.

Organization memory

Organization memory routes power the organization Memory tab. They require owner or admin access.

Method	Path	Purpose
GET	/api/organizations/:id/memory	Return tier distribution, top activated memories, core-memory candidates, and total memory count.
GET	/api/organizations/:id/members/:userId/memory	Return a redacted memory summary for an active organization member.
PUT	/api/organizations/:id/memory/candidates/:weaviateId	Approve or reject an organization core-memory candidate.

What does organization memory return?

{
  "success": true,
  "memory": {
    "tierDistribution": {
      "episodic": 128,
      "semantic": 42,
      "core": 7
    },
    "topMemories": [
      {
        "id": "mem_123",
        "collection": "ConversationMemory",
        "tier": "episodic",
        "activationScore": 0.82,
        "accessCount": 12,
        "salienceScore": 0.64,
        "lastAccessedAt": "2026-07-05T12:00:00.000Z",
        "snippet": "Customer onboarding exception..."
      }
    ],
    "candidates": [],
    "totalMemories": 177
  }
}

Knowledge and reflection routes

The /api/memory router also exposes organization knowledge and reflection-loop routes. These are workspace routes protected by session auth and memory permissions.

Group	Paths
Knowledge	POST /api/memory/knowledge, GET /api/memory/knowledge, GET /api/memory/knowledge/search, GET /api/memory/knowledge/stats, GET /api/memory/knowledge/:id, PUT /api/memory/knowledge/:id, DELETE /api/memory/knowledge/:id
Reflection settings	GET /api/memory/reflection/settings, PATCH /api/memory/reflection/settings
Reflection events and audits	GET /api/memory/reflection/events, GET /api/memory/reflection/audits
Reflection metrics	GET /api/memory/reflection/metrics, GET /api/memory/reflection/metrics/summary, GET /api/memory/reflection/metrics/trend, GET /api/memory/reflection/metrics/distribution
Reflection run	POST /api/memory/reflection/run
Preference calibration	POST /api/memory/preferences/:id/feedback, GET /api/memory/preferences/low-confidence, POST /api/memory/preferences/calibrate, GET /api/memory/preferences/feedback-stats

Continue from here

• API reference: shared API conventions, base URLs, streaming, and errors.
• AI memory: product concepts behind memory tiers and activation.
• ACT-R memory: technical model for activation, retrieval, decay, and consolidation.
• Security & compliance: data isolation, RBAC, and audit posture.