Skip to content
Core ConceptsCLI ReferenceAPI Reference
AGH RuntimeAPI Reference

Memory

AGH Memory HTTP endpoints.

Audience
Operators running durable agent work
Focus
API Reference guidance shaped for scanability, day-two clarity, and operator context.

List Memory v2 curated entries

GET/api/memory

Query Parameters

scope?string

Memory scope

Value in"global" | "workspace" | "agent"
workspace_id?string

Durable workspace id

agent_name?string

Agent name for agent-scoped memory

agent_tier?string

Agent memory tier

Value in"workspace" | "global"
limit?integer

Maximum number of memories to return

Formatint32

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/memory"
{
  "memories": [
    {
      "agent_name": "string",
      "agent_tier": "workspace",
      "content_hash": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "description": "string",
      "filename": "string",
      "injection": true,
      "last_recalled_at": "2019-08-24T14:15:22Z",
      "mod_time": "2019-08-24T14:15:22Z",
      "name": "string",
      "recall_count": 0,
      "scope": "global",
      "staleness_banner": "string",
      "superseded_by": "string",
      "system_managed": true,
      "type": "user",
      "updated_at": "2019-08-24T14:15:22Z",
      "workspace_id": "string"
    }
  ]
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Create or propose one Memory v2 curated entry

POST/api/memory

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory" \  -H "Content-Type: application/json" \  -d '{    "content": "string",    "name": "string",    "scope": "global",    "type": "user"  }'
{
  "applied": true,
  "decision": {
    "agent_name": "string",
    "agent_tier": "workspace",
    "applied_at": "2019-08-24T14:15:22Z",
    "candidate_hash": "string",
    "confidence": 0.1,
    "decided_at": "2019-08-24T14:15:22Z",
    "frontmatter": {
      "agent_name": "string",
      "agent_tier": "workspace",
      "description": "string",
      "filename": "string",
      "mod_time": "2019-08-24T14:15:22Z",
      "name": "string",
      "provenance": {
        "confidence": "string",
        "created_at": "2019-08-24T14:15:22Z",
        "source_actor": "cli",
        "source_session_ids": [
          "string"
        ],
        "superseded_by": "string",
        "updated_at": "2019-08-24T14:15:22Z"
      },
      "scope": "global",
      "type": "user"
    },
    "id": "string",
    "idempotency_key": "string",
    "llm_trace": {
      "error": "string",
      "latency_ms": 0,
      "model": "string",
      "prompt_version": "string"
    },
    "op": "noop",
    "post_content_hash": "string",
    "prompt_version": "string",
    "reason": "string",
    "rule_trace": [
      {
        "details": "string",
        "name": "string",
        "passed": true,
        "reason": "string",
        "target": "string"
      }
    ],
    "scope": "global",
    "source": "rule",
    "target_filename": "string",
    "targets": [
      "string"
    ],
    "workspace_id": "string"
  },
  "dry_run": true
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Create a Memory v2 ad-hoc note for dreaming reconciliation

POST/api/memory/ad-hoc

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/ad-hoc" \  -H "Content-Type: application/json" \  -d '{    "content": "string",    "scope": "global"  }'
{
  "accepted": true,
  "created_at": "2019-08-24T14:15:22Z",
  "path": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Get Memory v2 config metadata and provider registry state

GET/api/memory/config

Response Body

application/json

application/json

curl -X GET "https://example.com/api/memory/config"
{
  "config": {
    "controller": {
      "default_op_on_fail": "string",
      "llm": {
        "enabled": true,
        "max_tokens_out": 0,
        "model": "string",
        "prompt_version": "string",
        "timeout": "string",
        "top_k": 0
      },
      "max_latency": "string",
      "mode": "string",
      "policy": {
        "allow_origins": [
          "string"
        ],
        "max_content_chars": 0,
        "max_writes_per_min": 0
      }
    },
    "daily": {
      "archive_path": "string",
      "cold_archive_days": 0,
      "dreaming_window": 0,
      "hard_delete_days": 0,
      "max_archive_bytes": 0,
      "max_bytes": 0,
      "max_lines": 0,
      "rotate_format": "string",
      "sweep_hour": 0
    },
    "decisions": {
      "keep_audit_summary": true,
      "max_post_content_bytes": 0,
      "prune_after_applied_days": 0
    },
    "dream": {
      "agent": "string",
      "check_interval": "string",
      "debounce": "string",
      "enabled": true,
      "gates": {
        "min_recall_count": 0,
        "min_score": 0.1,
        "min_unpromoted": 0
      },
      "min_hours": 0.1,
      "min_sessions": 0,
      "prompt_version": "string",
      "scoring": {
        "recency_half_life_days": 0,
        "weights": {
          "frequency": 0.1,
          "freshness": 0.1,
          "recency": 0.1,
          "relevance": 0.1
        }
      }
    },
    "enabled": true,
    "extractor": {
      "deadline": "string",
      "dlq_path": "string",
      "enabled": true,
      "inbox_path": "string",
      "mode": "string",
      "model": "string",
      "queue": {
        "capacity": 0,
        "coalesce_max": 0
      },
      "sandbox_inbox_only": true,
      "throttle_turns": 0
    },
    "file": {
      "max_bytes": 0,
      "max_lines": 0
    },
    "global_dir": "string",
    "provider": {
      "cooldown": "string",
      "failure_threshold": 0,
      "name": "string",
      "timeout": "string"
    },
    "recall": {
      "freshness": {
        "banner_after_days": 0
      },
      "fusion": "string",
      "include_already_surfaced": true,
      "include_system": true,
      "raw_candidates": 0,
      "signals": {
        "metrics_enabled": true,
        "queue_capacity": 0,
        "worker_retry_max": 0
      },
      "top_k": 0,
      "weights": {
        "bm25_trigram": 0.1,
        "bm25_unicode": 0.1,
        "recall_signal": 0.1,
        "recency": 0.1
      }
    },
    "session": {
      "cold_archive_days": 0,
      "events_purge_grace": "string",
      "hard_delete_days": 0,
      "ledger_format": "string",
      "ledger_root": "string",
      "max_archive_bytes": 0,
      "unbound_partition": "string"
    },
    "workspace": {
      "auto_create": true,
      "toml_path": "string"
    }
  },
  "locked_paths": [
    "string"
  ],
  "mutable_paths": [
    "string"
  ],
  "providers": [
    {
      "active": true,
      "builtin": true,
      "cooldown_until": "2019-08-24T14:15:22Z",
      "failure_count": 0,
      "last_error_code": "string",
      "name": "string",
      "status": "active",
      "tools": [
        "string"
      ]
    }
  ]
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

List Memory v2 daily operation logs

GET/api/memory/daily

Query Parameters

scope?string

Memory scope

Value in"global" | "workspace" | "agent"
workspace_id?string

Durable workspace id

agent_name?string

Agent name for agent-scoped memory

agent_tier?string

Agent memory tier

Value in"workspace" | "global"
date?string

Daily log date in YYYY-MM-DD format

limit?integer

Maximum number of daily logs to return

Formatint32

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/memory/daily"
{
  "logs": [
    {
      "agent_name": "string",
      "agent_tier": "workspace",
      "date": "string",
      "operation_count": 0,
      "path": "string",
      "scope": "global",
      "workspace_id": "string"
    }
  ]
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

List Memory v2 controller decisions

GET/api/memory/decisions

Query Parameters

scope?string

Memory scope

Value in"global" | "workspace" | "agent"
workspace_id?string

Durable workspace id

agent_name?string

Agent name for agent-scoped memory

agent_tier?string

Agent memory tier

Value in"workspace" | "global"
op?string

Controller decision op

since?string

Only decisions since this timestamp

Formatdate-time
limit?integer

Maximum number of decisions to return

Formatint32

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/memory/decisions"
{
  "decisions": [
    {
      "agent_name": "string",
      "agent_tier": "workspace",
      "applied_at": "2019-08-24T14:15:22Z",
      "candidate_hash": "string",
      "confidence": 0.1,
      "decided_at": "2019-08-24T14:15:22Z",
      "frontmatter": {
        "agent_name": "string",
        "agent_tier": "workspace",
        "description": "string",
        "filename": "string",
        "mod_time": "2019-08-24T14:15:22Z",
        "name": "string",
        "provenance": {
          "confidence": "string",
          "created_at": "2019-08-24T14:15:22Z",
          "source_actor": "cli",
          "source_session_ids": [
            "string"
          ],
          "superseded_by": "string",
          "updated_at": "2019-08-24T14:15:22Z"
        },
        "scope": "global",
        "type": "user"
      },
      "id": "string",
      "idempotency_key": "string",
      "llm_trace": {
        "error": "string",
        "latency_ms": 0,
        "model": "string",
        "prompt_version": "string"
      },
      "op": "noop",
      "post_content_hash": "string",
      "prompt_version": "string",
      "reason": "string",
      "rule_trace": [
        {
          "details": "string",
          "name": "string",
          "passed": true,
          "reason": "string",
          "target": "string"
        }
      ],
      "scope": "global",
      "source": "rule",
      "target_filename": "string",
      "targets": [
        "string"
      ],
      "workspace_id": "string"
    }
  ]
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Get one Memory v2 controller decision

GET/api/memory/decisions/{decision_id}

Path Parameters

decision_id*string

Controller decision id

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/memory/decisions/string"
{
  "decision": {
    "agent_name": "string",
    "agent_tier": "workspace",
    "applied_at": "2019-08-24T14:15:22Z",
    "candidate_hash": "string",
    "confidence": 0.1,
    "decided_at": "2019-08-24T14:15:22Z",
    "frontmatter": {
      "agent_name": "string",
      "agent_tier": "workspace",
      "description": "string",
      "filename": "string",
      "mod_time": "2019-08-24T14:15:22Z",
      "name": "string",
      "provenance": {
        "confidence": "string",
        "created_at": "2019-08-24T14:15:22Z",
        "source_actor": "cli",
        "source_session_ids": [
          "string"
        ],
        "superseded_by": "string",
        "updated_at": "2019-08-24T14:15:22Z"
      },
      "scope": "global",
      "type": "user"
    },
    "id": "string",
    "idempotency_key": "string",
    "llm_trace": {
      "error": "string",
      "latency_ms": 0,
      "model": "string",
      "prompt_version": "string"
    },
    "op": "noop",
    "post_content_hash": "string",
    "prompt_version": "string",
    "reason": "string",
    "rule_trace": [
      {
        "details": "string",
        "name": "string",
        "passed": true,
        "reason": "string",
        "target": "string"
      }
    ],
    "scope": "global",
    "source": "rule",
    "target_filename": "string",
    "targets": [
      "string"
    ],
    "workspace_id": "string"
  }
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Revert one applied Memory v2 controller decision

POST/api/memory/decisions/{decision_id}/revert

Path Parameters

decision_id*string

Controller decision id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/decisions/string/revert" \  -H "Content-Type: application/json" \  -d '{}'
{
  "decision": {
    "agent_name": "string",
    "agent_tier": "workspace",
    "applied_at": "2019-08-24T14:15:22Z",
    "candidate_hash": "string",
    "confidence": 0.1,
    "decided_at": "2019-08-24T14:15:22Z",
    "frontmatter": {
      "agent_name": "string",
      "agent_tier": "workspace",
      "description": "string",
      "filename": "string",
      "mod_time": "2019-08-24T14:15:22Z",
      "name": "string",
      "provenance": {
        "confidence": "string",
        "created_at": "2019-08-24T14:15:22Z",
        "source_actor": "cli",
        "source_session_ids": [
          "string"
        ],
        "superseded_by": "string",
        "updated_at": "2019-08-24T14:15:22Z"
      },
      "scope": "global",
      "type": "user"
    },
    "id": "string",
    "idempotency_key": "string",
    "llm_trace": {
      "error": "string",
      "latency_ms": 0,
      "model": "string",
      "prompt_version": "string"
    },
    "op": "noop",
    "post_content_hash": "string",
    "prompt_version": "string",
    "reason": "string",
    "rule_trace": [
      {
        "details": "string",
        "name": "string",
        "passed": true,
        "reason": "string",
        "target": "string"
      }
    ],
    "scope": "global",
    "source": "rule",
    "target_filename": "string",
    "targets": [
      "string"
    ],
    "workspace_id": "string"
  },
  "dry_run": true,
  "reverted": true
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

List Memory v2 dreaming runs

GET/api/memory/dreams

Query Parameters

scope?string

Memory scope

Value in"global" | "workspace" | "agent"
workspace_id?string

Durable workspace id

agent_name?string

Agent name for agent-scoped memory

agent_tier?string

Agent memory tier

Value in"workspace" | "global"
status?string

Dream status

limit?integer

Maximum number of dreaming runs to return

Formatint32

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/memory/dreams"
{
  "dreams": [
    {
      "agent_name": "string",
      "agent_tier": "workspace",
      "artifact_paths": [
        "string"
      ],
      "candidate_count": 0,
      "completed_at": "2019-08-24T14:15:22Z",
      "failure_path": "string",
      "failure_reason": "string",
      "id": "string",
      "lock_until": "2019-08-24T14:15:22Z",
      "promoted_count": 0,
      "scope": "global",
      "started_at": "2019-08-24T14:15:22Z",
      "status": "idle",
      "workspace_id": "string"
    }
  ]
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Get Memory v2 dreaming status

GET/api/memory/dreams/status

Response Body

application/json

application/json

curl -X GET "https://example.com/api/memory/dreams/status"
{
  "dreams": [
    {
      "agent_name": "string",
      "agent_tier": "workspace",
      "artifact_paths": [
        "string"
      ],
      "candidate_count": 0,
      "completed_at": "2019-08-24T14:15:22Z",
      "failure_path": "string",
      "failure_reason": "string",
      "id": "string",
      "lock_until": "2019-08-24T14:15:22Z",
      "promoted_count": 0,
      "scope": "global",
      "started_at": "2019-08-24T14:15:22Z",
      "status": "idle",
      "workspace_id": "string"
    }
  ]
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Trigger Memory v2 dreaming immediately

POST/api/memory/dreams/trigger

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/dreams/trigger" \  -H "Content-Type: application/json" \  -d '{}'
{
  "dream": {
    "agent_name": "string",
    "agent_tier": "workspace",
    "artifact_paths": [
      "string"
    ],
    "candidate_count": 0,
    "completed_at": "2019-08-24T14:15:22Z",
    "failure_path": "string",
    "failure_reason": "string",
    "id": "string",
    "lock_until": "2019-08-24T14:15:22Z",
    "promoted_count": 0,
    "scope": "global",
    "started_at": "2019-08-24T14:15:22Z",
    "status": "idle",
    "workspace_id": "string"
  },
  "reason": "string",
  "triggered": true
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Get one Memory v2 dreaming run

GET/api/memory/dreams/{dream_id}

Path Parameters

dream_id*string

Dreaming run id

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/memory/dreams/string"
{
  "dream": {
    "agent_name": "string",
    "agent_tier": "workspace",
    "artifact_paths": [
      "string"
    ],
    "candidate_count": 0,
    "completed_at": "2019-08-24T14:15:22Z",
    "failure_path": "string",
    "failure_reason": "string",
    "id": "string",
    "lock_until": "2019-08-24T14:15:22Z",
    "promoted_count": 0,
    "scope": "global",
    "started_at": "2019-08-24T14:15:22Z",
    "status": "idle",
    "workspace_id": "string"
  }
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Retry a failed Memory v2 dreaming run

POST/api/memory/dreams/{dream_id}/retry

Path Parameters

dream_id*string

Dreaming run id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/dreams/string/retry" \  -H "Content-Type: application/json" \  -d '{}'
{
  "dream": {
    "agent_name": "string",
    "agent_tier": "workspace",
    "artifact_paths": [
      "string"
    ],
    "candidate_count": 0,
    "completed_at": "2019-08-24T14:15:22Z",
    "failure_path": "string",
    "failure_reason": "string",
    "id": "string",
    "lock_until": "2019-08-24T14:15:22Z",
    "promoted_count": 0,
    "scope": "global",
    "started_at": "2019-08-24T14:15:22Z",
    "status": "idle",
    "workspace_id": "string"
  },
  "retried": true
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Drain Memory v2 extractor queue

POST/api/memory/extractor/drain

Response Body

application/json

application/json

curl -X POST "https://example.com/api/memory/extractor/drain"
{
  "drained_at": "2019-08-24T14:15:22Z",
  "remaining": 0
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

List Memory v2 extractor DLQ records

GET/api/memory/extractor/failures

Query Parameters

session_id?string

Filter by session id

limit?integer

Maximum number of failures to return

Formatint32

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/memory/extractor/failures"
{
  "failures": [
    {
      "agent_name": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "id": "string",
      "path": "string",
      "reason": "string",
      "session_id": "string",
      "workspace_id": "string"
    }
  ]
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Retry Memory v2 extractor DLQ records

POST/api/memory/extractor/retry

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/extractor/retry" \  -H "Content-Type: application/json" \  -d '{}'
{
  "failed": 0,
  "retried": 0
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Get Memory v2 extractor queue status

GET/api/memory/extractor/status

Response Body

application/json

application/json

curl -X GET "https://example.com/api/memory/extractor/status"
{
  "extractor": {
    "active_provider_sessions": 0,
    "backpressured_sessions": 0,
    "coalesced_turns": 0,
    "dropped_turns": 0,
    "failure_count": 0,
    "in_flight_sessions": 0,
    "queued_sessions": 0,
    "skipped_turns": 0,
    "status": "idle"
  }
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Get memory health

GET/api/memory/health

Query Parameters

scope?string

Memory scope

Value in"global" | "workspace" | "agent"
workspace_id?string

Durable workspace id

agent_name?string

Agent name for agent-scoped memory

agent_tier?string

Agent memory tier

Value in"workspace" | "global"

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/memory/health"
{
  "configured": true,
  "dream_agent": "string",
  "dream_check_interval": "string",
  "dream_enabled": true,
  "dream_min_hours": 0.1,
  "dream_min_sessions": 0,
  "enabled": true,
  "global_dir": "string",
  "global_files": 0,
  "indexed_files": 0,
  "last_consolidation": "2019-08-24T14:15:22Z",
  "last_operation_at": "2019-08-24T14:15:22Z",
  "last_reindex": "2019-08-24T14:15:22Z",
  "operation_count": 0,
  "orphaned_files": 0,
  "reason": "string",
  "status": "string",
  "workspace_count": 0,
  "workspace_files": 0
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

List redacted memory operation history

GET/api/memory/history

Query Parameters

scope?string

Memory scope

Value in"global" | "workspace" | "agent"
workspace_id?string

Durable workspace id

agent_name?string

Agent name for agent-scoped memory

agent_tier?string

Agent memory tier

Value in"workspace" | "global"
operation?string

Memory operation type

since?string

Only operations since this timestamp

Formatdate-time
limit?integer

Maximum number of operations to return

Formatint32

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/memory/history"
{
  "operations": [
    {
      "agent_name": "string",
      "agent_tier": "workspace",
      "filename": "string",
      "id": "string",
      "operation": "memory.write",
      "scope": "global",
      "summary": "string",
      "timestamp": "2019-08-24T14:15:22Z",
      "workspace_id": "string"
    }
  ]
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Promote a Memory v2 entry between scopes or agent tiers

POST/api/memory/promote

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/promote" \  -H "Content-Type: application/json" \  -d '{    "filename": "string",    "from": {      "scope": "global"    },    "to": {      "scope": "global"    }  }'
{
  "applied": true,
  "decision": {
    "agent_name": "string",
    "agent_tier": "workspace",
    "applied_at": "2019-08-24T14:15:22Z",
    "candidate_hash": "string",
    "confidence": 0.1,
    "decided_at": "2019-08-24T14:15:22Z",
    "frontmatter": {
      "agent_name": "string",
      "agent_tier": "workspace",
      "description": "string",
      "filename": "string",
      "mod_time": "2019-08-24T14:15:22Z",
      "name": "string",
      "provenance": {
        "confidence": "string",
        "created_at": "2019-08-24T14:15:22Z",
        "source_actor": "cli",
        "source_session_ids": [
          "string"
        ],
        "superseded_by": "string",
        "updated_at": "2019-08-24T14:15:22Z"
      },
      "scope": "global",
      "type": "user"
    },
    "id": "string",
    "idempotency_key": "string",
    "llm_trace": {
      "error": "string",
      "latency_ms": 0,
      "model": "string",
      "prompt_version": "string"
    },
    "op": "noop",
    "post_content_hash": "string",
    "prompt_version": "string",
    "reason": "string",
    "rule_trace": [
      {
        "details": "string",
        "name": "string",
        "passed": true,
        "reason": "string",
        "target": "string"
      }
    ],
    "scope": "global",
    "source": "rule",
    "target_filename": "string",
    "targets": [
      "string"
    ],
    "workspace_id": "string"
  },
  "dry_run": true
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

List registered Memory v2 providers

GET/api/memory/providers

Response Body

application/json

application/json

curl -X GET "https://example.com/api/memory/providers"
{
  "providers": [
    {
      "active": true,
      "builtin": true,
      "cooldown_until": "2019-08-24T14:15:22Z",
      "failure_count": 0,
      "last_error_code": "string",
      "name": "string",
      "status": "active",
      "tools": [
        "string"
      ]
    }
  ]
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Select the active Memory v2 provider

POST/api/memory/providers/select

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/providers/select" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{
  "provider": {
    "active": true,
    "builtin": true,
    "cooldown_until": "2019-08-24T14:15:22Z",
    "failure_count": 0,
    "last_error_code": "string",
    "name": "string",
    "status": "active",
    "tools": [
      "string"
    ]
  }
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Get one Memory v2 provider

GET/api/memory/providers/{provider_name}

Path Parameters

provider_name*string

Memory provider name

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/memory/providers/string"
{
  "provider": {
    "active": true,
    "builtin": true,
    "cooldown_until": "2019-08-24T14:15:22Z",
    "failure_count": 0,
    "last_error_code": "string",
    "name": "string",
    "status": "active",
    "tools": [
      "string"
    ]
  }
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Disable a Memory v2 provider

POST/api/memory/providers/{provider_name}/disable

Path Parameters

provider_name*string

Memory provider name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

reason?string

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/providers/string/disable" \  -H "Content-Type: application/json" \  -d '{}'
{
  "changed": true,
  "provider": {
    "active": true,
    "builtin": true,
    "cooldown_until": "2019-08-24T14:15:22Z",
    "failure_count": 0,
    "last_error_code": "string",
    "name": "string",
    "status": "active",
    "tools": [
      "string"
    ]
  }
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Enable a Memory v2 provider

POST/api/memory/providers/{provider_name}/enable

Path Parameters

provider_name*string

Memory provider name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

reason?string

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/providers/string/enable" \  -H "Content-Type: application/json" \  -d '{}'
{
  "changed": true,
  "provider": {
    "active": true,
    "builtin": true,
    "cooldown_until": "2019-08-24T14:15:22Z",
    "failure_count": 0,
    "last_error_code": "string",
    "name": "string",
    "status": "active",
    "tools": [
      "string"
    ]
  }
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Get one Memory v2 recall trace

GET/api/memory/recall-traces/{session_id}/{turn_seq}

Path Parameters

session_id*string

Session id

turn_seq*integer

Turn sequence

Formatint64

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/memory/recall-traces/string/0"
{
  "trace": {
    "executed_at": "2019-08-24T14:15:22Z",
    "options": {
      "allow_trivial_query": true,
      "already_surfaced": [
        "string"
      ],
      "include_already_surfaced": true,
      "include_system": true,
      "raw_candidates": 0,
      "top_k": 0
    },
    "query": {
      "agent_name": "string",
      "context_hint": "string",
      "query_text": "string",
      "workspace_id": "string"
    },
    "recall": {
      "blocks": [
        {
          "agent_tier": "workspace",
          "entries": [
            {
              "age_days": 0,
              "body": "string",
              "filename": "string",
              "id": "string",
              "mod_time": "2019-08-24T14:15:22Z",
              "staleness_banner": "string",
              "title": "string",
              "type": "user",
              "why_recalled": [
                "string"
              ],
              "workspace_id": "string"
            }
          ],
          "scope": "global"
        }
      ],
      "header": {
        "content_hash": "string",
        "text": "string"
      }
    },
    "session_id": "string",
    "skipped_reason": "string",
    "turn_seq": 0
  }
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Rebuild Memory v2 derived catalog indexes

POST/api/memory/reindex

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/reindex" \  -H "Content-Type: application/json" \  -d '{}'
{
  "agent_name": "string",
  "agent_tier": "workspace",
  "completed_at": "2019-08-24T14:15:22Z",
  "indexed_files": 0,
  "scope": "global",
  "workspace_id": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Invalidate Memory v2 frozen snapshots for the next session boot

POST/api/memory/reload

Response Body

application/json

application/json

curl -X POST "https://example.com/api/memory/reload"
{
  "generation": 0,
  "reloaded_at": "2019-08-24T14:15:22Z"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Reset Memory v2 derived state or curated storage

POST/api/memory/reset

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/reset" \  -H "Content-Type: application/json" \  -d '{    "confirm": true,    "derived_only": true  }'
{
  "deleted_files": 0,
  "deleted_rows": 0,
  "derived_only": true,
  "reset_at": "2019-08-24T14:15:22Z"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Resolve the effective Memory v2 scope/tier and precedence chain

GET/api/memory/scope-show

Query Parameters

scope?string

Memory scope

Value in"global" | "workspace" | "agent"
workspace_id?string

Durable workspace id

agent_name?string

Agent name for agent-scoped memory

agent_tier?string

Agent memory tier

Value in"workspace" | "global"

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/memory/scope-show"
{
  "precedence": [
    {
      "agent_name": "string",
      "agent_tier": "workspace",
      "scope": "global",
      "workspace_id": "string"
    }
  ],
  "roots": {
    "property1": "string",
    "property2": "string"
  },
  "selector": {
    "agent_name": "string",
    "agent_tier": "workspace",
    "scope": "global",
    "workspace_id": "string"
  }
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Run deterministic Memory v2 recall/search

POST/api/memory/search

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/search" \  -H "Content-Type: application/json" \  -d '{    "query_text": "string"  }'
{
  "recall": {
    "blocks": [
      {
        "agent_tier": "workspace",
        "entries": [
          {
            "age_days": 0,
            "body": "string",
            "filename": "string",
            "id": "string",
            "mod_time": "2019-08-24T14:15:22Z",
            "staleness_banner": "string",
            "title": "string",
            "type": "user",
            "why_recalled": [
              "string"
            ],
            "workspace_id": "string"
          }
        ],
        "scope": "global"
      }
    ],
    "header": {
      "content_hash": "string",
      "text": "string"
    }
  },
  "results": [
    {
      "already_shown": true,
      "memory": {
        "agent_name": "string",
        "agent_tier": "workspace",
        "content_hash": "string",
        "created_at": "2019-08-24T14:15:22Z",
        "description": "string",
        "filename": "string",
        "injection": true,
        "last_recalled_at": "2019-08-24T14:15:22Z",
        "mod_time": "2019-08-24T14:15:22Z",
        "name": "string",
        "recall_count": 0,
        "scope": "global",
        "staleness_banner": "string",
        "superseded_by": "string",
        "system_managed": true,
        "type": "user",
        "updated_at": "2019-08-24T14:15:22Z",
        "workspace_id": "string"
      },
      "score": 0.1,
      "shadowed_by": "string",
      "snippet": "string",
      "why_recalled": [
        "string"
      ]
    }
  ]
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Prune materialized Memory v2 session ledger state

POST/api/memory/sessions/prune

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/api/memory/sessions/prune" \  -H "Content-Type: application/json" \  -d '{    "older_than_hours": 0  }'
{
  "dry_run": true,
  "pruned_events": 0,
  "pruned_sessions": 0
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Repair materialized Memory v2 session ledgers

POST/api/memory/sessions/repair

Response Body

application/json

application/json

curl -X POST "https://example.com/api/memory/sessions/repair"
{
  "completed_at": "2019-08-24T14:15:22Z",
  "repaired_ledgers": 0,
  "skipped_ledgers": 0
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Read one memory document

GET/api/memory/{filename}

Path Parameters

filename*string

Memory filename

Query Parameters

scope?string

Memory scope

Value in"global" | "workspace" | "agent"
workspace_id?string

Durable workspace id

agent_name?string

Agent name for agent-scoped memory

agent_tier?string

Agent memory tier

Value in"workspace" | "global"

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/memory/string"
{
  "memory": {
    "content": "string",
    "summary": {
      "agent_name": "string",
      "agent_tier": "workspace",
      "content_hash": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "description": "string",
      "filename": "string",
      "injection": true,
      "last_recalled_at": "2019-08-24T14:15:22Z",
      "mod_time": "2019-08-24T14:15:22Z",
      "name": "string",
      "recall_count": 0,
      "scope": "global",
      "staleness_banner": "string",
      "superseded_by": "string",
      "system_managed": true,
      "type": "user",
      "updated_at": "2019-08-24T14:15:22Z",
      "workspace_id": "string"
    }
  }
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Edit one Memory v2 curated entry through the controller

PATCH/api/memory/{filename}

Path Parameters

filename*string

Memory filename

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/memory/string" \  -H "Content-Type: application/json" \  -d '{    "content": "string"  }'
{
  "applied": true,
  "decision": {
    "agent_name": "string",
    "agent_tier": "workspace",
    "applied_at": "2019-08-24T14:15:22Z",
    "candidate_hash": "string",
    "confidence": 0.1,
    "decided_at": "2019-08-24T14:15:22Z",
    "frontmatter": {
      "agent_name": "string",
      "agent_tier": "workspace",
      "description": "string",
      "filename": "string",
      "mod_time": "2019-08-24T14:15:22Z",
      "name": "string",
      "provenance": {
        "confidence": "string",
        "created_at": "2019-08-24T14:15:22Z",
        "source_actor": "cli",
        "source_session_ids": [
          "string"
        ],
        "superseded_by": "string",
        "updated_at": "2019-08-24T14:15:22Z"
      },
      "scope": "global",
      "type": "user"
    },
    "id": "string",
    "idempotency_key": "string",
    "llm_trace": {
      "error": "string",
      "latency_ms": 0,
      "model": "string",
      "prompt_version": "string"
    },
    "op": "noop",
    "post_content_hash": "string",
    "prompt_version": "string",
    "reason": "string",
    "rule_trace": [
      {
        "details": "string",
        "name": "string",
        "passed": true,
        "reason": "string",
        "target": "string"
      }
    ],
    "scope": "global",
    "source": "rule",
    "target_filename": "string",
    "targets": [
      "string"
    ],
    "workspace_id": "string"
  },
  "dry_run": true
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Delete one memory document

DELETE/api/memory/{filename}

Path Parameters

filename*string

Memory filename

Query Parameters

scope?string

Memory scope

Value in"global" | "workspace" | "agent"
workspace_id?string

Durable workspace id

agent_name?string

Agent name for agent-scoped memory

agent_tier?string

Agent memory tier

Value in"workspace" | "global"

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/memory/string"
{
  "applied": true,
  "decision": {
    "agent_name": "string",
    "agent_tier": "workspace",
    "applied_at": "2019-08-24T14:15:22Z",
    "candidate_hash": "string",
    "confidence": 0.1,
    "decided_at": "2019-08-24T14:15:22Z",
    "frontmatter": {
      "agent_name": "string",
      "agent_tier": "workspace",
      "description": "string",
      "filename": "string",
      "mod_time": "2019-08-24T14:15:22Z",
      "name": "string",
      "provenance": {
        "confidence": "string",
        "created_at": "2019-08-24T14:15:22Z",
        "source_actor": "cli",
        "source_session_ids": [
          "string"
        ],
        "superseded_by": "string",
        "updated_at": "2019-08-24T14:15:22Z"
      },
      "scope": "global",
      "type": "user"
    },
    "id": "string",
    "idempotency_key": "string",
    "llm_trace": {
      "error": "string",
      "latency_ms": 0,
      "model": "string",
      "prompt_version": "string"
    },
    "op": "noop",
    "post_content_hash": "string",
    "prompt_version": "string",
    "reason": "string",
    "rule_trace": [
      {
        "details": "string",
        "name": "string",
        "passed": true,
        "reason": "string",
        "target": "string"
      }
    ],
    "scope": "global",
    "source": "rule",
    "target_filename": "string",
    "targets": [
      "string"
    ],
    "workspace_id": "string"
  }
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Get one materialized Memory v2 session ledger

GET/api/workspaces/{workspace_id}/memory/sessions/{session_id}/ledger

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/memory/sessions/string/ledger"
{
  "events": [
    {
      "emitted_at": "2019-08-24T14:15:22Z",
      "event_type": "string",
      "payload": {
        "property1": null,
        "property2": null
      },
      "sequence": 0
    }
  ],
  "meta": {
    "checksum": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "parent_session_id": "string",
    "path": "string",
    "root_session_id": "string",
    "session_id": "string",
    "spawn_depth": 0,
    "stopped_at": "2019-08-24T14:15:22Z",
    "version": 0,
    "workspace_id": "string"
  }
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Replay one materialized Memory v2 session ledger

POST/api/workspaces/{workspace_id}/memory/sessions/{session_id}/replay

Path Parameters

workspace_id*string

Workspace id

session_id*string

Session id

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workspaces/string/memory/sessions/string/replay" \  -H "Content-Type: application/json" \  -d '{}'
{
  "events": [
    {
      "emitted_at": "2019-08-24T14:15:22Z",
      "event_type": "string",
      "payload": {
        "property1": null,
        "property2": null
      },
      "sequence": 0
    }
  ],
  "session_id": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
{
  "code": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
Empty

Agents

AGH Agents HTTP endpoints.

Skills

AGH Skills HTTP endpoints.