Agent: Memory

Agent Memory

Persistent agent memory — read, write, search, and control the project memory store. These endpoints forward to the daemon’s memory.* RPCs, with active-realm-scoped reads and writes, daemon-paginated listings, and a daemon-side human-only gate on consolidation.

The HTTP edge has no service-level auth; hoody-proxy is the boundary (kit network-position trust). The daemon’s memAdminGate over the Unix socket may still return admin_unauthorized when a socket admin capability is configured.

Read project memory graph

`GET /api/v1/agent/memory/graph`

Read a project’s memory relation graph. Returns a paginated page of memory.graph — nodes, edges, and stats. Filter via ?project=&node_type= and page via ?limit=&offset=. The daemon’s memAdminGate may still return admin_unauthorized when a socket admin capability is configured. Active-realm-scoped (a realm header is rejected). Returns 503 store_unavailable when the memory store is not warm.

Parameters

Name	In	Type	Required	Description
`project`	query	string	No	Project key whose graph to read.
`node_type`	query	string	No	Optional node-type filter.
`limit`	query	integer	No	Maximum nodes/edges to return.
`offset`	query	integer	No	Pagination offset into the graph.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1): the `.hoody` project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1) selecting which on-disk `.hoody` install a stateless read/write resolves.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1): `global` or a 24-hex id (also accepted as `?realm=`). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector (§6.1) — the `in:query` alias of `X-Hoody-Realm` (read only when the header is absent).

Response

{
  "nodes": [
    {
      "id": "fact_01HMZ3K9X8R7P2V4N6YTBJWQ5C",
      "type": "fact",
      "label": "Payment provider is Stripe"
    },
    {
      "id": "workflow_01HMZ3KB7T3F2N4P6X8YZWQJVR",
      "type": "workflow",
      "label": "Deploy to staging"
    }
  ],
  "edges": [
    {
      "from": "fact_01HMZ3K9X8R7P2V4N6YTBJWQ5C",
      "to": "workflow_01HMZ3KB7T3F2N4P6X8YZWQJVR",
      "relation": "supports"
    }
  ],
  "stats": {
    "node_count": 142,
    "edge_count": 318
  },
  "limit": 200,
  "offset": 0,
  "truncated": false
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "admin_unauthorized",
  "message": "memory administration requires a valid admin token"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	The daemon’s Unix-socket `memAdminGate` / `systemAdminGate` refused the request. The daemon retains its own socket-side admin gate; when an admin capability is configured without a matching forwarded `admin_token`, the daemon refuses.	Run the daemon with socket auth (`--auth-token-path`) and no separate admin capability; or, for the interactive TUI Memory tab over the socket, present the daemon’s configured Memory-admin token.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`; its source IP is private/local. Authorization is owned by `hoody-proxy`, which is the only party that can reach the gateway.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "store_unavailable",
  "message": "memory store unavailable"
}

Error Code	Title	Description	Resolution
`store_unavailable`	Memory store unavailable	The memory store could not be opened (degraded remote host, not-warm realm store, divergent/corrupt local DB). The request fails closed rather than silently falling back.	Retry once the store is warm; if persistent, inspect the daemon logs for the degrade reason.

SDK usage

const graph = await client.agent.memory.getMemoryGraph({
  project: "hoody-platform",
  node_type: "fact",
  limit: 200,
  offset: 0
});

List memory items

`GET /api/v1/agent/memory/items`

Lists memory records for a project (memory.list). Filter via ?project=&kind=&type=&query=. The listing is daemon-paginated: the daemon caps the page size at 200 and never returns an unbounded set. An omitted ?limit (or one over 200) pages at 200, not “no pagination” — the response always carries meta.page and meta.limit reflecting the effective page size. Active-realm-scoped: a realm header is rejected.

Parameters

Name	In	Type	Required	Description
`project`	query	string	No	Project key to scope the listing to.
`kind`	query	string	No	Memory kind/store to filter by.
`type`	query	string	No	Memory type to filter by (e.g. `workflow`, `fact`).
`query`	query	string	No	Free-text filter over the records.
`page`	query	integer	No	1-based page number.
`limit`	query	integer	No	Items per page (1..200). 0 or omitted pages at the 200 ceiling; a value over 200 is clamped to 200. The effective page size is echoed in `meta.limit`.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector (§6.1) — `in:query` alias of `X-Hoody-Realm`.

Response

{
  "items": [
    {
      "id": "mem_01HMZ3K9X8R7P2V4N6YTBJWQ5C",
      "project": "hoody-platform",
      "kind": "fact",
      "type": "fact",
      "content": "Payment provider is Stripe.",
      "created_at": "2026-01-15T12:34:56Z"
    },
    {
      "id": "mem_01HMZ3KB7T3F2N4P6X8YZWQJVR",
      "project": "hoody-platform",
      "kind": "workflow",
      "type": "workflow",
      "content": "Deploy to staging: 1) run migration 2) restart app 3) verify health",
      "created_at": "2026-01-15T13:01:22Z"
    }
  ],
  "meta": {
    "total": 47,
    "page": 1,
    "limit": 200
  }
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "admin_unauthorized",
  "message": "memory administration requires a valid admin token"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	The daemon’s `memAdminGate` refused the request.	Run the daemon with socket auth and no separate admin capability; or present the Memory-admin token for the interactive TUI.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`.	Reach the agent through `hoody-proxy`.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor `Retry-After` and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "store_unavailable",
  "message": "memory store unavailable"
}

Error Code	Title	Description	Resolution
`store_unavailable`	Memory store unavailable	The memory store could not be opened.	Retry once the store is warm; if persistent, inspect the daemon logs.

SDK usage

for await (const page of client.agent.memory.listMemoryItemsIterator({
  project: "hoody-platform",
  kind: "fact",
  type: "fact",
  query: "stripe",
  limit: 200
})) {
  for (const item of page.items) {
    console.log(item.id, item.content);
  }
}

Read a memory item

`GET /api/v1/agent/memory/items/{id}`

Reads one memory record by id (memory.detail). Pass ?project=&kind= to disambiguate. The daemon’s memAdminGate may still return admin_unauthorized when a socket admin capability is configured.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`project`	query	string	No	Project key the memory belongs to.
`kind`	query	string	No	Memory kind/store the record lives in.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector (§6.1) — `in:query` alias of `X-Hoody-Realm`.

Response

{
  "id": "mem_01HMZ3K9X8R7P2V4N6YTBJWQ5C",
  "project": "hoody-platform",
  "kind": "fact",
  "type": "fact",
  "content": "Payment provider is Stripe.",
  "created_at": "2026-01-15T12:34:56Z",
  "updated_at": "2026-01-15T12:34:56Z"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "admin_unauthorized",
  "message": "memory administration requires a valid admin token"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	The daemon’s `memAdminGate` refused the request.	Run the daemon with socket auth and no separate admin capability; or present the Memory-admin token for the interactive TUI.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`.	Reach the agent through `hoody-proxy`.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor `Retry-After` and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "store_unavailable",
  "message": "memory store unavailable"
}

Error Code	Title	Description	Resolution
`store_unavailable`	Memory store unavailable	The memory store could not be opened.	Retry once the store is warm; if persistent, inspect the daemon logs.

SDK usage

const item = await client.agent.memory.getMemoryItem({
  id: "mem_01HMZ3K9X8R7P2V4N6YTBJWQ5C",
  project: "hoody-platform",
  kind: "fact"
});

List memory projects

`GET /api/v1/agent/memory/projects`

Lists the memory projects (memory.projects). The daemon’s memAdminGate may still return admin_unauthorized when a socket admin capability is configured. Active-realm-scoped: a realm header is rejected.

Parameters

Name	In	Type	Required	Description
`page`	query	integer	No	1-based page number for pagination.
`limit`	query	integer	No	Maximum items per page (0 = no pagination).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector (§6.1) — `in:query` alias of `X-Hoody-Realm`.

Response

{
  "items": [
    {
      "project": "hoody-platform",
      "item_count": 47,
      "last_capture": "2026-01-15T13:01:22Z"
    },
    {
      "project": "docs-site",
      "item_count": 12,
      "last_capture": "2026-01-14T09:15:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 0
  }
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "admin_unauthorized",
  "message": "memory administration requires a valid admin token"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	The daemon’s `memAdminGate` refused the request.	Run the daemon with socket auth and no separate admin capability; or present the Memory-admin token for the interactive TUI.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`.	Reach the agent through `hoody-proxy`.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor `Retry-After` and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "store_unavailable",
  "message": "memory store unavailable"
}

Error Code	Title	Description	Resolution
`store_unavailable`	Memory store unavailable	The memory store could not be opened.	Retry once the store is warm; if persistent, inspect the daemon logs.

SDK usage

for await (const page of client.agent.memory.listMemoryProjectsIterator({
  limit: 50
})) {
  for (const project of page.items) {
    console.log(project.project, project.item_count);
  }
}

Search memory (hybrid recall)

`POST /api/v1/agent/memory/search`

Hybrid recall across a project (memory.search): BM25 + vector + graph fusion. The query is privacy-stripped server-side before any tokenize/embed; the read is no-touch (it never strengthens future ranking). The daemon’s memAdminGate may still return admin_unauthorized when a socket admin capability is configured. Active-realm-scoped: a realm header is rejected. Returns 503 store_unavailable when the memory store is not warm.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector (§6.1) — `in:query` alias of `X-Hoody-Realm`.

Request body

Name	Type	Required	Description
`project`	string	No	Project key to search within.
`query`	string	No	The natural-language recall query (privacy-stripped server-side).
`limit`	integer	No	Maximum hits to return.
`kinds`	array	No	Optional memory kinds/stores to restrict the search to.
`skip_graph`	boolean	No	Skip the graph-fusion component of recall.

{
  "project": "hoody-platform",
  "query": "how do we deploy to staging",
  "limit": 10,
  "kinds": ["fact", "workflow"],
  "skip_graph": false
}

Response

{
  "hits": [
    {
      "id": "mem_01HMZ3KB7T3F2N4P6X8YZWQJVR",
      "project": "hoody-platform",
      "kind": "workflow",
      "type": "workflow",
      "head": "Deploy to staging: 1) run migration 2) restart app 3) verify health",
      "scores": {
        "bm25": 0.82,
        "vector": 0.91,
        "graph": 0.45,
        "fused": 0.87
      }
    },
    {
      "id": "mem_01HMZ3K9X8R7P2V4N6YTBJWQ5C",
      "project": "hoody-platform",
      "kind": "fact",
      "type": "fact",
      "head": "Staging URL is https://staging.hoody.dev",
      "scores": {
        "bm25": 0.55,
        "vector": 0.78,
        "graph": 0.30,
        "fused": 0.61
      }
    }
  ]
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "admin_unauthorized",
  "message": "memory administration requires a valid admin token"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	The daemon’s `memAdminGate` refused the request.	Run the daemon with socket auth and no separate admin capability; or present the Memory-admin token for the interactive TUI.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`.	Reach the agent through `hoody-proxy`.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`, default 8 MiB). The gateway rejects an oversized body at the edge before the handler reads it.	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor `Retry-After` and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "store_unavailable",
  "message": "memory store unavailable"
}

Error Code	Title	Description	Resolution
`store_unavailable`	Memory store unavailable	The memory store could not be opened.	Retry once the store is warm; if persistent, inspect the daemon logs.

SDK usage

const results = await client.agent.memory.searchMemory({
  project: "hoody-platform",
  query: "how do we deploy to staging",
  limit: 10,
  kinds: ["fact", "workflow"]
});

Save a memory item

`POST /api/v1/agent/memory/items`

Stores a new memory record (memory.save). The daemon’s memAdminGate may still return admin_unauthorized when a socket admin capability is configured.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector (§6.1) — `in:query` alias of `X-Hoody-Realm`.

Request body

Name	Type	Required	Description
`project`	string	No	Project key the memory belongs to.
`content`	string	No	The memory content.
`type`	string	No	Memory type (e.g. `workflow`, `fact`).

{
  "project": "hoody-platform",
  "content": "Payment provider is Stripe.",
  "type": "fact"
}

Response

{
  "id": "mem_01HMZ3K9X8R7P2V4N6YTBJWQ5C",
  "project": "hoody-platform",
  "kind": "fact",
  "type": "fact",
  "content": "Payment provider is Stripe.",
  "created_at": "2026-01-15T12:34:56Z"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "admin_unauthorized",
  "message": "memory administration requires a valid admin token"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	The daemon’s `memAdminGate` refused the request.	Run the daemon with socket auth and no separate admin capability; or present the Memory-admin token for the interactive TUI.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`.	Reach the agent through `hoody-proxy`.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`, default 8 MiB).	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor `Retry-After` and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "store_unavailable",
  "message": "memory store unavailable"
}

Error Code	Title	Description	Resolution
`store_unavailable`	Memory store unavailable	The memory store could not be opened.	Retry once the store is warm; if persistent, inspect the daemon logs.

SDK usage

const saved = await client.agent.memory.saveMemoryItem({
  project: "hoody-platform",
  content: "Payment provider is Stripe.",
  type: "fact"
});

Edit a memory item

`PATCH /api/v1/agent/memory/items/{id}`

Patches a memory record by id (memory.edit). The daemon’s memAdminGate may still return admin_unauthorized when a socket admin capability is configured.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector (§6.1) — `in:query` alias of `X-Hoody-Realm`.

Request body

Name	Type	Required	Description
`project`	string	No	Project key the memory belongs to.
`kind`	string	No	Memory kind/store the record lives in.
`content`	string	No	Replacement memory content.

{
  "project": "hoody-platform",
  "kind": "fact",
  "content": "Payment provider is Stripe (primary) and Adyen (EU fallback)."
}

Response

{
  "id": "mem_01HMZ3K9X8R7P2V4N6YTBJWQ5C",
  "project": "hoody-platform",
  "kind": "fact",
  "type": "fact",
  "content": "Payment provider is Stripe (primary) and Adyen (EU fallback).",
  "updated_at": "2026-01-15T14:22:10Z"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "admin_unauthorized",
  "message": "memory administration requires a valid admin token"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	The daemon’s `memAdminGate` refused the request.	Run the daemon with socket auth and no separate admin capability; or present the Memory-admin token for the interactive TUI.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`.	Reach the agent through `hoody-proxy`.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`, default 8 MiB).	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor `Retry-After` and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "store_unavailable",
  "message": "memory store unavailable"
}

Error Code	Title	Description	Resolution
`store_unavailable`	Memory store unavailable	The memory store could not be opened.	Retry once the store is warm; if persistent, inspect the daemon logs.

SDK usage

const edited = await client.agent.memory.editMemoryItem({
  id: "mem_01HMZ3K9X8R7P2V4N6YTBJWQ5C",
  content: "Payment provider is Stripe (primary) and Adyen (EU fallback)."
});

Delete a memory item

`DELETE /api/v1/agent/memory/items`

Deletes a memory record (memory.delete). This is the cross-project delete — pass the identity in the body. The daemon’s memAdminGate may still return admin_unauthorized when a socket admin capability is configured.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector (§6.1) — `in:query` alias of `X-Hoody-Realm`.

Request body

Name	Type	Required	Description
`id`	string	Yes	Memory record id.
`project`	string	No	Project key the memory belongs to.
`kind`	string	No	Memory kind/store the record lives in.

{
  "id": "mem_01HMZ3K9X8R7P2V4N6YTBJWQ5C",
  "project": "hoody-platform",
  "kind": "fact"
}

Response

{
  "id": "mem_01HMZ3K9X8R7P2V4N6YTBJWQ5C",
  "deleted": true
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "admin_unauthorized",
  "message": "memory administration requires a valid admin token"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	The daemon’s `memAdminGate` refused the request.	Run the daemon with socket auth and no separate admin capability; or present the Memory-admin token for the interactive TUI.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`.	Reach the agent through `hoody-proxy`.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`, default 8 MiB).	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor `Retry-After` and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "store_unavailable",
  "message": "memory store unavailable"
}

Error Code	Title	Description	Resolution
`store_unavailable`	Memory store unavailable	The memory store could not be opened.	Retry once the store is warm; if persistent, inspect the daemon logs.

SDK usage

await client.agent.memory.deleteMemoryItem({
  id: "mem_01HMZ3K9X8R7P2V4N6YTBJWQ5C",
  project: "hoody-platform",
  kind: "fact"
});

Toggle memory capture

`PUT /api/v1/agent/memory/enabled`

Flips the memory privacy switch (memory.set_enabled) — persists features.memory and flips the live store. Not admin-gated. The body is {enabled: bool}.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector (§6.1) — `in:query` alias of `X-Hoody-Realm`.

Request body

Name	Type	Required	Description
`enabled`	boolean	No	Whether memory capture is enabled.

{
  "enabled": true
}

Response

{
  "enabled": true,
  "persisted": true
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`.	Reach the agent through `hoody-proxy`.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`, default 8 MiB).	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor `Retry-After` and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.memory.setMemoryEnabled({
  enabled: true
});

Flush the memory store

`POST /api/v1/agent/memory/flush`

Forces the memory store durability barrier (memory.flush). Not admin-gated. The request body is empty; the gateway scrubs every _-prefixed key and folds in the request scope (cwd/config_dir) before dispatch.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector (§6.1) — `in:query` alias of `X-Hoody-Realm`.

Request body

This endpoint accepts no body.

Response

{
  "flushed": true,
  "barrier_id": "durability_01HMZ3K9X8R7P2V4N6YTBJWQ5C",
  "duration_ms": 42
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`.	Reach the agent through `hoody-proxy`.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`, default 8 MiB).	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor `Retry-After` and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.memory.flushMemory();

Trigger consolidation (human-only)

`POST /api/v1/agent/memory/consolidate`

Requests a consolidation pass for a project (memory.consolidate). HUMAN-ONLY: consolidation spends multi-LLM passes and evolves memory state irreversibly, so an autonomous caller may never self-approve it. The gateway server-stamps the machine marker and the daemon’s human-only gate always refuses an HTTP call with 403 human_only (the HTTP edge has no service-level auth, but the human-only gate is a second, non-bypassable daemon factor).

Active-realm-scoped (a realm header is rejected).

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector (§6.1) — `in:query` alias of `X-Hoody-Realm`.

Request body

Name	Type	Required	Description
`project`	string	Yes	Project key to consolidate.
`min_observations`	integer	No	Optional minimum-observations threshold for a fact to be consolidated.

{
  "project": "hoody-platform",
  "min_observations": 3
}

Response

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "human_only",
  "message": "memory consolidation requires direct human confirmation and is not available to machine callers"
}

Error Code	Title	Description	Resolution
`admin_unauthorized`	Rejected by the daemon’s own admin gate	The daemon’s `memAdminGate` refused the request.	Run the daemon with socket auth and no separate admin capability; or present the Memory-admin token for the interactive TUI.
`human_only`	Human confirmation required	The operation requires direct human confirmation and is not available to machine callers — an autonomous caller may not self-approve it even with a valid admin token.	Trigger the operation from an interactive human session, not an autonomous/machine-confirmed dispatch.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`.	Reach the agent through `hoody-proxy`.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`, default 8 MiB).	Reduce the request body below the configured limit; split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor `Retry-After` and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "consolidate_unavailable",
  "message": "could not enqueue consolidation (queue full or memory disabled) — retry shortly"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.
`store_unavailable`	Memory store unavailable	The memory store could not be opened.	Retry once the store is warm; if persistent, inspect the daemon logs.
`consolidate_unavailable`	Consolidation unavailable	The consolidation pass could not be enqueued (maintenance queue full or memory disabled). It is reported as retryable rather than as a silent success.	Retry shortly; ensure memory capture is enabled.

SDK usage

// The daemon will refuse this with 403 human_only when called over HTTP.
// Run consolidation from an interactive TUI/CLI session instead.
try {
  await client.agent.memory.consolidateMemory({
    project: "hoody-platform",
    min_observations: 3
  });
} catch (err) {
  // err.code === "human_only" — expected for machine callers
}