API Reference

Memora exposes the same service layer through three programmable surfaces: a REST API under /v1, an MCP server for agent clients, and a Go SDK. This page lists the endpoints, tools, and methods of each, plus the error codes common to all of them.

Request Conventions

Request and response bodies are JSON. Errors use one envelope shape across every endpoint:

{
  "error_code": "cas_conflict",
  "message": "expected watermark wmk_… but head is wmk_…",
  "details": {}
}

Unknown fields in a request body are rejected rather than ignored, so a misspelled key surfaces as 400 invalid_input instead of being silently dropped.

Headers

The agent header is required on non-GET requests whose path contains /memories, /edges, or /graph/. Workspace, collection, agent, recall, and pin requests do not require it. A write without the header returns 400 missing_agent_id; one whose identity provider rejects the agent returns 401 agent_verification_failed.

Every request is capped at 8 MiB and runs under the server's configured timeout, 30 seconds by default. Cross-origin requests are answered only for origins on the configured allow-list.

REST Endpoints

All paths are relative to /v1.

Workspaces and Collections

Memories

Graph

Note the slash in /edges/:batch. Batch edge creation is addressed as its own path segment — /edges/:batch. Written without the slash, as /edges:batch, the request returns 404 not_found.

Recall, Agents, and Audit

Ledger queries accept since, until, actor, agent_id, memory_id, edge_id, op (comma-separated), limit, and since_ledger_id for cursor paging.

Operational Endpoints

These sit outside /v1.

These are ordinary non-/ui paths, so they require the bearer token when an API key is configured. A probe that omits it receives 401.

The MCP Server

memora-core mcp speaks JSON-RPC 2.0 over stdio. Setting mcp_enable on a running server additionally mounts a WebSocket endpoint at /mcp. The server advertises protocol version 2024-11-05 and implements tools/list and tools/call. Twenty-five tools are exposed.

The stdio transport is unauthenticated unless you give it a key. With no key configured it treats its caller as trusted — it only talks to the process that started it — and logs a warning saying so. Passing --api-key, or setting MEMORA_API_KEY, makes the initialize handshake require that key and rejects every other method until the handshake succeeds.

There is no MCP tool for graph statistics or for querying the ledger; both are REST-only. Everything else in the tool list maps onto the REST verb of the same name.

The Go SDK

pkg/client is the Go client the CLI is built on, and it can be imported directly. Transport is REST.

import (
    "context"

    "github.com/axiom-studio/memora/pkg/client"
    "github.com/axiom-studio/memora/pkg/types/api"
)

c := client.New("http://localhost:7777", apiKey)
c.AgentID = "agent_my_service"

res, err := c.Imprint(ctx, workspaceID, api.ImprintRequest{
    Content: "Customer wants the enterprise plan.",
})

New returns a client with a 30-second timeout. Endpoint, APIKey, AgentID, Workspace, and HTTPClient are all exported, so the HTTP client can be replaced for connection pooling, tracing, or tests. Every method takes the workspace as an explicit argument; the Workspace field is a convenience holder for callers that want one place to keep it, not an implicit default.

Handling Errors

Non-2xx responses come back as a *client.APIError carrying the status, the decoded envelope, and the raw body. Two helpers cover the cases worth branching on:

res, err := c.Patch(ctx, workspaceID, memoryID, watermark, req)
if client.IsCASErr(err) {
    // Someone else wrote first. Re-read and decide.
}

var apiErr *client.APIError
if errors.As(err, &apiErr) && apiErr.IsNotFound() {
    // The Memory is gone.
}

The SDK sets Authorization, Memora-Agent-Id, and If-Match from the client's fields and method arguments. It does not set Memora-Identity-Provider, so SDK writes are always verified by the default opaque provider.

Error Codes

Every error response carries an error_code. Client faults are distinguished from server faults, so a 5xx always indicates a Memora problem rather than a bad request.

capability_unavailable is the one to expect during deployment rather than at runtime: it means the request is well-formed but the storage seam behind it was never configured. See Adapters for which operations depend on which seam.