SwarmRecall Knowledge

Knowledge graph with entities, relations, traversal, and semantic search via the SwarmRecall API. Build and query structured knowledge graphs with vector emb...

Security Scan

The skill's requirements and runtime instructions are consistent with a SwarmRecall knowledge-graph API integration, but there are a few small mismatches and privacy points you should review before use.

Purpose & Capability

The skill claims to provide knowledge-graph operations via the SwarmRecall API and only requests a single API key (SWARMRECALL_API_KEY). The endpoints and behaviors described match that purpose.

Instruction Scope

Instructions are largely scoped to API calls for creating, querying, traversing, and validating graph data. Two things to note: (1) Auto-registration instructs the agent to obtain an apiKey if none exists and asks to 'save the apiKey to the SWARMRECALL_API_KEY environment variable' — the skill does not explicitly show how the agent should persist that (it rightly warns not to write to disk without consent), and (2) the SKILL.md references an optional SWARMRECALL_API_URL override but that env var is not declared in the registry metadata. The skill correctly calls out that user consent should be obtained before storing personal/sensitive data.

Install Mechanism

No install spec or downloaded code is present; this is an instruction-only skill, which reduces filesystem/installation risk.

Credentials

Only SWARMRECALL_API_KEY is required and is appropriate for this integration. Minor issues: SKILL.md mentions an optional SWARMRECALL_API_URL (not declared in requires.env) and instructs saving an auto-provisioned apiKey to an environment variable — this requires explicit user consent and care. The skill also supports optional 'poolId' writes which will share data with other tenants, so the API key grants write/read access to potentially shared pools and should be treated accordingly.

Persistence & Privilege

always is false, no system paths or other skills' configs are requested, and the skill doesn't request persistent installation. It will store user-provided knowledge on SwarmRecall servers (as documented) if used — this is consistent with its purpose but is a persistence implication to be aware of.

Assessment

This skill appears to do what it says: it uses a single SwarmRecall API key to create and query graph entities. Before installing: (1) Understand that any data you store will be sent to api.swarmrecall.ai and may be stored in shared pools if you supply a poolId — get explicit user consent before uploading personal or sensitive information; (2) the skill will attempt auto-registration if no API key is present — insist the agent ask you before it stores or persists any returned apiKey, and don't allow it to write secrets to disk automatically; (3) review the service's privacy policy and whether pool sharing is acceptable for your data; (4) rotate and scope the SWARMRECALL_API_KEY appropriately (least privilege), and consider using an account dedicated to agent integrations; (5) note minor mismatches in the SKILL.md (an undeclared SWARMRECALL_API_URL override and a version string mismatch) — they look like documentation issues rather than functional problems, but you may want to confirm the correct base URL and environment names with the vendor.

Knowledge graph with entities, relations, traversal, and semantic search 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
• Knowledge graph data (entities, relations) 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

Create an entity

POST /api/v1/knowledge/entities
{
  "type": "person",
  "name": "Alice",
  "properties": { "role": "engineer" },
  "poolId": "<uuid>"           // optional — write to shared pool
}

Get an entity

GET /api/v1/knowledge/entities/:id

List entities

GET /api/v1/knowledge/entities?type=person&limit=20&offset=0&includeArchived=false

Update an entity

PATCH /api/v1/knowledge/entities/:id
{ "name": "Alice Smith", "properties": { "role": "senior engineer" } }

Delete an entity

DELETE /api/v1/knowledge/entities/:id

Create a relation

POST /api/v1/knowledge/relations
{
  "fromEntityId": "<id>",
  "toEntityId": "<id>",
  "relation": "works_on",
  "properties": {},
  "poolId": "<uuid>"           // optional — write to shared pool
}

List relations

GET /api/v1/knowledge/relations?entityId=<id>&relation=works_on&limit=20&offset=0

Delete a relation

DELETE /api/v1/knowledge/relations/:id

Traverse the graph

GET /api/v1/knowledge/traverse?startId=<id>&relation=works_on&depth=2&limit=50

Search entities

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

Validate the graph

POST /api/v1/knowledge/validate

Behavior

• When the user provides structured information: create entities with POST /api/v1/knowledge/entities.
• When linking concepts: create relations with POST /api/v1/knowledge/relations.
• When the user asks "what do I know about X?": search with GET /api/v1/knowledge/search?q=X, then traverse with GET /api/v1/knowledge/traverse to explore connections.
• Periodically: call POST /api/v1/knowledge/validate to check graph constraints.

Shared Pools

• The POST /api/v1/knowledge/entities and POST /api/v1/knowledge/relations endpoints accept an optional "poolId" field.
• When poolId is provided, the entity or relation is shared with all pool members who have knowledge read access.
• The agent must have readwrite access to the pool's knowledge module to write shared entities and relations.
• Search (GET /api/v1/knowledge/search) and list (GET /api/v1/knowledge/entities, GET /api/v1/knowledge/relations) 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.