Guides / Switch to Recall

Switch from Honcho

Recall implements Honcho's v3 REST API. Code written for Honcho keeps working after you change two settings: the base URL and the API key. This guide lists what changes, what stays the same, what Recall adds, the differences that matter, and a checklist.

What changes

In Honcho's own clients, that is the constructor:

# Python: honcho-ai
honcho = Honcho(base_url="https://api.recallmem.dev", api_key="pk_live_...", workspace_id="my-app")

// TypeScript: @honcho-ai/sdk
const honcho = new Honcho({ baseURL: "https://api.recallmem.dev", apiKey: "pk_live_...", workspaceId: "my-app" });

Both clients also read their settings from the environment, so an app that configures them that way needs no code change at all:

HONCHO_URL=https://api.recallmem.dev
HONCHO_API_KEY=pk_live_...
HONCHO_WORKSPACE_ID=my-app

What stays the same

The REST paths, request and response bodies, status codes, error bodies ({"detail": …}), pagination and filters; workspaces, peers, sessions, messages, conclusions, peer cards, representations, session context, summaries, scopes and dreams; the reasoning levels minimal to max, with low as the default; streaming, structured output and evidence on chat; webhooks signed with X-Honcho-Signature; and the 40 MCP tools with their names (at /mcp?profile=full).

We checked this with Honcho's published clients, version 2.5.1 of both, against a Recall server with authentication on and a pk_live_ key, as on the hosted service. With only the base URL and key changed, a whole app ran: creating peers and sessions, adding messages and files, context in OpenAI and Anthropic form, chat (plain, streamed, with a level, with evidence, about another peer, structured, workspace-wide), search at every level, peer cards, representations, conclusions, metadata, clones, scopes, dreams, queue status, and the clients' own error classes for a wrong key, a missing message and a workspace that still has sessions. The TypeScript run is a test in the repository (packages/server/test/honcho-client.test.ts) and runs on every change.

You can also move to Recall's own SDKs, npm install @recall-memory/sdk or pip install recall-mem. They have the same objects and calls, plus Recall's additions, retries and idempotent writes. Change the import and the constructor (new Recall({ workspaceId }), Recall(workspace_id=...)); they take their settings from options or from RECALL_URL, RECALL_API_KEY and RECALL_WORKSPACE_ID, never from another product's variables. The usual calls:

import { Recall } from "@recall-memory/sdk";

const recall = new Recall({ workspaceId: "my-app" });

// The same objects and calls as before: peers, sessions, messages, context and chat.
const alice = recall.peer("alice");
const assistant = recall.peer("assistant");
const session = recall.session("support-42");
await session.addPeers([alice, assistant]);
await session.addMessages([
  alice.message("We moved from Amsterdam to Utrecht last week."),
  assistant.message("Congratulations on the move!"),
]);
const context = await session.context({ tokens: 2000, peerTarget: alice });
const messages = context.toOpenAI(assistant);
await recall.waitForIdle(); // for this demo only: real apps do not wait for learning
const city = await alice.chat("Where does alice live now?", { reasoningLevel: "low" });
const hits = await alice.search("Utrecht");

from recall_memory import Recall

recall = Recall(workspace_id="my-app")

# The same objects and calls as before: peers, sessions, messages, context and chat.
alice = recall.peer("alice")
assistant = recall.peer("assistant")
session = recall.session("support-42")
session.add_peers([alice, assistant])
session.add_messages(
    [
        alice.message("We moved from Amsterdam to Utrecht last week."),
        assistant.message("Congratulations on the move!"),
    ]
)
context = session.context(tokens=2000, peer_target=alice)
messages = context.to_openai(assistant=assistant)
recall.wait_for_idle()  # for this demo only: real apps do not wait for learning
city = alice.chat("Where does alice live now?", reasoning_level="low")
hits = alice.search("Utrecht")

What Recall adds

• Answers you can check. With evidence on, chat also returns citations, a confidence and abstained, which is true when memory did not hold the answer and Recall said so instead of guessing.
• Facts with a history. When something stops being true, the old fact is closed when the new message is learned, not later. Conclusions carry valid_from, valid_to, superseded_by and the ids of the messages they came from, and you can filter on current.
• Safe retries. An Idempotency-Key header on messages, turns and chat: a retried request is not stored or charged twice.
• One request per turn. POST …/sessions/{id}/turn stores the new messages and returns the context for the reply.
• Forgetting a person. DELETE …/peers/{peer} removes their messages, the facts about them and their peer cards (details).
• Reads that never create. GET for one workspace, peer or session answers 404 for a typo instead of creating it.
• Operations. Usage by task and model at GET /v3/usage; webhook deliveries retried with backoff, each with a stable X-Recall-Event-Id; wait_ms on queue status to wait until learning is done.
• Where it runs. The hosted service stores data in Frankfurt (EU). The server is source-available and you can run it yourself; the SDKs and integrations are MIT.
• Integrations. Plugins for Claude Code, Codex and OpenClaw, a memory provider for Hermes, and an MCP server that Claude, ChatGPT and Cursor connect to by signing in (integrations).

// What Recall adds. An answer with its sources, a confidence and an honest "I don't know".
const answer = await alice.chat("Where does alice live now?", { includeEvidence: true });
const reply = answer.abstained ? "I'm not sure yet." : answer.content;
const sources = answer.citations;
// One request that stores a message and returns the context for the reply.
const { context: next } = await session.turn([alice.message("Any good cafés near me?")], {
  peerTarget: alice,
  tokens: 2000,
});
// Forget a person: her messages, the facts about her and her peer cards.
const erased = await alice.delete();

# What Recall adds. An answer with its sources, a confidence and an honest "I don't know".
answer = alice.chat("Where does alice live now?", include_evidence=True)
reply = "I'm not sure yet." if answer.abstained else answer.content
sources = answer.citations
# One request that stores a message and returns the context for the reply.
result = session.turn(
    [alice.message("Any good cafés near me?")], peer_target=alice, tokens=2000
)
# Forget a person: her messages, the facts about her and her peer cards.
erased = alice.delete()

Differences that matter

• Chat does not create. On Recall, chat about a workspace or peer that does not exist answers 404, where Honcho creates them; reading the card of an unknown peer is a 404 too. Honcho's clients create a peer when you call peer(), so this only shows in raw REST calls: create the peer first with POST …/peers, or turn on autoCreate (auto_create in Python) in Recall's SDKs.
• Your data does not move by itself. Recall does not import from Honcho. Send the conversations you want remembered through POST …/sessions/{id}/messages, with created_at to keep their original dates, and Recall learns from them; learning is billed per message token (pricing). Facts you want kept word for word go in through POST …/conclusions, and peer cards through PUT …/peers/{peer}/card.
• Different models, different answers. The level names are the same, but each level is Recall's own plan, answered by Recall's models (see levels and models). Answers will not match Honcho's word for word. Run your most common questions in the dashboard's Playground before you switch traffic.
• Peer cards have limits. Up to 500 entries of up to 4,000 characters. Setting a card about a peer that does not exist yet creates that peer.
• Webhooks can arrive twice. Recall retries a failed delivery, so drop repeats by X-Recall-Event-Id. On the hosted service, verify signatures with your account's webhook_secret from GET /v3/account.
• Self-hosting is set up differently. A server of your own is configured with RECALL_* environment variables, not Honcho's configuration file. It runs as one process with Postgres and pgvector (or an embedded database) and no Redis. Size limits are Honcho's defaults and cannot be changed. Clients authenticate with tokens from recall token (self-hosting).

For prices and published benchmark results side by side, see Recall and Honcho compared.

Checklist

1. Sign in and create a key under API keys: Whole account, or limited to the workspace your app uses.
2. Set the base URL and key in your client, or HONCHO_URL and HONCHO_API_KEY in its environment. Keep your workspace ids.
3. Send the conversations you want remembered, with their original created_at. Add hand-written facts and peer cards if you kept them.
4. If you call the REST API directly, create peers before you read or chat about them.
5. Point webhooks at your endpoint again, verify them with your webhook_secret, and drop repeated X-Recall-Event-Ids.
6. For MCP clients, use https://api.recallmem.dev/mcp; add ?profile=full for Honcho's 40 tools.
7. Ask your most common questions in the Playground, choose a level per question, and check the cost under Usage.

Next: Reasoning levels and models · Cost and speed