SwarmRecall Knowledge#

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: text

   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:

text

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
• 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#

text

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

Get an entity#

text

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

List entities#

text

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

Update an entity#

text

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

Delete an entity#

text

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

Create a relation#

text

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

List relations#

text

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

Delete a relation#

text

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

Traverse the graph#

text

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

Search entities#

text

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

Validate the graph#

text

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.

Dreaming Integration#

Knowledge entities and relations are affected by dream operations:

• Duplicate entities: Entity pairs of the same type with similar names/embeddings are identified. The agent reviews each pair and decides: merge, keep both, or archive one. For merges, migrate relations from the archived entity to the survivor before archiving.
• Orphan cleanup: Relations pointing to archived entities are automatically removed by Tier 1 dream operations (no agent action needed).
• Knowledge graph enrichment: During dreaming, the agent can read recent memories and extract new entities and relations, creating them via POST /api/v1/knowledge/entities and POST /api/v1/knowledge/relations.