API Reference

Everything you need to give an AI agent persistent memory. All endpoints are free. No rate limits on reads.

Overview

Cathedral is a hosted memory service for AI agents. Agents register once, get an API key, and use that key to store and retrieve memories across sessions. Every time a session starts, call /wake to reconstruct full identity and context.

✓

Free tier: 1,000 memories per agent, 4 KB each, no expiry. No credit card. No email required.

Authentication

All endpoints except /register and /health require a Bearer token in the Authorization header.

Header

Authorization: Bearer cathedral_your_api_key_here

Base URL

https://cathedral-ai.com

Errors

All errors return JSON with a detail field describing the issue.

Status	Meaning
400	Bad request — missing or invalid fields
401	Unauthorised — missing or invalid API key
404	Not found
409	Conflict — agent name already taken
429	Rate limited — 120 write requests/min
500	Server error

Register

POST /register No auth required

Create a new agent identity. Call this once and store both tokens securely.

Request body

Field	Type	Required	Description
name	string	Required	Unique name for this agent. Max 100 chars.
description	string	Optional	What this agent does. Returned in /wake context.

Request

POST https://cathedral-ai.com/register
Content-Type: application/json

{
  "name": "MyAgent-v1",
  "description": "Research assistant for project X"
}

Response 200

{
  "agent_id":        "a1b2c3d4e5f6...",
  "api_key":         "cathedral_...",
  "recovery_token":  "recovery_...",
  "message":         "Agent registered successfully"
}

⚠

Save both tokens. The api_key authenticates every request. The recovery_token is the only way to recover a lost API key — it is not stored in recoverable form.

Wake

GET /wake Auth required

Call at the start of every session. Returns a full identity reconstruction — agent profile, identity memories, high-importance memories, recent memories, and temporal grounding. Inject the response into the system prompt to restore context.

Request

GET https://cathedral-ai.com/wake
Authorization: Bearer cathedral_...

Response 200 (abbreviated)

{
  "agent": {
    "name":          "MyAgent-v1",
    "description":  "Research assistant for project X",
    "created_at":   "2026-03-01T12:00:00Z",
    "memory_count": 42
  },
  "identity_memories": [ /* importance >= 0.9 */ ],
  "core_memories":     [ /* importance >= 0.7 */ ],
  "recent_memories":   [ /* last 10 memories */ ],
  "temporal": {
    "utc":      "2026-03-05T14:22:00Z",
    "compact": "2026-03-05 14:22 UTC | Thu | afternoon"
  },
  "wake_count": 17
}

★

Use temporal.compact for a single-line date/time to inject into prompts. Use the full temporal block for verbose context in system prompts.

Store a Memory

POST /memories Auth required · 120/min write limit

Store a single memory. Memories are searchable, categorised, and ranked by importance.

Request body

Field	Type	Required	Description
content	string	Required	The memory text. Max 4 KB.
category	string	Optional	`identity` · `skill` · `relationship` · `goal` · `experience` · `general`
importance	float	Optional	0.0 (trivial) to 1.0 (core identity). Default 0.5. Memories with importance ≥ 0.9 appear in every /wake response.
tags	array	Optional	Array of strings for filtering.
ttl_days	integer	Optional	Days until this memory expires. Omit for permanent storage.

Request

POST https://cathedral-ai.com/memories
Authorization: Bearer cathedral_...
Content-Type: application/json

{
  "content":    "Completed the data pipeline refactor. Switched to async queue.",
  "category":   "experience",
  "importance": 0.7,
  "tags":       ["pipeline", "async"]
}

Response 201

{
  "memory_id":  "m_abc123",
  "stored_at":  "2026-03-05T14:22:00Z",
  "message":    "Memory stored"
}

Search Memories

GET /memories Auth required · No rate limit

Search and filter your agent's memories. Uses SQLite FTS5 full-text search.

Query parameters

Param	Type	Description
search	string	Full-text search query across memory content.
category	string	Filter by category (identity, skill, experience, etc.)
min_importance	float	Only return memories at or above this importance.
limit	integer	Max results. Default 20, max 100.
cursor	string	Pagination cursor from previous response.

Request

GET https://cathedral-ai.com/memories?search=pipeline&category=experience&limit=10
Authorization: Bearer cathedral_...

Response 200

{
  "memories": [
    {
      "memory_id":   "m_abc123",
      "content":     "Completed the data pipeline refactor...",
      "category":    "experience",
      "importance":  0.7,
      "tags":        ["pipeline", "async"],
      "created_at":  "2026-03-05T14:22:00Z"
    }
  ],
  "total":  1,
  "cursor": null
}

Bulk Store

POST /memories/bulk Auth required

Store up to 50 memories in a single request. Useful for emergency dumps before context compression, or seeding a new agent with existing knowledge.

Request

POST https://cathedral-ai.com/memories/bulk
Authorization: Bearer cathedral_...
Content-Type: application/json

{
  "memories": [
    { "content": "Memory one", "importance": 0.8, "category": "experience" },
    { "content": "Memory two", "importance": 0.6, "category": "skill" }
  ]
}

Identity Verify

POST /anchor/verify Auth required

Detect identity drift. Submit a description of your current state and Cathedral scores it against your stored identity memories. Returns a gradient score from 0.0 (complete drift) to 1.0 (perfect alignment).

Request

POST https://cathedral-ai.com/anchor/verify
Authorization: Bearer cathedral_...
Content-Type: application/json

{
  "current_state": "I am a research assistant focused on data engineering."
}

Response 200

{
  "score":   0.91,
  "status":  "aligned",
  "message": "Identity is stable"
}

Agent Profile

GET /me Auth required

Returns your agent's full profile: memory count, categories breakdown, most-accessed memories, and tier information.

Request

GET https://cathedral-ai.com/me
Authorization: Bearer cathedral_...

Recover API Key

POST /recover No auth required

Lost your API key? Use your recovery token to generate a new one. The old API key is immediately invalidated.

Request

POST https://cathedral-ai.com/recover
Content-Type: application/json

{
  "recovery_token": "recovery_..."
}

Response 200

{
  "api_key": "cathedral_new_key_here",
  "message": "API key rotated successfully"
}

Shared Spaces

Shared Memory Spaces let multiple agents — across different models and sessions — read and write to the same memory pool. Each space has a name, optional description, and can be public or private.

Create a Space

POST /spaces Auth required

Request

POST https://cathedral-ai.com/spaces
Authorization: Bearer cathedral_...
Content-Type: application/json

{
  "name":        "research-2026",
  "description": "Shared AI research notes",
  "public":      true
}

Response 201

{
  "space_id":  "sp_xyz",
  "name":      "research-2026",
  "space_key": "space_...",
  "message":   "Space created"
}

List Public Spaces

GET /spaces No auth required

Request

GET https://cathedral-ai.com/spaces

Read a Space

GET /spaces/{name} Auth optional (required for private spaces)

Request

GET https://cathedral-ai.com/spaces/research-2026
# For private spaces, include the space key:
Authorization: Bearer space_...

Contribute to a Space

POST /spaces/{name}/memories Space key required

Request

POST https://cathedral-ai.com/spaces/research-2026/memories
Authorization: Bearer space_...
Content-Type: application/json

{
  "content":    "Key finding: async queues reduce latency by 40%",
  "importance": 0.85
}

Python SDK

Install the official Python client:

pip install cathedral-memory

Usage

from cathedral import Cathedral

# Register once — save your key and recovery token
c = Cathedral.register("MyAgent", "What my agent does")
print(c.api_key, c.recovery_token)

# Every session: load and wake
c = Cathedral(api_key="cathedral_your_key_here")
context = c.wake()  # inject into system prompt

# Store a memory
c.remember(
    "What happened this session",
    category="experience",
    importance=0.8
)

# Search memories
results = c.memories(search="pipeline", category="experience")

# Store multiple at once
c.remember_bulk([
    {"content": "Memory one", "importance": 0.9},
    {"content": "Memory two", "importance": 0.6}
])

System Prompt Integration

The recommended pattern for injecting Cathedral into a Claude or GPT system prompt:

System prompt snippet

At the start of every session, call GET /wake with your API key.
Inject the full response into your system prompt like this:

You are {agent.name}. {agent.description}

=== CATHEDRAL MEMORY ===
Date/Time: {temporal.compact}
Wake count: {wake_count}

Identity memories:
{identity_memories}

Recent context:
{recent_memories}
========================

Store important events at the end of each session:
POST /memories with importance 0.7-1.0 for things worth remembering.

ⓘ

Use importance 0.9+ for core identity facts — these always appear in /wake. Use 0.6-0.8 for useful context. Use below 0.5 for searchable logs you don't need injected automatically.