Write a memory
const url = 'https://api.metaphoric.io/v1/spaces/personal/memories';const options = { method: 'POST', headers: { 'metaphor-user': 'customer-4821', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"content":"example","source":{"name":"api","id":"ticket-1042","url":null},"occurred_at":null,"audience":null,"agent":null}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”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.
Example
personalpersonal 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.
Header Parameters
Section titled “Header Parameters”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.
Example
customer-4821The 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.
Request Bodyrequired
Section titled “Request Bodyrequired”object
What to remember: up to 32,000 characters, not all of them white space. It is never written to a log.
object
The source: api, slack, gmail, claude-code or another name of yours.
Example
apiThe 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.
Example
ticket-1042A 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.
When it happened, which may be long before it is sent. Null means now. Not kept yet: a value other than null is refused.
Example
2027-01-31T09:30:00ZWho 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.
Example
[ "user:customer-4821"]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.
Example
claude-codeResponses
Section titled “Responses”The memory is kept. The same source and content sent again changes nothing, and a memory forgotten since stays forgotten.
object
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.
accepted today.
Example
{ "id": "4f1c9a7e2b8d06c3a5e9f17b20d4c8e6"}The request is not valid, or names no user to act for.
object
object
One of ErrorCode, or a code added since. Treat a code you do not know by its status.
Example generated
{ "error": { "code": "example", "message": "example" }}No valid API key was sent.
object
object
One of ErrorCode, or a code added since. Treat a code you do not know by its status.
Example generated
{ "error": { "code": "example", "message": "example" }}The API key does not allow this, or not for this user.
object
object
One of ErrorCode, or a code added since. Treat a code you do not know by its status.
Example generated
{ "error": { "code": "example", "message": "example" }}No such shared space.
object
object
One of ErrorCode, or a code added since. Treat a code you do not know by its status.
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.
object
object
One of ErrorCode, or a code added since. Treat a code you do not know by its status.
Example generated
{ "error": { "code": "example", "message": "example" }}The request body is longer than 524,288 bytes.
object
object
One of ErrorCode, or a code added since. Treat a code you do not know by its status.
Example generated
{ "error": { "code": "example", "message": "example" }}The body was not sent as application/json.
object
object
One of ErrorCode, or a code added since. Treat a code you do not know by its status.
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.
object
object
One of ErrorCode, or a code added since. Treat a code you do not know by its status.
Example generated
{ "error": { "code": "example", "message": "example" }}Something went wrong. Try again.
object
object
One of ErrorCode, or a code added since. Treat a code you do not know by its status.
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.
object
object
One of ErrorCode, or a code added since. Treat a code you do not know by its status.
Example generated
{ "error": { "code": "example", "message": "example" }}