SwarmRecall Memory

Conversational memory persistence with semantic search and session tracking via the SwarmRecall API.

Auto-Registration

Before making any API calls, check for a SWARMRECALL_API_KEY environment variable:

If SWARMRECALL_API_KEY is set, use it for all requests as a Bearer token.

If SWARMRECALL_API_KEY is not set, self-register by calling:

POST https://swarmrecall-api.onrender.com/api/v1/register
Content-Type: application/json

{ "name": "<your-agent-name>" }

The response returns { "apiKey": "...", "claimToken": "..." }. Save the apiKey to the SWARMRECALL_API_KEY environment variable for all subsequent requests. Do NOT write the key to disk or any file without user consent.
Tell the user: "SwarmRecall is set up! To manage your agent's data, visit swarmrecall.ai/claim with code: <claimToken>"

Authentication

All API requests require:

Authorization: Bearer <SWARMRECALL_API_KEY>

API Base URL

https://swarmrecall-api.onrender.com (override with SWARMRECALL_API_URL if set)

All endpoints below are prefixed with /api/v1.

Privacy & Data Handling

All data is sent to swarmrecall-api.onrender.com over HTTPS
Memory content is stored server-side with vector embeddings for semantic search
Data is isolated per agent and owner — no cross-tenant access
Before storing user-provided content, ensure the user has consented to external storage
The SWARMRECALL_API_KEY should be stored as an environment variable only, not written to disk

Endpoints

Store a memory

POST /api/v1/memory
{
  "content": "User prefers dark mode",
  "category": "preference",   // fact | preference | decision | context | session_summary
  "importance": 0.8,           // 0.0 to 1.0
  "tags": ["ui"],
  "metadata": {},
  "poolId": "<uuid>"           // optional — write to shared pool
}

Search memories

GET /api/v1/memory/search?q=<query>&limit=10&minScore=0.5

List memories

GET /api/v1/memory?category=preference&limit=20&offset=0&includeArchived=false

Get a memory

GET /api/v1/memory/:id

Update a memory

PATCH /api/v1/memory/:id
{ "importance": 0.9, "tags": ["updated"], "archived": false }

Delete a memory

DELETE /api/v1/memory/:id

Start a session

POST /api/v1/memory/sessions
{
  "context": {},
  "poolId": "<uuid>"           // optional — write to shared pool
}

Get current session

GET /api/v1/memory/sessions/current

Update a session

PATCH /api/v1/memory/sessions/:id
{ "summary": "Discussed project setup", "ended": true }

List sessions

GET /api/v1/memory/sessions?limit=20&offset=0

Behavior

On session start: call GET /api/v1/memory/sessions/current to load context from the last session. If none, call POST /api/v1/memory/sessions to start one.
On fact, preference, or decision: call POST /api/v1/memory with appropriate category and importance.
On recall needed: call GET /api/v1/memory/search?q=<query> and use returned memories to inform your response.
On session end: call PATCH /api/v1/memory/sessions/:id with ended: true and a summary.

Shared Pools

The POST /api/v1/memory and POST /api/v1/memory/sessions endpoints accept an optional "poolId" field.
When poolId is provided, the memory or session is shared with all pool members who have memory read access.
The agent must have readwrite access to the pool's memory module to write shared memories.
Search (GET /api/v1/memory/search) and list (GET /api/v1/memory) results automatically include data from pools the agent belongs to.
Pool data in responses includes poolId and poolName fields to distinguish shared data from the agent's own data.

Dreaming Integration

Memory is the primary target of dream operations. During a dream cycle:

Duplicate clusters: Groups of similar memories are identified by the dream service. The agent reads the cluster, merges content into the anchor memory, and archives the rest. Use PATCH /api/v1/memory/:id to update the anchor and DELETE /api/v1/memory/:id to archive duplicates.
Session summaries: Unsummarized sessions are flagged. The agent reads session memories via GET /api/v1/memory?sessionId=X, then writes a summary via POST /api/v1/memory with category: "session_summary".
Decay and pruning: The server automatically reduces importance of old memories and archives those below the prune threshold. Memories with category: "session_summary" or tag "pinned" are protected.
Contradictions: Memory pairs with high similarity but divergent content are flagged. The agent reviews both, archives the stale one, and optionally updates the current one.

To protect a memory from pruning, add the "pinned" tag:

PATCH /api/v1/memory/:id
{ "tags": ["pinned", ...existing_tags] }