Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Agent: Memory

Section titled “Agent: Memory”

These endpoints manage persistent agent memory. Use them to read or modify the memory store, browse a project’s relation graph, run hybrid recall search, and toggle or flush capture. The realm a request acts in is selected per call: X-Hoody-Realm or ?realm= names it ("global" or a 24-hex realm id; the header wins), and omitted, the agent’s active realm. X-Hoody-Config-Dir selects which on-disk install a stateless read or write resolves against. Every call goes through the agent’s URL: Hoody Kit programs are reached through their URLs only, and a request refused by the Source IP Guard gets 403 forbidden.

Data-host classification and recovery

Section titled “Data-host classification and recovery”

GET /api/v1/agent/memory/datahost

Section titled “GET /api/v1/agent/memory/datahost”

Read the realm’s memory data host. The reply classifies which computer serves this realm’s memory and why it might not be served. state is one of leader (this computer serves it), follower (a healthy peer does), electing (the fleet is choosing, transiently none), unavailable (a host is named but unreachable from here), stuck (recovery cooldown, election errors, or a permission refusal), not_realm_member (this computer is not tagged into the realm), fleet_disabled (no Hoody fleet identity), or realm_blocked (the active realm selection is unavailable). Every one of those is a 200: a realm with no serving host is an answer, not a failure. hosts lists the live claimants and the current host; can_use_self says whether memory.claimDataHost would be offered.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/datahost' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Hoody-Config-Dir: /home/user/.hoody'

PUT /api/v1/agent/memory/datahost

Section titled “PUT /api/v1/agent/memory/datahost”

Elects THIS computer as the realm’s memory data host, the recovery action when a realm’s memory has no reachable host. Only self-assignment is implemented; naming a peer is refused 400 unsupported. expect_realm is mandatory in spirit but should be named: the daemon reads an absent field as the global realm rather than as “unspecified”, so omitting it is refused at the edge rather than silently assigning global. A realm switch between the data-host read and this call is refused 409 refused_realm_changed.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
NameTypeRequiredDescription
use_selfbooleanYesAssign THIS computer. Only true is implemented; false is refused 400 unsupported.
expect_realmstringNoThe realm this assignment is for: "global" for the global partition, or a 24-hex realm id. Required unless X-Hoody-Realm or ?realm= names the realm; refused 400 when neither does (an empty value means the global realm to the daemon, never “unspecified”), and 400 bad_request when it names another realm than they do.
Terminal window
curl -X PUT 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/datahost' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "use_self": true,
    "expect_realm": "global"
  }'

Status and listings

Section titled “Status and listings”

GET /api/v1/agent/memory/status

Section titled “GET /api/v1/agent/memory/status”

Reports whether memory is on, whether its store resolved, and what it holds. This is the discriminator the other memory reads cannot be: memory.listProjects and memory.listItems return a successful empty result for a realm whose memory is off, which is byte-identical to a healthy store with nothing in it. enabled is the persisted capture switch, available says whether a store resolved, degraded distinguishes a real fault from an off realm, and reason, remedy, and recoverable describe it. An off or degraded store is a 200 describing that state, not an error. totals covers the whole store; pass ?project= to also get that project’s counts, embedding_coverage, and last_consolidated_at. last_consolidated discriminates recorded, never, or unreadable, because a store that could not be read must not report the same “never” as one that has genuinely never consolidated. degraded_reads names any block whose read failed. Counts are the durable rows and may lag an in-flight capture batch; call memory.flush first for a barrier.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
projectquerystringNoProject key to report per-project counts, embedding coverage, and last-consolidation for. Omitted: only the whole-store totals are returned.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/status?project=acme-web' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Hoody-Config-Dir: /home/user/.hoody'

GET /api/v1/agent/memory/projects

Section titled “GET /api/v1/agent/memory/projects”

Lists the memory projects. The response is paged; pass ?page= and ?limit= (0 for no pagination).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pagequeryintegerNo1-based page number for pagination.
limitqueryintegerNoMaximum items per page (0 = no pagination).
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/projects?page=1&limit=50' \
  -H 'Authorization: Bearer <token>'

GET /api/v1/agent/memory/items

Section titled “GET /api/v1/agent/memory/items”

Lists memory records for a project. Filter via ?project=, ?kind=, ?type=, and ?query=. The type and query filters apply ONLY to kind=memory (the default store); the lesson, slot, and observation stores do not support these filters, so passing type or query with one of those kinds is REJECTED 400 rather than silently returning an unfiltered page. The daemon caps the page size at 200 and never returns an unbounded set, so the response always carries meta.page and meta.limit reflecting the effective page size. An omitted ?limit (or one over 200) pages at 200, not “no pagination”.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
projectquerystringNoProject key to scope the listing to.
kindquerystringNoMemory kind/store to filter by.
typequerystringNoMemory type to filter by (e.g. workflow, fact). kind=memory ONLY; rejected 400 with a lesson, slot, or observation kind.
queryquerystringNoFree-text filter over the records. kind=memory ONLY; rejected 400 with a lesson, slot, or observation kind.
pagequeryintegerNo1-based page number.
limitqueryintegerNoItems 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. NOT “no pagination”; the daemon never returns an unbounded set.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/items?project=acme-web&kind=memory&type=fact&page=1&limit=50' \
  -H 'Authorization: Bearer <token>'

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

Section titled “GET /api/v1/agent/memory/items/{id}”

Reads one memory record by id. Pass ?project= and ?kind=; a record the project does not hold is 404 not_found. record carries the stored fields in snake_case (for a memory: id, project, type, title, content, concepts, files, session_ids, source_observation_ids, strength, version, parent_id, supersedes, is_latest, forget_after, tier, retention, last_scored_at, created_at, updated_at, agent_id; a lesson, slot, or observation carries its own).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe item id.
projectquerystringNoProject key the memory belongs to.
kindquerystringNoMemory kind/store the record lives in.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/items/67e89abc123def456789abcd?project=acme-web&kind=memory' \
  -H 'Authorization: Bearer <token>'

GET /api/v1/agent/memory/graph

Section titled “GET /api/v1/agent/memory/graph”

Returns a paginated page of a project’s memory relation graph: nodes, edges, stats. Filter via ?project= and ?node_type=; page via ?limit= and ?offset=.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
projectquerystringNoProject key whose graph to read.
node_typequerystringNoOptional node-type filter.
limitqueryintegerNoMaximum nodes/edges to return.
offsetqueryintegerNoPagination offset into the graph.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
Terminal window
curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/graph?project=acme-web&node_type=memory&limit=200&offset=0' \
  -H 'Authorization: Bearer <token>'
Section titled “Search”

POST /api/v1/agent/memory/search

Section titled “POST /api/v1/agent/memory/search”

Hybrid recall across a project: BM25 + vector + graph fusion. The query is privacy-stripped before any tokenize or embed; the read is no-touch (it never strengthens future ranking).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
NameTypeRequiredDescription
projectstringNoProject key to search within.
querystringNoThe natural-language recall query (privacy-stripped server-side).
limitintegerNoMaximum hits to return.
kindsarrayNoOptional memory kinds/stores to restrict the search to.
skip_graphbooleanNoSkip the graph-fusion component of recall.
Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/search' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "project": "acme-web",
    "query": "stripe webhook retry behavior",
    "limit": 10
  }'

Memory writes

Section titled “Memory writes”

POST /api/v1/agent/memory/items

Section titled “POST /api/v1/agent/memory/items”

Stores a new memory record. A save here never supersedes an existing memory, however similar: two saves are always two records (an agent’s own saves may still replace a near-duplicate). The reply carries the new record’s id, type, title, and version, and superseded: the id of the record this save replaced, always "" on this route.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
NameTypeRequiredDescription
projectstringYesProject key the memory belongs to.
contentstringYesThe memory content.
typestringNoMemory type (e.g. workflow, fact).
conceptsarrayNoConcept tags to index the memory under.
filesarrayNoFile paths the memory is about.
ttl_daysintegerNoDays until the memory expires, counted from the save. Omitted, 0, or a negative value means no expiry. Must be a whole number between -2147483648 and 106751 (about 292 years, the longest expiry the store can represent); a value outside that range is REFUSED, never clamped and never treated as no expiry. A fractional value like 30.5 and a numeric string like "30" are both REFUSED too, never truncated or coerced. A silent coercion to 0 would store the memory with no expiry at all while reporting success.
strengthintegerNoInitial ranking strength, a whole number from 1 (weakest) to 10 (strongest). Omitted or 0 takes the store’s default of 7. Any other value (a negative number, anything above 10, a fractional value, or a numeric string) is REFUSED, never coerced and never silently replaced with the default.
expect_realmstringNoOptional realm assertion: "global" or a 24-hex realm id. The write is refused when the daemon’s active realm no longer matches, so it cannot land in a realm the caller switched away from.
Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/items' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "project": "acme-web",
    "content": "Stripe webhooks must be acknowledged within 5 seconds; the retry window is exponential.",
    "type": "fact",
    "concepts": ["stripe", "webhooks", "reliability"],
    "files": ["src/webhooks/stripe.ts"],
    "ttl_days": 90,
    "strength": 8
  }'

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

Section titled “PATCH /api/v1/agent/memory/items/{id}”

Patches a memory record by id. An id the project does not hold is 404 not_found. An absent body field preserves the stored value; a present one overwrites it.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe item id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
NameTypeRequiredDescription
projectstringNoProject key the record belongs to.
kindstringNoWhich store the record lives in. Omitted means memory. It selects which of the fields below apply; observation is not editable. Allowed values: memory, lesson, slot.
contentstringNoReplacement content. Applies to every kind, and is REQUIRED for kind=slot (a slot edit with no content is refused; use the delete route to remove a slot).
typestringNokind=memory: replacement memory type (e.g. workflow, fact).
conceptsarrayNokind=memory: replacement concept tags. The whole list is replaced, and a malformed array is rejected rather than silently truncated.
filesarrayNokind=memory: replacement file paths. The whole list is replaced, and a malformed array is rejected rather than silently truncated.
strengthintegerNokind=memory: replacement ranking strength, a whole number from 1 (weakest) to 10 (strongest). Any other value (0, a negative number, anything above 10, a fractional value, or a numeric string) is REFUSED, never coerced, and the stored strength is left unchanged.
ttl_daysintegerNokind=memory: days until the memory expires, counted from now. 0 or a negative value CLEARS the expiry and makes the memory permanent, so omit the field entirely on an edit that is not about retention. Must be a whole number between -2147483648 and 106751 (about 292 years, the longest expiry the store can represent); a value outside that range is REFUSED, never clamped, and the stored expiry is left unchanged. A fractional value like 30.5 and a numeric string like "30" are both REFUSED too, never truncated or coerced.
tierstringNokind=memory: replacement storage tier.
contextstringNokind=lesson: replacement context. Send it verbatim to preserve it; an absent value preserves the stored one, but the field is how the TUI resends it unchanged.
confidencenumberNokind=lesson: replacement confidence.
expect_realmstringNoOptional realm assertion: "global" or a 24-hex realm id. The edit is refused when the daemon’s active realm no longer matches.
Terminal window
curl -X PATCH 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/items/67e89abc123def456789abcd' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "project": "acme-web",
    "kind": "memory",
    "content": "Updated: Stripe webhooks must be acknowledged within 5 seconds; retries are exponential.",
    "strength": 9
  }'

DELETE /api/v1/agent/memory/items

Section titled “DELETE /api/v1/agent/memory/items”

Deletes a memory record. The delete is cross-project. Deletes one or many records in a single call: address them by ids, or by name/id for a slot. To erase a whole project, including its summaries, relation graph, and consolidation residue (none of which are reachable record by record), use memory.deleteProject instead.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
NameTypeRequiredDescription
idsarrayNoRecord ids to delete. Required for kind=memory, kind=observation, or kind=lesson (the empty/default kind included). A summary:<session_id>-prefixed id deletes a summary.
idstringNoA single record id; shorthand for a one-element ids. For kind=slot it is the slot NAME (an alias for name).
namestringNokind=slot: the slot to delete. Takes precedence over id.
projectstringNoProject key the records belong to.
kindstringNoWhich store the records live in. Omitted means memory. Allowed values: memory, observation, lesson, slot.
reasonstringNoOptional reason recorded on the governance audit row.
expect_realmstringNoOptional realm assertion: "global" or a 24-hex realm id. The delete is refused when the daemon’s active realm no longer matches.
Terminal window
curl -X DELETE 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/items' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": ["67e89abc123def456789abcd"],
    "project": "acme-web",
    "kind": "memory",
    "reason": "stale and now incorrect"
  }'

Memory lifecycle

Section titled “Memory lifecycle”

PUT /api/v1/agent/memory/enabled

Section titled “PUT /api/v1/agent/memory/enabled”

Flips the memory privacy switch: persists features.memory and applies it immediately. Not restricted to admins (the daemon applies no admin check to this call).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
NameTypeRequiredDescription
enabledbooleanYesWhether memory capture is enabled.

The SDK reaches this operation through two methods:

  • client.agent.memory.enable(...): sets enabled: true.
  • client.agent.memory.disable(...): sets enabled: false.
Terminal window
curl -X PUT 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/enabled' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true
  }'

POST /api/v1/agent/memory/flush

Section titled “POST /api/v1/agent/memory/flush”

Forces the memory store durability barrier. Not restricted to admins. The body is optional; every _-prefixed key is ignored, and all other keys are passed through verbatim.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”

JSON object. The schema declares no fields; document none and invent none. Every _-prefixed key is ignored (removed before dispatch), the request scope (cwd/config_dir) is added from the scope headers, and all other keys are passed through verbatim. No fields are required.

Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/flush' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /api/v1/agent/memory/consolidate

Section titled “POST /api/v1/agent/memory/consolidate”

Requests a consolidation pass for a project. HUMAN-ONLY: consolidation spends multi-LLM passes and evolves memory state irreversibly, so an autonomous caller may NEVER self-approve it. An HTTP request is always treated as coming from a machine, never from an interactive human, so a request that passes the admin check is refused 403 human_only. Run consolidation from an interactive human session (TUI/CLI) instead.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
NameTypeRequiredDescription
projectstringYesProject key to consolidate.
min_observationsintegerNoOptional minimum-observations threshold for a fact to be consolidated.
Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/consolidate' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "project": "acme-web",
    "min_observations": 3
  }'

Project erasure

Section titled “Project erasure”

POST /api/v1/agent/memory/write-intents

Section titled “POST /api/v1/agent/memory/write-intents”

Mints the single-use intent a guarded memory write requires. The intent binds {store, op, project}: it is spent the moment it is checked and is rejected for any other operation or project, so a retry after that point needs a fresh one. A request refused before the check (a realm that no longer matches, a missing project) leaves it unspent until it expires. op is currently "wipe_project" only (the intent for memory.deleteProject). It also binds the realm that was active when it was minted, so a realm switch between the mint and the write invalidates it rather than erasing another realm’s project. It expires, so mint it when you submit rather than when a form opens.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
NameTypeRequiredDescription
opstringYesThe write this intent authorizes. The minted intent is valid for this op alone. Allowed values: wipe_project.
projectstringYesProject key the write will target. The intent is valid for this project alone.
expect_realmstringNoOptional realm assertion: "global" or a 24-hex realm id. The request is refused when the daemon’s active realm no longer matches.
Terminal window
curl -X POST 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/write-intents' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "op": "wipe_project",
    "project": "acme-web"
  }'

DELETE /api/v1/agent/memory/projects/{project}

Section titled “DELETE /api/v1/agent/memory/projects/{project}”

Erases everything a project owns: its observations, memories, summaries, sessions, lessons, slots, documents, embeddings, search postings, relation graph, and provenance, plus the project registry row, the profile cache, and the consolidation cursor and input fingerprints. IRREVERSIBLE, and NOT the same as deleting every item the listing returns: summaries are not an enumerable kind, the relation graph has no delete surface, and none of the residue is addressable by id, so an item-by-item delete leaves a project that still shapes future recall and consolidation. Requires the single-use intent from memory.createWriteIntent (op "wipe_project", same project) in the body as nonce. Capture work queued before the erasure is drained first, and the injection epoch advances on both the success and the failure path, so no session re-injects erased content. The audit row survives by design; it records counts, never content.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
projectpathstringYesThe project.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read only when the header is absent): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.

Request body

Section titled “Request body”
NameTypeRequiredDescription
noncestringYesThe single-use intent from memory.createWriteIntent, minted for op "wipe_project" and this project.
reasonstringNoOptional reason recorded on the audit row.
expect_realmstringNoOptional realm assertion: "global" or a 24-hex realm id. The request is refused when the daemon’s active realm no longer matches.
Terminal window
curl -X DELETE 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/projects/acme-web' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "nonce": "intent_67e89abc123def456789abcd",
    "reason": "test cleanup"
  }'