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:

1. If SWARMRECALL_API_KEY is set, use it for all requests as a Bearer token.
2. 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>" }
   

3. 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.
4. 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] }