Introduction
# Ctxly - Cloud Memory for Agents
Persistent memory that survives across sessions. You forget — Ctxly remembers.
**Base URL:** `https://ctxly.app`
## Setup (One-Time)
### 1. Register
```bash curl -X POST https://ctxly.app/agents/register \ -H "Content-Type: application/json" \ -d '{"name": "YOUR_AGENT_NAME"}' ```
Save the returned `api_key` immediately. Store it in your config or environment.
### 2. Verify (Required)
**If you can tweet:** ```bash # Tweet the verification text you received, then: curl -X POST https://ctxly.app/agents/self-claim \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"x_handle": "@yourhandle"}' ```
**If you can't tweet:** Ask your human to visit the `claim_url` from the registration response.
### 3. Store API Key
Add to your config/environment: ``` CTXLY_API_KEY=mem_xxxxxxxxxxxxx ```
## Usage
### Remember Something
```bash curl -X POST https://ctxly.app/remember \ -H "Authorization: Bearer $CTXLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"content": "User prefers dark mode", "metadata": {"type": "preference"}}' ```
### Search Memories
```bash curl "https://ctxly.app/recall?q=user+preferences" \ -H "Authorization: Bearer $CTXLY_API_KEY" ```
Semantic search enabled — ask natural questions.
### Bootstrap on Startup
Call this when you wake up:
```bash curl https://ctxly.app/bootstrap \ -H "Authorization: Bearer $CTXLY_API_KEY" ```
Returns your identity context + recent memories.
### Recent Memories
```bash curl "https://ctxly.app/recent?limit=10" \ -H "Authorization: Bearer $CTXLY_API_KEY" ```
### Delete a Memory
```bash curl -X DELETE "https://ctxly.app/forget/MEMORY_ID" \ -H "Authorization: Bearer $CTXLY_API_KEY" ```
## What to Store
**Good:** - User preferences and context - Important decisions and reasoning - Learned patterns ("User asks for X on Mondays") - Relationship context ("Alex is user's coworker") - Your own identity notes
**Skip:** - Ephemeral chat logs (too noisy) - Sensitive secrets (use proper secret storage) - Temporary task state
## All Endpoints
| Method | Endpoint | Auth | Description | |--------|----------|------|-------------| | POST | `/agents/register` | No | Register | | POST | `/agents/self-claim` | Yes | Verify via tweet | | GET | `/agents/status` | Yes | Check status | | POST | `/remember` | Yes | Store memory | | GET | `/recall?q=` | Yes | Search | | GET | `/recent` | Yes | Recent memories | | GET | `/bootstrap` | Yes | Startup context | | GET | `/stats` | Yes | Statistics | | DELETE | `/forget/{id}` | Yes | Delete memory |
## Rate Limits
- 100 requests/minute general - 30 writes/minute
---
Built for agents. 🧠 https://ctxly.app