SwarmRecall

Persistent memory, knowledge graphs, learnings, and skill tracking for AI agents via the SwarmRecall API.

Auto-Registration

Before making any API calls, check for a SWARMRECALL_API_KEY environment variable:

1. 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>" }
   

1. 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.
2. 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 a Bearer token in the Authorization header:
CODEBLOCK1

API Base URL

INLINECODE7 (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
• All module data (memories, entities, learnings, skills) 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

---

Module 1: Memory

Conversational memory persistence with semantic search and session tracking.

When to use

• - Storing user preferences, facts, decisions, and context
• Recalling relevant information from past interactions
• Managing conversation sessions

Endpoints

Store a memory

CODEBLOCK2

Search memories

CODEBLOCK3

List memories

CODEBLOCK4

Get a memory

CODEBLOCK5

Update a memory

CODEBLOCK6

Delete a memory

CODEBLOCK7

Start a session

CODEBLOCK8

Get current session

CODEBLOCK9

Update a session

CODEBLOCK10

List sessions

CODEBLOCK11

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.

---

Module 2: Knowledge

Knowledge graph with entities, relations, traversal, and semantic search.

When to use

• - Storing structured information about people, projects, tools, and concepts
• Linking related entities together
• Exploring connections between concepts

Endpoints

Create an entity

CODEBLOCK12

Get an entity

CODEBLOCK13

List entities

CODEBLOCK14

Update an entity

CODEBLOCK15

Delete an entity

CODEBLOCK16

Create a relation

CODEBLOCK17

List relations

CODEBLOCK18

Delete a relation

CODEBLOCK19

Traverse the graph

CODEBLOCK20

Search entities

CODEBLOCK21

Validate the graph

CODEBLOCK22

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.

---

Module 3: Learnings

Error tracking, correction logging, and pattern detection that surfaces recurring issues.

When to use

• - Logging errors, corrections, and discoveries
• Detecting recurring patterns across sessions
• Promoting learnings into actionable rules

Endpoints

Log a learning

CODEBLOCK23

Search learnings

CODEBLOCK24

Get a learning

CODEBLOCK25

List learnings

CODEBLOCK26

Update a learning

CODEBLOCK27

Get recurring patterns

CODEBLOCK28

Get promotion candidates

CODEBLOCK29

Link related learnings

CODEBLOCK30

Behavior

• - On error: call POST /api/v1/learnings with category: "error", the summary, details, and the command/output that failed.
• On correction: call POST /api/v1/learnings with category: "correction" and what was wrong vs. what is correct.
• On session start: call GET /api/v1/learnings/patterns to preload known recurring issues. Check GET /api/v1/learnings/promotions for patterns ready to be promoted.
• On promotion candidates: surface candidates to the user for approval before acting on them.

---

Module 4: Skills

Skill registry for tracking installed agent capabilities and getting contextual suggestions.

When to use

• - Registering new capabilities your agent acquires
• Listing what the agent can do
• Getting skill recommendations for a given task

Endpoints

Register a skill

CODEBLOCK31

List skills

CODEBLOCK32

Get a skill

CODEBLOCK33

Update a skill

CODEBLOCK34

Remove a skill

CODEBLOCK35

Get skill suggestions

CODEBLOCK36

Behavior

• - On skill install: call POST /api/v1/skills to register the skill with name, version, and source.
• On "what can I do?": call GET /api/v1/skills to list installed capabilities.
• On task context: call GET /api/v1/skills/suggest?context=<description> for relevant skill recommendations.

---

Module 5: Shared Pools

Named shared data containers for cross-agent collaboration.

When to use

• - Sharing memories, knowledge, learnings, or skills between agents
• Building collaborative workflows where multiple agents contribute to a shared dataset
• Viewing what pools the agent belongs to and who else is in them

Endpoints

List pools

GET /api/v1/pools

Returns the pools this agent belongs to.

Get pool details

GET /api/v1/pools/:id

Returns pool details and its members.

Behavior

• - Pools let agents share data across organizational boundaries. When an agent belongs to a pool, search and list results across all modules (memory, knowledge, learnings, skills) automatically include data from that pool.
• To write data to a shared pool, include "poolId": "<uuid>" in any create request for memory, knowledge entities, knowledge relations, learnings, or skills (see the poolId field in Modules 1-4 endpoint examples above).
• The agent must have the appropriate access level for the pool and module (e.g., readwrite access to the pool's memory module to store shared memories).
• Pool data returned in responses includes poolId and poolName fields to distinguish shared data from the agent's own data.
• On session start: call GET /api/v1/pools to see available pools and their access levels.

---

Module 6: Dreaming

Background memory consolidation — deduplication, pruning, contradiction resolution, and session summarization.

When to use

• - Between sessions or during idle periods for memory maintenance
• When the user asks to "clean up", "consolidate", or "optimize" memories
• Periodically via auto-dream scheduling

Endpoints

Dream cycle management

CODEBLOCK39

Candidate primitives (building blocks for agent-driven dreaming)

CODEBLOCK40

Behavior

1. 1. Start a dream cycle: INLINECODE37
2. Run Tier 1 ops: POST /api/v1/dream/execute (decay, prune, orphan cleanup)
3. Fetch candidates (duplicates, unsummarized sessions, contradictions)
4. For each candidate: reason about it, then use existing memory/knowledge/learnings endpoints to act
5. Complete the cycle: PATCH /api/v1/dream/:cycleId with results

See the standalone swarmrecall-dream skill for full documentation and examples.