# Recall AI

> Long-term memory for AI agents. Save what an agent learns, find it in milliseconds,
> and let newer facts supersede older ones. Hosted API, MCP server, CLI and TypeScript SDK.
> Recall AI is developed and maintained by Nidonic Labs.

Base URL: https://recallai.nidonic.online
Auth: send `Authorization: Bearer rc_...` (or `X-API-Key: rc_...`) on every request.
Get a key: a human signs up at https://recallai.nidonic.online/console (email code or Google), then creates one under Settings → API keys,
or runs `npx @recall-ai/cli login` (opens the browser; the machine gets its own key).
TypeScript: npm install @recall-ai/sdk

## Concepts

- realm: a hard isolation boundary in the URL path (one per user, tenant or project).
  Pattern ^[a-zA-Z0-9_:-]+$, max 255 chars. Created on first save.
- file: text you save. It is split into pieces, embedded and findable within seconds.
- note: a fact taken from a file. When a newer note contradicts an older one, it supersedes it:
  the newer note becomes the latest version and the older one is kept as history.
- about: a realm's core facts (stable) and changing facts (recent), ready to put in a prompt.
- sync: a background step that decides which notes supersede, build on or repeat others.
  "continuous" (default) batches it per realm; "instant" (paid plans) runs it right away for one file.

## Endpoints

POST   /v1/realms/{realm}/file                   {"content": "...", "metadata": {...}, "externalId": "...", "sync": "continuous"|"instant"}  -> 202 {id, status}
POST   /v1/realms/{realm}/files                  {"documents": ["...", {...}]}  (up to 100; per-item errors)
GET    /v1/realms/{realm}/files                  ?page=1&limit=20
GET    /v1/realms/{realm}/files/{id}             ?include=chunks,memories  -> status: queued|extracting|chunking|embedding|done|failed
DELETE /v1/realms/{realm}/files/{id}
POST   /v1/realms/{realm}/find                   {"q": "...", "limit": 10, "mode": "hybrid"|"notes"|"pieces"}
GET    /v1/realms/{realm}/about
POST   /v1/realms/{realm}/notes/remove           {"ids": [...]} or {"query": "...", "dryRun": true}
POST   /v1/realms/{realm}/sync                   run sync for the realm now
GET    /v1/realms/{realm}/explorer               File Explorer: the realm as Markdown files
GET    /v1/realms/{realm}/explorer/{path}        RECALL.md, index.md, notes/<id>.md, files/<id>.md
GET    /v1/realms                                your realms
GET    /v1/usage                                 usage and limits for the key's organization
GET    /v1/plans                                 public plan limits
GET    /v1/organization                          your organization (PATCH {"name"} with a session)

Find results: {"results": [{"id", "type": "memory" (a note) | "chunk" (a piece), "text", "score", "document_id", ...}]}
Field names in responses are stable: "namespace" is the realm, "memories" are notes, "documents" are files,
"chunks" are pieces, "static"/"dynamic" are core/changing facts.

Compatibility: earlier paths still work and behave the same: /v1/namespaces/{ns}/document(s), /search,
/profile, /memories/forget, /tree, /file/{path}; and the fields customId, dreaming ("dynamic"), searchMode.

## Errors

Every error is JSON: {"error": "message", "code": "machine_code"}.
- 401 unauthorized: missing or invalid key.
- 402 plan_limit: monthly plan limit reached; body has "plan_limit" and a Retry-After header.
- 429 rate_limited: too many requests this minute; respect Retry-After.
- 400 invalid_request: the body failed validation.

## MCP

Endpoint: https://recallai.nidonic.online/mcp (Streamable HTTP, protocol 2025-06-18), same Bearer key.
Tools: recall_save {content, realm?, metadata?}, recall_find {query, realm?, limit?}, recall_about {realm?},
recall_remove {ids? | query?, realm?, dryRun? = true}, recall_notes {realm?, limit?}.
Local MCP server signed in with the CLI login: npx @recall-ai/cli mcp (or: npx @recall-ai/cli setup claude|cursor|codex|opencode).

## CLI

Install: npm install -g @recall-ai/cli
Sign in: recall login (opens the browser; the machine gets its own key). recall login --key rc_... works without a browser.
Every command except login is refused until you are signed in, or RECALL_API_KEY is set.
The realm is, in order: --realm, the folder's .recall.json (written by recall connect), RECALL_REALM, then project-<current folder>.
Every command takes --json for scripts.

recall login | logout            sign in or out on this machine
recall status                    the key, server, plan and realm in use, and this month's usage
recall connect [realm]           link this folder to a realm; without a realm, show the link
recall realms                    your realms with note and file counts
recall save <text>               save text; or --file <path>, --url <url>, or pipe text in; --wait until findable
recall find <query>              find notes and file pieces (--limit)
recall about                     the realm's core facts and changing facts
recall remove <query>            shows matching notes, asks, then removes them (--yes skips the question)
recall files [id]                list files, or show one with its notes
recall files rm <id>             delete a file
recall sync                      run Sync now
recall setup <agent>             connect claude, cursor, codex or opencode
recall mcp                       Recall's MCP server over stdio, using your login
recall explore [path]            File Explorer: the realm as files, or one file (e.g. RECALL.md)

## Plugins

Source: https://github.com/Ravicodess/Recall-AI/tree/main/plugins. Sign in first: npx @recall-ai/cli login.
The plugins use that login (or RECALL_API_KEY) and do nothing without it. RECALL_BASE_URL=https://recallai.nidonic.online.
Coding-agent plugins share the realm "project-<repo folder>" (non [a-zA-Z0-9_:-] characters become "-"); RECALL_REALM overrides it.
- Claude Code: /plugin marketplace add Ravicodess/Recall-AI, then /plugin install recall@recall-ai. Recalls at session start and per prompt, and keeps learning: it saves the conversation in the background as it grows.
- OpenCode: npx @recall-ai/cli setup opencode, and copy plugins/opencode/index.js to .opencode/plugin/recall.js. Recalls per message, and keeps learning: it saves after each reply as the conversation grows.
- Cursor: npx @recall-ai/cli setup cursor, and plugins/cursor/recall.mdc → .cursor/rules/.
- Codex: npx @recall-ai/cli setup codex, and append plugins/codex/AGENTS.md to AGENTS.md.
- Chrome: load plugins/browser unpacked; saves pages and selections, finds from the toolbar.
Saving skips tool calls and replaces <private>…</private> with [private]; RECALL_SAVE=off turns it off.

## Integration recipe for a coding agent

1. Ask the human for an rc_ key (from https://recallai.nidonic.online/console). Read it from an env var, e.g. RECALL_API_KEY. Never commit it.
2. Pick a realm per end user (e.g. "user_<id>").
3. After useful turns, save the text (POST /file). Do not wait for it; it becomes findable in seconds.
4. Before answering, find with the user's message and put the top results in the prompt.
5. Handle 402 and 429 by backing off; they are not bugs.

## Facts

- Find never calls a language model; it is Postgres full-text plus vector search.
- Sync uses a language model in the background to decide which notes supersede which.
- Data is stored in Postgres (Supabase). Hosted only; no self-hosted edition.

Copyright © 2026 Nidonic Labs. All rights reserved.