Skip to content

Write a memory

POST
/v1/spaces/{space_id}/memories
curl --request POST \
--url https://api.metaphoric.io/v1/spaces/personal/memories \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'metaphor-user: customer-4821' \
--data '{ "content": "example", "source": { "name": "api", "id": "ticket-1042", "url": null }, "occurred_at": null, "audience": null, "agent": null }'

Needs memories:write. Answers once the memory is kept, before it is ready for recall. The acting user is its author. An audience naming a group that does not exist and one naming a group the user is not in are refused the same. The body may be up to 524,288 bytes.

space_id
required

personal for the acting user’s own space, or a shared space’s ID: 1 to 63 lowercase letters, digits and hyphens, starting with a letter or digit. personal always answers: before the user’s first write it holds nothing.

string
/^[a-z0-9][a-z0-9-]{0,62}$/

Example

personal

personal for the acting user’s own space, or a shared space’s ID: 1 to 63 lowercase letters, digits and hyphens, starting with a letter or digit. personal always answers: before the user’s first write it holds nothing.

metaphor-user

A member’s ID, which Metaphor issued and which starts with metaphor:, or your own ID for an end user: 1 to 256 visible ASCII characters but " and \, not starting with metaphor:. Metaphor keeps an end user’s ID as you send it only on a key held to that user. A service user’s ID is issued by Metaphor, so it starts with metaphor: too.

string
>= 1 characters <= 256 characters /^[!#-[\]-~]+$/

Example

customer-4821

The user this request acts for. Required for a key of your own server; a key held to a user may leave it out, or send that user’s ID. A server key acts for a member only where the owner turned that on for the project, and each such request is recorded.

Media typeapplication/json
object
content
required

What to remember: up to 32,000 characters, not all of them white space. It is never written to a log.

string
>= 1 characters <= 32000 characters /\S/
source
required
object
name
required

The source: api, slack, gmail, claude-code or another name of yours.

string
/^[a-z0-9][a-z0-9-]{0,31}$/

Example

api
id
required

The item’s ID at the source. Writing the same source ID again with the same content changes nothing. Content is compared as it is kept, with credentials such as API keys hidden, so text that differs only in one counts as the same. With other content, it is refused with conflict until replacing an item is served. Once its memory is forgotten, the same content sent again changes nothing while the forget can be undone, and is then refused with conflict. Each author’s source IDs are their own. The ID is kept after its memory is forgotten, and in history after an erase, so it must not hold content or personal data: use the source’s own ID, not a title, a sentence or a person’s name.

string
>= 1 characters <= 256 characters /^[!#-[\]-~]+$/

Example

ticket-1042
url

A link to the item at the source: http or https only, in visible ASCII, with no user or password. Not kept yet: a value other than null is refused.

string | null format: uri
<= 2048 characters /^https?:\/\/[\x21\x22\x24-\x2e\x30-\x3e\x41-\x5b\x5d-\x7e]+(?:[/?#][\x21-\x7e]*)?$/
occurred_at

When it happened, which may be long before it is sent. Null means now. Not kept yet: a value other than null is refused.

string | null format: date-time

Example

2027-01-31T09:30:00Z
audience

Who may see it. Null takes the space’s default: in a personal space, its user alone. A user may name themselves, groups they are in, and project when they are a member.

Array<string> | null
>= 1 items <= 100 items unique items

Example

[
"user:customer-4821"
]
agent

The agent writing it for the acting user, if one is, such as claude-code. Not kept yet: a value other than null is refused.

string | null
/^[a-z0-9][a-z0-9-]{0,62}$/

Example

claude-code

The memory is kept. The same source and content sent again changes nothing, and a memory forgotten since stays forgotten.

Media typeapplication/json
object
id
required

A memory’s ID, made from its source. The same source gives the same ID in every space, so an ID names a memory only within its space.

string
/^[0-9a-f]{32}$/
status
required

accepted today.

string

Example

{
"id": "4f1c9a7e2b8d06c3a5e9f17b20d4c8e6"
}

The request is not valid, or names no user to act for.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

No valid API key was sent.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The API key does not allow this, or not for this user.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

No such shared space.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

conflict: the source ID is already used, by other content or by a memory forgotten past undoing. Replacing an item is not served yet. user-erased: the acting user was erased after the request was let in. Nothing was kept.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The request body is longer than 524,288 bytes.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The body was not sent as application/json.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The API key sent more than 600 requests in a minute, the user’s keys together more than 2000, or the tenant’s keys together more than 6000. Wait the seconds Retry-After gives.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

Something went wrong. Try again.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The request could not be checked, or the tenant is not set up to take memories yet. Try again later.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}