AI Memory

Persistent memory entries that the AI uses to maintain context across sessions.

Endpoints

Method	Path	Description	Auth	Rate Limit
GET	/ai/memory	List memories	JWT + Entitlement	60/min
POST	/ai/memory	Create a memory entry	JWT + Entitlement	30/min

---

GET /ai/memory

List memory entries, optionally filtered by scope.

Authentication: JWT Bearer token + active AI entitlement required. Rate limit: 60/min

Request

Parameter	Type	Required	Description
scope	string	No	Filter by scope: user, session, chain, workspace
origin	string	No	Filter by origin: user, inferred, imported, system
confidence	string	No	Filter by confidence: low, medium, high
freshness	string	No	Filter by freshness: active, stale, archived
chainyId	string	No	Filter by Chainy ID (UUID)
type	string	No	Filter by memory type: preference, context, behavioral, goal

Response

Response Example

{
  "data": [
    {
      "id": "cm5mem01",
      "content": "User prefers morning study sessions between 7-9 AM.",
      "scope": "user",
      "tags": ["preferences", "learning-style"],
      "type": "preference",
      "origin": "user",
      "confidence": "high",
      "freshness": "active",
      "chainyId": null,
      "importance": 75,
      "createdAt": "2026-03-17T10:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

Response Fields

Field	Type	Description
id	string	Memory ID
content	string	Memory content
scope	string	user, session, chain, workspace
tags	string[]	Tags
type	string | null	Memory type: preference, context, behavioral, goal
origin	string | null	Memory origin: user, inferred, imported, system
confidence	string | null	Confidence level: low, medium, high
freshness	string	Memory freshness: active, stale, archived
chainyId	string | null	Linked Chainy ID
importance	number	Importance score (0-100)
createdAt	string	ISO 8601

Code Examples

cURL

curl "https://api.chainabit.com/api/v1/ai/memory?scope=user" \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const params = new URLSearchParams({ scope: "user" });
const res = await fetch(`${BASE_URL}/ai/memory?${params}`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data, meta } = await res.json();

Python

import requests

res = requests.get(
    f"{BASE_URL}/ai/memory",
    headers={"Authorization": f"Bearer {TOKEN}"},
    params={"scope": "user"},
)
body = res.json()

---

POST /ai/memory

Create a new memory entry.

Authentication: JWT Bearer token + active AI entitlement required. Rate limit: 30/min

Request

Field	Type	Required	Constraints	Description
content	string	Yes	Non-empty, max 10,000 chars	Memory content
scope	string	Yes	user, session, chain, workspace	Scope for this memory
scopeId	string	No	—	ID of the scoped entity (e.g., chain ID)
tags	string[]	No	—	Tags for categorization
origin	string	No	user, inferred, imported, system	Memory origin. Defaults to user
confidence	string	No	low, medium, high	Confidence level. Defaults to medium
evidence	string[]	No	Max 20 items, each max 2,000 chars	Supporting evidence for this memory
sourceEntityType	string	No	chainy, chain, bit, session	Type of the source entity
sourceEntityId	string	No	UUID	ID of the source entity
chainyId	string	No	UUID	Linked Chainy ID
type	string	No	preference, context, behavioral, goal	Memory type

Response

Response Example

{
  "data": {
    "id": "cm5mem01",
    "content": "User prefers morning study sessions between 7-9 AM. Learns best with visual mnemonics.",
    "scope": "user",
    "scopeId": null,
    "tags": ["preferences", "learning-style"],
    "type": "preference",
    "origin": "user",
    "confidence": "medium",
    "freshness": "active",
    "chainyId": null,
    "importance": 50,
    "createdAt": "2026-03-17T10:00:00.000Z"
  }
}

Response Fields

Field	Type	Description
id	string	Memory ID
content	string	Memory content
scope	string	user, session, chain, workspace
scopeId	string | null	Scoped entity ID
tags	string[]	Tags
type	string | null	Memory type: preference, context, behavioral, goal
origin	string | null	Memory origin: user, inferred, imported, system
confidence	string | null	Confidence level: low, medium, high
freshness	string	Memory freshness: active, stale, archived
chainyId	string | null	Linked Chainy ID
importance	number	Importance score (0-100)
createdAt	string	ISO 8601

Code Examples

cURL

curl -X POST https://api.chainabit.com/api/v1/ai/memory \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers morning study sessions between 7-9 AM. Learns best with visual mnemonics.",
    "scope": "user",
    "tags": ["preferences", "learning-style"]
  }'

JavaScript

const res = await fetch(`${BASE_URL}/ai/memory`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content:
      "User prefers morning study sessions between 7-9 AM. Learns best with visual mnemonics.",
    scope: "user",
    tags: ["preferences", "learning-style"],
  }),
});
const { data } = await res.json();

Python

import requests

res = requests.post(
    f"{BASE_URL}/ai/memory",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "content": "User prefers morning study sessions between 7-9 AM. Learns best with visual mnemonics.",
        "scope": "user",
        "tags": ["preferences", "learning-style"],
    },
)
data = res.json()["data"]

---

Memory Taxonomy

Each memory entry is classified along several dimensions:

Scope

Where the memory applies.

Value	Description
user	Account-wide — applies across all sessions and chains
session	Session-scoped — relevant only within a specific session
chain	Chain-scoped — tied to a specific chain
workspace	Workspace-scoped — shared across a workspace
chainy	Chainy-scoped — tied to a specific Chainy

Type

What kind of memory.

Value	Description
preference	User preferences (e.g., study times, UI choices)
context	Situational context (e.g., current project, topic)
behavioral	Observed patterns (e.g., learning habits, usage trends)
goal	Explicit goals (e.g., targets, milestones)

Origin

How the memory was created.

Value	Description
user	Explicitly created by the user
inferred	AI-derived from interactions
imported	Imported from an external source
system	Platform-generated by the system

Freshness Lifecycle

Memories progress through freshness states over time:

active → stale → archived

Value	Description
active	Current and relevant
stale	Not recently accessed or updated — may need review
archived	No longer active — retained for history

Confidence

How reliable the memory is considered to be.

Value	Description
low	Uncertain — may need verification
medium	Reasonable confidence (default for new memories)
high	Well-established and verified

---

Content Validation

INFO

Memory content is validated before storage. Requests that fail validation return a 400 Bad Request response.

• Max content length: 10,000 characters
• Prompt injection: Content is validated against prompt injection patterns and rejected if suspicious
• Null bytes: Content containing null bytes (\0) is rejected
• Empty content: The content field must be non-empty