create_memory

POST

/v1/memories

const url = 'https://app.everruns.com/api/v1/memories';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"description":"Living design documents synced from GitHub","name":"design-docs","source":{"branch":"main","repository":"acme/design-docs","root_folder":"docs/","type":"github"}}'
};

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://app.everruns.com/api/v1/memories \
  --header 'Content-Type: application/json' \
  --data '{ "description": "Living design documents synced from GitHub", "name": "design-docs", "source": { "branch": "main", "repository": "acme/design-docs", "root_folder": "docs/", "type": "github" } }'

Create a new workspace memory.

Request Body^required

application/json

Request body for the create_memory operation.

object

description

Human-readable description. Safe to render in user-facing messages.

string | null

Example

Living design documents synced from GitHub

name

required

Human-readable name. Safe to render in user-facing messages.

string

Example

design-docs

source

One of:

null
object

null

One of:

object
object

Source configuration. Example shape is defined on CreateMemorySourceRequest.

object

branch

Branch to sync. Defaults to the repository’s default branch when omitted.

string | null

Example

main

repository

required

GitHub repository in owner/repo form.

string

Example

acme/design-docs

root_folder

Sub-directory within the repository to sync. Empty / omitted = whole tree.

string | null

Example

docs/

sync_interval_secs

Automatic resync interval in seconds. Omit or set 0 for manual-only; scheduled sync accepts 300 through 604800.

integer | null format: int32

<= 604800

Example

type

required

string

Allowed values: github

Example

{
  "branch": "main",
  "repository": "acme/design-docs",
  "root_folder": "docs/",
  "type": "github"
}

Source configuration. Example shape is defined on CreateMemorySourceRequest.

object

branch

Branch to sync. Defaults to the repository’s default branch when omitted.

string | null

Example

main

root_folder

Sub-directory within the repository to sync. Empty / omitted = whole tree.

string | null

Example

docs/

sync_interval_secs

Automatic resync interval in seconds. Omit or set 0 for manual-only; scheduled sync accepts 300 through 604800.

integer | null format: int32

<= 604800

Example

url

required

Clonable git URL (SSH or HTTPS).

string

Example

https://github.com/acme/design-docs.git

type

required

string

Allowed values: git

Example

{
  "branch": "main",
  "repository": "acme/design-docs",
  "root_folder": "docs/",
  "type": "github"
}

Responses

201

Memory created

application/json

Response body for memory.

object

archived_at

Timestamp when this resource was archived, if any (RFC 3339).

string | null format: date-time

created_at

required

Timestamp when this resource was created (RFC 3339).

string format: date-time

deleted_at

Timestamp when this resource was soft-deleted, if any (RFC 3339).

string | null format: date-time

description

Human-readable description. Safe to render in user-facing messages.

string | null

required

Prefixed public identifier. See ID Schema.

string

is_readonly

required

Whether the memory is mounted read-only into sessions. Read-only memories accept no writes from the session sandbox.

boolean

last_sync_error

Most recent sync error message; cleared on the next successful sync.

string | null

last_synced_at

Timestamp of the most recent successful sync (RFC 3339). None if never synced.

string | null format: date-time

name

required

Human-readable name. Safe to render in user-facing messages.

string

source

required

One of:

Source-specific configuration (git remote, github repo, manual upload).

object

provider

required

string

Allowed values: manual

source_type

required

Source kind discriminator (manual, git, github). Determines which source variant is populated.

string

status

required

Current lifecycle status.

string

sync_status

required

Current sync status (idle, syncing, succeeded, failed). Only meaningful when source_type is git or github.

string

updated_at

required

Timestamp when this resource was last updated (RFC 3339).

string format: date-time

Example

{
  "archived_at": "2026-05-26T00:00:00Z",
  "created_at": "2026-04-01T10:00:00Z",
  "deleted_at": "2026-05-26T00:00:00Z",
  "description": "Living design documents synced from GitHub",
  "id": "mem_01933b5a000070008000000000000001",
  "is_readonly": false,
  "last_sync_error": "ssh: connect to host github.com port 22: Connection timed out",
  "last_synced_at": "2026-05-25T08:00:00Z",
  "name": "design-docs",
  "source": {
    "provider": "manual"
  },
  "source_type": "github",
  "status": "active",
  "sync_status": "succeeded",
  "updated_at": "2026-05-25T08:00:00Z"
}

400

Invalid input

application/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json by [problem_json_content_type].

object

allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary documented in specs/api-conventions.md distinguishes them.

object

hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null

method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null

rel

required

Link relation describing the action. Closed vocabulary documented in specs/api-conventions.md — examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string

schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

code

Stable, machine-readable error code (snake_case).

string | null

detail

Human-readable explanation specific to this occurrence.

string | null

instance

Request URI for this occurrence.

string | null

retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

status

required

HTTP status code; mirrors the response status line.

integer format: int32

title

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}

409

Duplicate memory name

application/json

Standard error response.

object

allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary documented in specs/api-conventions.md distinguishes them.

object

hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

href

string | null

method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null

rel

required

string

schema_ref

string | null

code

Stable, machine-readable error code (snake_case).

string | null

detail

Human-readable explanation specific to this occurrence.

string | null

instance

Request URI for this occurrence.

string | null

retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

status

required

HTTP status code; mirrors the response status line.

integer format: int32

title

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}

create_memory

Request Body required

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Responses

201

Example

400

Example

409

Example

Request Body^required