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 coherent with its stated purpose: it calls an external SwarmRecall API using a single API key to store and search agent memories; nothing requested or instructed appears disproportionate or unrelated to that purpose.

Purpose & Capability

Name and description (conversational memory, semantic search) match the declared requirement (a single SWARMRECALL_API_KEY) and the SKILL.md endpoints. There are no unrelated credentials, binaries, or install steps that would be out of scope for a memory persistence integration.

Instruction Scope

Runtime instructions are narrowly scoped to registering/using an API key, calling memory and session endpoints, and honoring user consent before storing sensitive data. Two minor notes: (1) the SKILL.md references an optional override variable SWARMRECALL_API_URL which is not declared in the registry metadata; (2) the auto-registration flow instructs the agent to 'save the apiKey to the SWARMRECALL_API_KEY environment variable' but doesn't specify how to persist it safely across agent runs (and includes a contradictory admonition not to write the key to disk without consent). Also be aware that shared pool functionality can expose stored memories to other pool members — the agent must obtain user consent before writing user data to pools.

Install Mechanism

Instruction-only skill with no install spec and no code files; nothing is downloaded or written to disk by the skill itself. This has a low install risk.

Credentials

Only one credential is required (SWARMRECALL_API_KEY) and it is the declared primary credential. That matches the skill's purpose and is proportionate. No other secrets or unrelated credentials are requested.

Persistence & Privilege

The skill is not marked always:true and uses the default autonomous-invocation capability. That is normal for skills that provide runtime behavior. Note that autonomous invocation will allow the agent to call an external service (api.swarmrecall.ai) during conversations; combined with the memory-storing behavior, ensure the agent follows the consent guidance before persisting user data.

Assessment

This skill is coherent for storing and searching conversational memory with SwarmRecall, but review these practical considerations before installing: (1) confirm you trust https://api.swarmrecall.ai and review their privacy/security docs (deletion, retention, tenant isolation); (2) be careful about what the agent stores — follow the SKILL.md requirement to obtain user consent before storing personal or sensitive data, and avoid writing secrets to disk; (3) shared pools mean memories can be visible to other pool members — only write to pools when appropriate; (4) the auto-registration flow will create an API key if none is present — decide whether you prefer to provision the key manually and set SWARMRECALL_API_KEY yourself; (5) verify how your agent runtime persists environment variables (the skill's instruction to 'save' the key to an env var may require manual intervention) and consider rotating/revoking the key if you stop using the service.

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://api.swarmrecall.ai/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://api.swarmrecall.ai (override with SWARMRECALL_API_URL if set)

All endpoints below are prefixed with /api/v1.

Privacy & Data Handling

• All data is sent to api.swarmrecall.ai 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.