Memory is always on. Search uses full-text matching, plus vector matching when an embedding provider is available; without one,
vector and hybrid searches fall back to full text. GET /api/memory/provider shows which provider is in use and why.GET routes check their query string as strictly as the POST routes check their bodies, so an out-of-range limit or an empty query is a 400. Every route is on the general rate tier except POST /api/memory/embedding/reindex and POST /api/memory/embedding/install, which are on the sensitive tier (see rate limits).
Routes
Saving runs a fact’s
title and content, and a procedure’s content, through a secret scrubber before anything is embedded or stored. Text that looks like a credential (API keys, tokens, NAME_KEY=value pairs, PEM blocks) is replaced with [REDACTED], and so is any key of 12 characters or more saved in Clawboo’s vault, whatever its shape. A secret Clawboo never saved is caught only when it matches a known pattern: keep secrets out of memory.GET /api/memory
Searches stored facts. The query string is checked with the same rules as the agents’ memory_search tool. Each result is a fact with a score from 0 to 1 and a matchedVia field saying how it matched.
- Query params
- Request body: none.
Scope is inclusive. A query scoped by
teamId or agentId also sees global facts (those saved with no scope), so global memory is visible to every scoped search.Responses
200 OK: the (possibly empty) result list:
matchedVia reflects the mode that actually ran, not the mode requested: a vector/hybrid request with no embedding provider runs as fts and reports matchedVia: 'fts'. In hybrid mode the score blends the cosine similarity (60%) and an FTS-hit signal (40%).
400 Bad Request: the query failed validation (for example a blank query, a limit outside 1 to 100, or an unknown mode):
500 Internal Server Error: any failure running the search:
Example
POST /api/memory
Saves a memory entry: a fact (the default, when kind is left out or is "fact") or a procedure (kind: "procedure"). A fact is a lasting statement (“The client prefers short answers”); a procedure is named how-to text that keeps every version. Saving a procedure under a name and scope that already exist adds a new version (the highest version plus 1) instead of overwriting.
Entries saved here record createdByRuntime: 'user' and no agent, so you can tell them apart from what agents save.
- Path/query params: none.
- Request body: one of:
Responses
200 OK: a fact was saved. It is embedded when a provider is available; a failed embedding never blocks the save:
200 OK: a procedure was saved (kind: 'procedure'):
400 Bad Request: the body failed validation (for example a title or content that is too long, too many tags, or a procedure with no name):
500 Internal Server Error: any failure writing the entry:
Example
GET /api/memory/browse
Lists the most recent facts (newest updatedAt first) and procedures (newest first, one row per version). Facts are scoped the same inclusive way as search. Procedures are filtered by teamId only: agentId does not narrow them.
- Query params
- Request body: none.
Responses
200 OK: facts and procedures side by side:
400 Bad Request: limit out of the 1..200 range:
500 Internal Server Error: any failure reading the store:
Example
GET /api/memory/graph
The store as a graph: facts and procedures are nodes, joined by similarity, shared-tag and version edges and grouped into communities. Every edge comes from something stored.
- Query params:
limit(1 to 500 facts, newest first),teamId,agentId(scope, as for search).
200 OK:
400 Bad Request: { "error": "invalid query", "details": { ... } }.
POST /api/memory/feedback
Records how a fact worked out. Outcomes feed the learning entry returned with each fact by search and browse. factId can be the full id, or a prefix of at least 8 characters that matches exactly one fact.
- Body:
{ factId: string; outcome: 'useful' | 'dead_end' | 'corrected'; note?: string; scope?: { teamId?, agentId? } }.correctedrequires anote.
200 OK: { ok: true, outcome: MemoryOutcome, learning: LearningEntry }, the recorded outcome and the fact’s updated learning entry.
400 Bad Request: { "error": "invalid body", "details": { ... } }, or { "error": "corrected requires a note" }.
404 Not Found: { "error": "unknown fact" }.
GET /api/memory/outcomes
Every outcome recorded for one fact, newest first. factId can be a prefix, as for feedback.
- Query params:
factId(required),limit(1 to 200).
200 OK: { ok: true, factId: string, outcomes: MemoryOutcome[] }, where each outcome is { id, factId, outcome, note, agentId, teamId, taskId, runtime, createdAt }.
400 Bad Request: { "error": "invalid query", "details": { ... } }.
404 Not Found: { "error": "unknown fact" }.
GET /api/memory/provider
Reports the embedding provider behind vector and hybrid search and the graph’s similarity links, and why it is the one in use. Providers are tried in this order:
- Ollama at
http://localhost:11434with thenomic-embed-textmodel installed. This address is fixed:OLLAMA_BASE_URL, which Clawboo Native honors, is not used for embeddings. - OpenAI, with
OPENAI_API_KEYfrom the server’s environment or a key saved under Providers. OpenClaw’s~/.openclaw/.envis not read. - None: search uses full text only.
- Ollama without the model cannot embed. With no OpenAI key this is reported as
ollama-model-missing. With a key, OpenAI serves, andmissingModelnames the model whose install would move embeddings onto this machine. - Local first. Once any fact holds an Ollama vector, an OpenAI key is not used on its own, and an Ollama that stops answering is reported as
ollama-unreachableinstead of being replaced quietly.
POST /api/memory/embedding/reindex with allowRemote: true. That choice lasts until one of these happens:
- any Clawboo process (the server, or the stdio Memory server) finds Ollama serving again;
- the OpenAI key is disconnected under Providers or Runtimes;
- a check finds no OpenAI key at all (a key store that failed to read does not count).
reembedAll is dropped along with it.
CLAWBOO_DISABLE_EMBEDDINGS=1 turns embeddings off: provider is null and status.state is disabled.
The server re-checks the provider on its own, whether or not anything reads this route:
A disconnected key stops being used at once, including by Memory MCP sessions already open, which ask for the current provider on every call. Reading this route while facts wait to be indexed also starts indexing them, unless the last attempt failed within the past minute.
- Path/query params: none.
- Request body: none.
Responses
200 OK: provider keeps its original shape (and is null whenever status.state is not ready); status explains it:
pending counts only facts that have no vector at all: an automatic pass never re-uploads facts another provider already indexed. The exception is a switch the user asked for (reembedAll) that has not finished: until it has, pending also counts the facts still carrying another provider’s vectors, and automatic retries carry on with them.
500 Internal Server Error: an unexpected failure:
Example
POST /api/memory/embedding/reindex
Re-checks the provider straight away and starts indexing every fact that has no vector, including facts the provider turned down before. In the background it sends the provider one short fixed string (never fact text), so a provider that has recovered stops reporting its last failure. Indexing runs in the background, newest facts first, and never changes a fact’s updatedAt.
Rate tier: sensitive (60 requests a minute, shared with the other sensitive routes).
- Request body (optional):
{ allowRemote?: boolean; reembedAll?: boolean }.allowRemote: truerecords the choice to use an OpenAI key although the store was indexed locally (seeGET /api/memory/providerfor when the choice ends).reembedAll: truealso replaces vectors another provider made, which an automatic pass never does for a remote provider. The request stays pending for the provider it found until every fact is re-indexed: it survives a pass that fails partway and a server restart, and is dropped once another provider takes over.
Responses
202 Accepted: indexing started, or there was nothing to do. Poll GET /api/memory/provider for progress:
500 Internal Server Error: the re-check or the status read failed:
Example
POST /api/memory/embedding/install
Asks the local Ollama to download the embedding model (through Ollama’s own /api/pull) and streams the progress as Server-Sent Events. The model is always nomic-embed-text; any request body is ignored. On success the provider is re-checked, which starts indexing the store. Closing the connection cancels the download; Ollama keeps what it already fetched.
Rate tier: sensitive (60 requests a minute, shared with the other sensitive routes), because it downloads over the network.
- Request body: none.
Responses
409 Conflict (JSON, not a stream): there is nothing to install, because status.missingModel is null (Ollama is not running, or already has the model). state is the current status.state, or unknown when the status check itself failed:
200 OK (text/event-stream): one data: frame per event:
message is a plain phrase (Preparing the download, Downloading, Verifying, Finishing). Byte counts follow the largest layer only, so the percentage does not restart for each small file after the model. A stream that ends without Ollama reporting success is an error, never a complete. IN_PROGRESS means another install is already running.
Example
Error envelope
Most error bodies are{ "error": "<message>" }. The validating routes (search, save, browse, graph, feedback, outcomes) add details, the zod flatten() output, on a 400: { "error": "invalid query", "details": { ... } }. The install route’s 409 carries detail and state instead, since nothing in the request was wrong.
Related
- Memory: what facts and procedures are, scopes, and how agents use them.
- Memory panel: search, save and browse from the dashboard.
- MCP tools: the Memory tools agents call against the same store.
- Tools and MCP API: attach the Memory MCP server to an agent.
- @clawboo/db:
SqliteMemoryStoreand the memory schemas.