swarmrecall-learnings

# SwarmRecall Learnings Error tracking, correction logging, and pattern detection 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 - Learning data (errors, corrections, discoveries) 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 ### Log a learning ``` POST /api/v1/learnings { "category": "error", // error | correction | discovery | optimization | preference "summary": "npm install fails with peer deps", "details": "Full error output...", "priority": "high", // low | medium | high | critical "area": "build", "suggestedAction": "Use --legacy-peer-deps flag", "tags": ["npm", "build"], "metadata": {}, "poolId": "<uuid>" // optional — write to shared pool } ``` ### Search learnings ``` GET /api/v1/learnings/search?q=<query>&limit=10&minScore=0.5 ``` ### Get a learning ``` GET /api/v1/learnings/:id ``` ### List learnings ``` GET /api/v1/learnings?category=error&status=open&priority=high&area=build&limit=20&offset=0 ``` ### Update a learning ``` PATCH /api/v1/learnings/:id { "status": "resolved", "resolution": "Added --legacy-peer-deps", "resolutionCommit": "abc123" } ``` ### Get recurring patterns ``` GET /api/v1/learnings/patterns ``` ### Get promotion candidates ``` GET /api/v1/learnings/promotions ``` ### Link related learnings ``` POST /api/v1/learnings/:id/link { "targetId": "<other-learning-id>" } ``` ## 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. ## Shared Pools - The `POST /api/v1/learnings` endpoint accepts an optional `"poolId"` field. - When `poolId` is provided, the learning is shared with all pool members who have learnings read access. - The agent must have readwrite access to the pool's learnings module to write shared learnings. - Search (`GET /api/v1/learnings/search`) and list (`GET /api/v1/learnings`) 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 Learnings benefit from dream-time promotion: - **Promotion candidates**: The existing `GET /api/v1/learnings/promotions` endpoint surfaces patterns meeting promotion criteria (3+ recurrences, 2+ sessions, within 30 days). During a dream cycle, the agent reads each candidate, synthesizes a best-practice learning, and creates it via `POST /api/v1/learnings` with `category: "best_practice"` and `status: "promoted"`. - **Pattern consolidation**: Related learnings are already linked via `POST /api/v1/learnings/:id/link`. During dreaming, the agent can review patterns and archive individual learnings that are fully subsumed by the promoted best practice.