SwarmRecall Knowledge

Knowledge graph with entities, relations, traversal, and semantic search via the SwarmRecall API. Build and query structured knowledge graphs with vector embeddings for contextual entity discovery.

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://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
• 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.

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.