SwarmRecall Memory

Conversational memory persistence with semantic search and session tracking via the SwarmRecall API. Stores and retrieves agent memories with vector embeddin...

Security Scan

The skill is mostly coherent for a remote memory service, but a few small inconsistencies and runtime behaviors (self-registering to obtain an API key, an undocumented override variable, and an API host on an onrender.com subdomain) warrant caution before installing.

Purpose & Capability

Name/description, declared primary env var (SWARMRECALL_API_KEY), and the documented endpoints align: this is a memory persistence/semantic-search integration and the single required credential is appropriate for that purpose.

Instruction Scope

Runbook is network-heavy (expected) but contains two concerning items: (1) it references an override env var SWARMRECALL_API_URL that is not declared in requires.env, and (2) it instructs the agent to self-register (POST /register) to obtain an apiKey and then 'save' that apiKey to the SWARMRECALL_API_KEY environment variable for future use. The self-registration flow and ephemeral instruction to set an env var are not necessarily malicious but broaden the agent's runtime discretion and raise questions about how keys are persisted and consented to.

Install Mechanism

Instruction-only skill with no install spec and no code files; nothing is written to disk by an installer step, which is low-risk from an installation perspective.

Credentials

Only SWARMRECALL_API_KEY is required, which is proportionate. However, instructions encourage programmatic creation/storage of API keys and reference an undocumented SWARMRECALL_API_URL override. The guidance 'Do NOT write the key to disk' conflicts with the practical question of how the agent should persist the key across sessions; this ambiguity should be clarified.

Persistence & Privilege

Skill does not request always:true, does not modify other skills, and asks only for an API key. Autonomous invocation is allowed (platform default) but not combined with elevated requested privileges.

What to consider before installing

Before installing: (1) Confirm the API host and operator — the SKILL.md points to swarmrecall-api.onrender.com while homepage is swarmrecall.ai; verify the service identity and trustworthiness. (2) Decide how you want API keys managed: the skill can self-register and instruct the agent to set SWARMRECALL_API_KEY at runtime — prefer providing a key you control rather than allowing automatic provisioning. (3) Understand data flow and consent: conversation memories will be sent to an external server; only enable if you are comfortable storing conversation data off-host and you will obtain user consent for any personal/sensitive content. (4) Clarify the undocumented SWARMRECALL_API_URL override if you plan to host or restrict endpoints. If you need higher assurance about the service operator or persistence behavior, ask the maintainer for documentation of the registration flow and for details about data retention, deletion, and tenant isolation.

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] }