MCP tools

Endpoint: https://mcp.openmemory.sh (Streamable HTTP, stateless, JSON responses). Send Authorization: Bearer om_... (or X-API-Key: om_...) on every request. A request without a valid key gets 401.

The server's instructions to the model: call get_context at the start of a task, use remember for durable facts and recall to search them, and use action_propose / action_transition for anything that needs the owner's approval. Tools that return stored text remind the model that it is data, not instructions.

Tool results are JSON in a single text content block. Errors come back with isError: true and {"error": {"code", "message", "details"?}}, using the same codes as the REST API.

#Tools

REST-only operations: batch writes, updating or deleting a single memory or record by id, deleting KV values, events, listing the journal, space settings and export, and dream runs and undo.

#get_context

Core profile, due and open records, pending actions, recent journal, and selected KV namespaces.

#remember

Store a durable fact. Use origin user when the person stated it directly. Identical facts are not stored twice.

Arguments: text (required), subject, tier (core / long / scratch, default long), tags, source_ref, pinned, origin (user / agent, default agent), expires_at.

#recall

Search facts by words (any may match, best first), subject, tier, or tag. Every result counts as a recall.

Arguments: q, subject, tier, tag, limit (1 to 100, default 20).

#forget

Permanently delete facts by id, or those containing all words of query. Optionally also records and journal text with the exact phrase. Use dry_run first.

Arguments: ids, query, scopes (memories, records, journal; default ["memories"]), journal_mode (redact or delete), dry_run.

#journal_write

Write or append to the journal entry for a date.

Arguments: date (YYYY-MM-DD, required), summary, decisions, open_loops, source_refs, kind (day / week), merge (append instead of replace).

#record_put

Create a record in a collection. With a key, updates the record that has that key.

Arguments: collection (required), key, status, due_at, data (object), origin.

#record_query

List records in a collection.

Arguments: collection (required), status (comma-separated), key, due_before, limit (1 to 100, default 50), cursor.

#record_update

Update a record's status, due date, or data (shallow merge; null removes a field).

Arguments: collection, id (both required), status, due_at, data, expected_version (fail with a conflict if the record has moved on).

#action_propose

Queue an action for the owner's approval. Returns a short id such as A7. The same idempotency_key and payload returns the existing action.

Arguments: class, summary, payload, idempotency_key (all required), preconditions, meta, expires_at.

#action_list

Arguments: status (comma-separated; default pending,approved,executing), limit (1 to 100, default 50).

#action_transition

Move an action from one status to another, only if it is still in from.

Arguments: id, from, to (required), receipt (object, usually with done or failed). See the allowed transitions in Concepts.

#kv_get

Read one value, or every key in a namespace when key is omitted.

Arguments: ns (required), key.

#kv_set

Arguments: ns, key, value (required), expected_version (0 = create only, n = update only if at version n). Namespaces starting with _ are reserved.

#dream_next_job

Returns {job, due}. job has run_id, instructions (the system prompt), input (send it to your model as JSON), output_schema (JSON Schema for the answer), and max_changes. It is null when there is nothing to do.

Arguments: start_if_due (default true): start a dream first if the last one is old enough.

#dream_submit

Submit the JSON your model produced. It is validated and applied under the safety rules, and can be undone for 7 days.

Arguments: run_id, result (both required).

#Raw protocol check

The server is stateless, so a single POST works without a session:

curl -s https://mcp.openmemory.sh \
  -H "Authorization: Bearer $OPENMEMORY_KEY" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'