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

Agent: Memory

Section titled “Agent: Memory”

The Agent Memory API exposes persistent memory across projects on a container-hosted Hoody agent. It lets you save, read, edit, and delete memory records, browse the project memory relation graph and the list of projects, run hybrid recall (BM25 + vector + graph fusion), toggle capture, flush the durability barrier, and consolidate memory. All routes are active-realm-scoped: passing a X-Hoody-Realm header or ?realm= parameter is rejected with realm_scope_unsupported. The daemon never returns unbounded lists — the page size is capped at 200 and the effective limit is echoed in meta.

Memory items

Section titled “Memory items”

Save a memory item

Section titled “Save a memory item”

POST /api/v1/agent/memory/items

Stores a new memory record (memory.save).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override
X-Hoody-ContainerheaderstringNoPer-request bound remote container
X-Hoody-RealmheaderstringNoPer-request realm selector
realmquerystringNoin:query alias of X-Hoody-Realm

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
projectstringYesProject key the memory belongs to
contentstringYesThe memory content
typestringNoMemory type (e.g. workflow, fact)

Response

Section titled “Response”
{
  "id": "mem_890abcdef12345678901cdef",
  "project": "acme-api",
  "kind": "memory",
  "type": "workflow",
  "content": "Always rebuild the SDK before publishing.",
  "created_at": "2026-01-12T14:22:09Z"
}

SDK usage

Section titled “SDK usage”
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-api",
    "content": "Always rebuild the SDK before publishing.",
    "type": "workflow"
  }'

List memory items

Section titled “List memory items”

GET /api/v1/agent/memory/items

Lists memory records for a project (memory.list). The ?type= and ?query= filters apply only to kind=memory; passing them with lesson, slot, or observation is rejected with 400. The daemon pages server-side and caps the page size at 200; an omitted or over-limit ?limit is clamped to 200, not interpreted as “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 (kind=memory only)
queryquerystringNoFree-text filter over the records (kind=memory only)
pagequeryintegerNo1-based page number
limitqueryintegerNoItems per page (1..200, clamped to 200)
X-Hoody-CwdheaderstringNoPer-request working-directory scope
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override
X-Hoody-ContainerheaderstringNoPer-request bound remote container
X-Hoody-RealmheaderstringNoPer-request realm selector
realmquerystringNoin:query alias of X-Hoody-Realm

Response

Section titled “Response”
{
  "items": [
    {
      "id": "mem_890abcdef12345678901cdef",
      "project": "acme-api",
      "kind": "memory",
      "type": "workflow",
      "content": "Always rebuild the SDK before publishing.",
      "created_at": "2026-01-12T14:22:09Z"
    },
    {
      "id": "mem_890abcdef12345678901abcd0",
      "project": "acme-api",
      "kind": "memory",
      "type": "fact",
      "content": "The publish job runs in region us-east-1.",
      "created_at": "2026-01-11T09:03:11Z"
    }
  ],
  "meta": {
    "total": 412,
    "page": 1,
    "limit": 200
  }
}

SDK usage

Section titled “SDK usage”
Terminal window
curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/items?project=acme-api&kind=memory&page=1&limit=50' \
  -H 'Authorization: Bearer <token>'

Read a memory item

Section titled “Read a memory item”

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

Reads one memory record by id (memory.detail). Pass ?project= and ?kind= to disambiguate.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesPath identifier
projectquerystringNoProject key the memory belongs to
kindquerystringNoMemory kind/store the record lives in
X-Hoody-CwdheaderstringNoPer-request working-directory scope
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override
X-Hoody-ContainerheaderstringNoPer-request bound remote container
X-Hoody-RealmheaderstringNoPer-request realm selector
realmquerystringNoin:query alias of X-Hoody-Realm

Response

Section titled “Response”
{
  "id": "mem_890abcdef12345678901cdef",
  "project": "acme-api",
  "kind": "memory",
  "type": "workflow",
  "content": "Always rebuild the SDK before publishing.",
  "created_at": "2026-01-12T14:22:09Z",
  "updated_at": "2026-01-12T14:22:09Z"
}

SDK usage

Section titled “SDK usage”
Terminal window
curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/items/mem_890abcdef12345678901cdef?project=acme-api&kind=memory' \
  -H 'Authorization: Bearer <token>'

Edit a memory item

Section titled “Edit a memory item”

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

Patches a memory record by id (memory.edit).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesPath identifier
X-Hoody-CwdheaderstringNoPer-request working-directory scope
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override
X-Hoody-ContainerheaderstringNoPer-request bound remote container
X-Hoody-RealmheaderstringNoPer-request realm selector
realmquerystringNoin:query alias of X-Hoody-Realm

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
projectstringNoProject key the memory belongs to
kindstringNoMemory kind/store the record lives in
contentstringNoReplacement memory content

Response

Section titled “Response”
{
  "id": "mem_890abcdef12345678901cdef",
  "project": "acme-api",
  "kind": "memory",
  "content": "Always rebuild the SDK and run integration tests before publishing.",
  "updated_at": "2026-01-12T15:02:11Z"
}

SDK usage

Section titled “SDK usage”
Terminal window
curl -X PATCH 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/items/mem_890abcdef12345678901cdef' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "project": "acme-api",
    "kind": "memory",
    "content": "Always rebuild the SDK and run integration tests before publishing."
  }'

Delete a memory item

Section titled “Delete a memory item”

DELETE /api/v1/agent/memory/items

Deletes a memory record (memory.delete). This is the cross-project delete; the request body carries the identity.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override
X-Hoody-ContainerheaderstringNoPer-request bound remote container
X-Hoody-RealmheaderstringNoPer-request realm selector
realmquerystringNoin:query alias of X-Hoody-Realm

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
idstringYesMemory record id
projectstringNoProject key the memory belongs to
kindstringNoMemory kind/store the record lives in

Response

Section titled “Response”
{
  "id": "mem_890abcdef12345678901cdef",
  "deleted": true
}

SDK usage

Section titled “SDK usage”
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 '{
    "id": "mem_890abcdef12345678901cdef",
    "project": "acme-api",
    "kind": "memory"
  }'

Memory graph and projects

Section titled “Memory graph and projects”

Read a memory relation graph

Section titled “Read a memory relation graph”

GET /api/v1/agent/memory/graph

Returns a paginated page of a project’s memory relation graph (memory.graph): nodes, edges, and stats. Filter with ?project= and ?node_type=; page with ?limit= and ?offset=. The route fails closed with 503 store_unavailable when the memory store is not warm.

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
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override
X-Hoody-ContainerheaderstringNoPer-request bound remote container
X-Hoody-RealmheaderstringNoPer-request realm selector
realmquerystringNoin:query alias of X-Hoody-Realm

Response

Section titled “Response”
{
  "nodes": [
    { "id": "mem_890abcdef12345678901cdef", "type": "workflow", "label": "Rebuild SDK" },
    { "id": "mem_890abcdef12345678901abcd0", "type": "fact", "label": "Publish region" }
  ],
  "edges": [
    { "from": "mem_890abcdef12345678901cdef", "to": "mem_890abcdef12345678901abcd0", "relation": "references" }
  ],
  "stats": { "node_count": 412, "edge_count": 1204 },
  "limit": 200,
  "offset": 0,
  "truncated": false
}

SDK usage

Section titled “SDK usage”
Terminal window
curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/memory/graph?project=acme-api&limit=200&offset=0' \
  -H 'Authorization: Bearer <token>'

List memory projects

Section titled “List memory projects”

GET /api/v1/agent/memory/projects

Lists the memory projects (memory.projects).

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
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override
X-Hoody-ContainerheaderstringNoPer-request bound remote container
X-Hoody-RealmheaderstringNoPer-request realm selector
realmquerystringNoin:query alias of X-Hoody-Realm

Response

Section titled “Response”
{
  "items": [
    { "key": "acme-api", "memory_count": 412, "last_active_at": "2026-01-12T14:22:09Z" },
    { "key": "billing-svc", "memory_count": 88, "last_active_at": "2026-01-09T11:00:00Z" }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 50
  }
}

SDK usage

Section titled “SDK usage”
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>'

Search and configuration

Section titled “Search and configuration”

Search memory (hybrid recall)

Section titled “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 or embed step; the read is no-touch and never strengthens future ranking. The route fails closed with 503 store_unavailable when the memory store is not warm.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override
X-Hoody-ContainerheaderstringNoPer-request bound remote container
X-Hoody-RealmheaderstringNoPer-request realm selector
realmquerystringNoin:query alias of X-Hoody-Realm

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
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

Response

Section titled “Response”
{
  "hits": [
    {
      "id": "mem_890abcdef12345678901cdef",
      "project": "acme-api",
      "kind": "memory",
      "score": 0.91,
      "fusion": { "bm25": 0.78, "vector": 0.94, "graph": 0.45 }
    },
    {
      "id": "mem_890abcdef12345678901abcd0",
      "project": "acme-api",
      "kind": "memory",
      "score": 0.74,
      "fusion": { "bm25": 0.62, "vector": 0.71, "graph": 0.30 }
    }
  ]
}

SDK usage

Section titled “SDK usage”
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-api",
    "query": "how do we publish the SDK safely",
    "limit": 10,
    "skip_graph": false
  }'

Toggle memory capture

Section titled “Toggle memory capture”

PUT /api/v1/agent/memory/enabled

Flips the memory privacy switch (memory.set_enabled), persists features.memory, and applies it immediately. Not restricted to admins.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override
X-Hoody-ContainerheaderstringNoPer-request bound remote container
X-Hoody-RealmheaderstringNoPer-request realm selector
realmquerystringNoin:query alias of X-Hoody-Realm

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
enabledbooleanNoWhether memory capture is enabled

Response

Section titled “Response”
{
  "enabled": true,
  "updated_at": "2026-01-12T15:30:44Z"
}

SDK usage

Section titled “SDK usage”
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
  }'

Flush the memory store

Section titled “Flush the memory store”

POST /api/v1/agent/memory/flush

Forces the memory store durability barrier (memory.flush). Not restricted to admins.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override
X-Hoody-ContainerheaderstringNoPer-request bound remote container
X-Hoody-RealmheaderstringNoPer-request realm selector
realmquerystringNoin:query alias of X-Hoody-Realm

Request Body

Section titled “Request Body”

This endpoint accepts a JSON object forwarded to the daemon memory.flush RPC. Reserved _-prefixed keys are ignored; the request scope (cwd / config_dir) is applied automatically. No fields are required.

Response

Section titled “Response”
{
  "flushed": true,
  "barrier_id": "barrier_890abcdef12345678901cdef",
  "flushed_at": "2026-01-12T15:34:11Z"
}

SDK usage

Section titled “SDK usage”
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 '{}'

Trigger a memory consolidation pass

Section titled “Trigger a memory consolidation pass”

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. An HTTP call to this operation always returns 403 human_only — a documented, enforced guarantee. Run consolidation from an interactive human session (TUI / CLI) instead.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override
X-Hoody-ContainerheaderstringNoPer-request bound remote container
X-Hoody-RealmheaderstringNoPer-request realm selector
realmquerystringNoin:query alias of X-Hoody-Realm

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
projectstringYesProject key to consolidate
min_observationsintegerNoOptional minimum-observations threshold for a fact to be consolidated

Response

Section titled “Response”
{
  "code": "bad_request",
  "message": "invalid request"
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parametersCorrect the request body or query parameters
realm_scope_unsupportedRealm scope unsupportedA per-request realm header was supplied to an active-only / global-no-realm RPCOmit the realm header on this route, or open a session to scope by realm

SDK usage

Section titled “SDK usage”
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-api",
    "min_observations": 5
  }'