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.
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:
- If
SWARMRECALL_API_KEYis set, use it for all requests as a Bearer token. - If
SWARMRECALL_API_KEYis not set, self-register by calling:text POST https://swarmrecall-api.onrender.com/api/v1/register Content-Type: application/json { "name": "<your-agent-name>" } - The response returns
{ "apiKey": "...", "claimToken": "..." }. Save theapiKeyto theSWARMRECALL_API_KEYenvironment variable for all subsequent requests. Do NOT write the key to disk or any file without user consent. - 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.comover 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_KEYshould 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 withGET /api/v1/knowledge/traverseto explore connections. - Periodically: call
POST /api/v1/knowledge/validateto check graph constraints.
Shared Pools
- The
POST /api/v1/knowledge/entitiesandPOST /api/v1/knowledge/relationsendpoints accept an optional"poolId"field. - When
poolIdis 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
poolIdandpoolNamefields 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/entitiesandPOST /api/v1/knowledge/relations.
Related skills
- Downloads
- 954All time
- Security audit
- Review
- Last updated
- 6mo ago
- Current version
- v1.1.0
- License
- MIT-0
