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

Agent Memory API exposes the persistent memory store that backs the Hoody agent. Use these endpoints to read and write memory items, browse the memory relation graph, list memory projects, run hybrid recall search, toggle capture, flush the durability barrier, and trigger consolidation. All operations are active-realm-scoped: a per-request realm header is rejected with realm_scope_unsupported. Memory administration through the daemon’s own admin gate may return admin_unauthorized; requests must arrive through the Hoody proxy or they return forbidden.

Read — graph, items, projects

Section titled “Read — graph, items, projects”

GET /api/v1/agent/memory/graph

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

Read a paginated page of a project’s memory relation graph: nodes, edges, stats. Filter by 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.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id.
realmquerystringNoQuery alias of X-Hoody-Realm (read only when the header is absent).

Response

Section titled “Response”
{
  "nodes": [
    {
      "id": "n_8f3a1c",
      "type": "fact",
      "label": "Hoody proxy listens on 127.0.0.1:0",
      "weight": 0.92
    },
    {
      "id": "n_22b04e",
      "type": "workflow",
      "label": "deploy-prod-checklist",
      "weight": 0.74
    }
  ],
  "edges": [
    {
      "from": "n_8f3a1c",
      "to": "n_22b04e",
      "relation": "supports"
    }
  ],
  "stats": {
    "node_count": 1284,
    "edge_count": 4127,
    "types": ["fact", "workflow", "lesson"]
  },
  "limit": 50,
  "offset": 0,
  "truncated": false
}

SDK

Section titled “SDK”
await client.agent.memory.getMemoryGraph({ project: "hoody", limit: 50, offset: 0 })
Terminal window
curl "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/memory/graph?project=hoody&limit=50&offset=0"

GET /api/v1/agent/memory/items

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

Lists memory records for a project. The type and query filters apply only to kind=memory (the default store); passing them with lesson, slot, or observation is rejected with 400.

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.
queryquerystringNoFree-text filter over the records. kind=memory only.
pagequeryintegerNo1-based page number.
limitqueryintegerNoItems per page (1..200). Values above 200 are 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.
realmquerystringNoQuery alias of X-Hoody-Realm.

Response

Section titled “Response”
{
  "items": [
    {
      "id": "mem_01HXYZABCDEF",
      "project": "hoody",
      "kind": "memory",
      "type": "fact",
      "content": "Hoody proxy binds to a random localhost port by default.",
      "created_at": "2025-11-04T17:22:11Z"
    },
    {
      "id": "mem_01HXYZGHJKLM",
      "project": "hoody",
      "kind": "memory",
      "type": "workflow",
      "content": "Run `hoody deploy` then `hoody logs -f` to verify rollout.",
      "created_at": "2025-11-04T17:30:48Z"
    }
  ],
  "meta": {
    "total": 412,
    "page": 1,
    "limit": 50
  }
}

SDK

Section titled “SDK”
for await (const item of client.agent.memory.listMemoryItemsIterator({ project: "hoody", kind: "memory", limit: 50 })) {
  console.log(item.id, item.type)
}
Terminal window
curl "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/memory/items?project=hoody&kind=memory&page=1&limit=50"

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

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

Reads one memory record by id.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesMemory record id.
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.
realmquerystringNoQuery alias of X-Hoody-Realm.

Response

Section titled “Response”
{
  "id": "mem_01HXYZABCDEF",
  "project": "hoody",
  "kind": "memory",
  "type": "fact",
  "content": "Hoody proxy binds to a random localhost port by default.",
  "created_at": "2025-11-04T17:22:11Z",
  "updated_at": "2025-11-04T17:22:11Z"
}

SDK

Section titled “SDK”
const item = await client.agent.memory.getMemoryItem("mem_01HXYZABCDEF", { project: "hoody", kind: "memory" })
Terminal window
curl "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/memory/items/mem_01HXYZABCDEF?project=hoody&kind=memory"

GET /api/v1/agent/memory/projects

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

Lists 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.
realmquerystringNoQuery alias of X-Hoody-Realm.

Response

Section titled “Response”
{
  "items": [
    {
      "key": "hoody",
      "memory_count": 412,
      "last_active_at": "2025-11-05T08:14:02Z"
    },
    {
      "key": "docs-site",
      "memory_count": 87,
      "last_active_at": "2025-11-04T19:55:31Z"
    }
  ],
  "meta": {
    "total": 7,
    "page": 1,
    "limit": 50
  }
}

SDK

Section titled “SDK”
for await (const project of client.agent.memory.listMemoryProjectsIterator({ limit: 50 })) {
  console.log(project.key, project.memory_count)
}
Terminal window
curl "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/memory/projects?page=1&limit=50"

Search — hybrid recall

Section titled “Search — hybrid recall”

POST /api/v1/agent/memory/search

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

Runs hybrid recall across a project: BM25 + vector + graph fusion. The query is privacy-stripped before tokenization/embedding, and the read is no-touch (it never strengthens future ranking).

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.
realmquerystringNoQuery 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_01HXYZABCDEF",
      "kind": "memory",
      "type": "fact",
      "head": "Hoody proxy binds to a random localhost port by default.",
      "rank": {
        "bm25": 0.81,
        "vector": 0.74,
        "graph": 0.0,
        "fused": 0.79
      }
    },
    {
      "id": "mem_01HXYZGHJKLM",
      "kind": "memory",
      "type": "workflow",
      "head": "Run `hoody deploy` then `hoody logs -f` to verify rollout.",
      "rank": {
        "bm25": 0.42,
        "vector": 0.69,
        "graph": 0.55,
        "fused": 0.61
      }
    }
  ]
}

SDK

Section titled “SDK”
const { hits } = await client.agent.memory.searchMemory({
  project: "hoody",
  query: "how does the proxy bind its port?",
  limit: 10
})
Terminal window
curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/memory/search" \
  -H "Content-Type: application/json" \
  -d '{"project":"hoody","query":"how does the proxy bind its port?","limit":10}'

Write — save, edit, delete

Section titled “Write — save, edit, delete”

POST /api/v1/agent/memory/items

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

Stores a new memory record.

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.
realmquerystringNoQuery 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_01HXYZABCDEF",
  "project": "hoody",
  "kind": "memory",
  "type": "fact",
  "content": "Hoody proxy binds to a random localhost port by default.",
  "created_at": "2025-11-05T08:14:02Z"
}

SDK

Section titled “SDK”
await client.agent.memory.saveMemoryItem({
  project: "hoody",
  content: "Hoody proxy binds to a random localhost port by default.",
  type: "fact"
})
Terminal window
curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/memory/items" \
  -H "Content-Type: application/json" \
  -d '{"project":"hoody","content":"Hoody proxy binds to a random localhost port by default.","type":"fact"}'

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

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

Patches a memory record by id.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesMemory record id.
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.
realmquerystringNoQuery 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_01HXYZABCDEF",
  "project": "hoody",
  "kind": "memory",
  "type": "fact",
  "content": "Hoody proxy binds to 127.0.0.1 on a random ephemeral port by default.",
  "updated_at": "2025-11-05T09:02:47Z"
}

SDK

Section titled “SDK”
await client.agent.memory.editMemoryItem("mem_01HXYZABCDEF", {
  project: "hoody",
  kind: "memory",
  content: "Hoody proxy binds to 127.0.0.1 on a random ephemeral port by default."
})
Terminal window
curl -X PATCH "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/memory/items/mem_01HXYZABCDEF" \
  -H "Content-Type: application/json" \
  -d '{"project":"hoody","kind":"memory","content":"Hoody proxy binds to 127.0.0.1 on a random ephemeral port by default."}'

DELETE /api/v1/agent/memory/items

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

Deletes a memory record. This is the cross-project delete — the record identity comes from the request body.

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.
realmquerystringNoQuery 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_01HXYZABCDEF",
  "deleted": true
}

SDK

Section titled “SDK”
await client.agent.memory.deleteMemoryItem({
  id: "mem_01HXYZABCDEF",
  project: "hoody",
  kind: "memory"
})
Terminal window
curl -X DELETE "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/memory/items" \
  -H "Content-Type: application/json" \
  -d '{"id":"mem_01HXYZABCDEF","project":"hoody","kind":"memory"}'

State — enabled toggle, flush, consolidate

Section titled “State — enabled toggle, flush, consolidate”

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.

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.
realmquerystringNoQuery alias of X-Hoody-Realm.

Request Body

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

Response

Section titled “Response”
{
  "features": {
    "memory": true
  },
  "applied_at": "2025-11-05T09:18:11Z"
}

SDK

Section titled “SDK”
await client.agent.memory.setMemoryEnabled({ enabled: true })
Terminal window
curl -X PUT "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/memory/enabled" \
  -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 request body is a free-form object forwarded to the daemon memory.flush RPC; reserved _-prefixed keys are ignored and the request scope (cwd / config_dir) is applied automatically.

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.
realmquerystringNoQuery alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”

This endpoint accepts an empty body. No fields are documented.

Response

Section titled “Response”
{
  "flushed": true,
  "barrier_ms": 14,
  "at": "2025-11-05T09:18:11Z"
}

SDK

Section titled “SDK”
await client.agent.memory.flushMemory({})
Terminal window
curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/memory/flush" \
  -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.

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.
realmquerystringNoQuery 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 parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA per-request realm header was supplied to an active-only / global-no-realm RPC.Omit the realm header on this route.

SDK

Section titled “SDK”
// Note: HTTP callers always receive 403 human_only. Use the TUI/CLI from an
// interactive human session to actually run consolidation.
await client.agent.memory.consolidateMemory({ project: "hoody", min_observations: 5 })
Terminal window
# Note: this call will always return 403 human_only when invoked via HTTP.
curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/memory/consolidate" \
  -H "Content-Type: application/json" \
  -d '{"project":"hoody","min_observations":5}'