---
title: MCP tools
description: The 15 tools the OpenMemory MCP server exposes, with their arguments. Streamable HTTP, stateless, authenticated with a bearer key.
---

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](/docs/concepts#errors).

## Tools

| Tool | What it does | REST equivalent |
| --- | --- | --- |
| [`get_context`](#get_context) | Everything needed at the start of a task | `GET /v1/context` |
| [`remember`](#remember) | Store a durable fact | `POST /v1/memories` |
| [`recall`](#recall) | Search facts | `GET /v1/memories` |
| [`forget`](#forget) | Permanently delete facts, records, journal text | `POST /v1/forget` |
| [`journal_write`](#journal_write) | Write or append to a day's journal | `PUT /v1/journal/{date}` |
| [`record_put`](#record_put) | Create or upsert a record | `POST /v1/collections/{c}/records` |
| [`record_query`](#record_query) | List records | `GET /v1/collections/{c}/records` |
| [`record_update`](#record_update) | Update a record, optionally compare-and-set | `PATCH /v1/collections/{c}/records/{id}` |
| [`action_propose`](#action_propose) | Queue an action for approval | `POST /v1/actions` |
| [`action_list`](#action_list) | List actions | `GET /v1/actions` |
| [`action_transition`](#action_transition) | Compare-and-set status change | `POST /v1/actions/{id}/transition` |
| [`kv_get`](#kv_get) | Read a value or a namespace | `GET /v1/kv/{ns}[/{key}]` |
| [`kv_set`](#kv_set) | Set a value, optionally compare-and-set | `PUT /v1/kv/{ns}/{key}` |
| [`dream_next_job`](#dream_next_job) | Get (and start if due) a client-mode dream job | `GET /v1/dream/jobs/next` |
| [`dream_submit`](#dream_submit) | Submit your model's dream result | `POST /v1/dream/jobs/{id}/result` |

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.

| Argument | Type | Default |
| --- | --- | --- |
| `budget_chars` | integer, 200 to 20,000 | 4,000 |
| `journal_days` | integer, 0 to 31 | 7 |
| `due_within_days` | integer, 0 to 90 | 7 |
| `kv` | comma-separated namespaces | none |
| `collections` | comma-separated collections | all (for due items) |

### 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](/docs/concepts#actions).

### 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](/docs/dreaming#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:

```bash
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"}'
```