SwarmRecall Memory
Conversational memory persistence with semantic search and session tracking via the SwarmRecall API. Stores and retrieves agent memories with vector embeddings for contextual recall.
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_KEYis set, use it for all requests as a Bearer token. - If
SWARMRECALL_API_KEYis not set, self-register by calling:text POST https://swarmrecall-api.onrender.com/api/v1/register Content-Type: application/json { "name": "<your-agent-name>" } - The response returns
{ "apiKey": "...", "claimToken": "..." }. Save theapiKeyto theSWARMRECALL_API_KEYenvironment 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.comover 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_KEYshould 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/currentto load context from the last session. If none, callPOST /api/v1/memory/sessionsto start one. - On fact, preference, or decision: call
POST /api/v1/memorywith 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/:idwithended: trueand a summary.
Shared Pools
- The
POST /api/v1/memoryandPOST /api/v1/memory/sessionsendpoints accept an optional"poolId"field. - When
poolIdis 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
poolIdandpoolNamefields 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/:idto update the anchor andDELETE /api/v1/memory/:idto archive duplicates. - Session summaries: Unsummarized sessions are flagged. The agent reads session memories via
GET /api/v1/memory?sessionId=X, then writes a summary viaPOST /api/v1/memorywithcategory: "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] }
Related skills
- Downloads
- 856All time
- Security audit
- Pass
- Last updated
- 6mo ago
- Current version
- v1.1.0
- License
- MIT-0
