Memory

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"

type?string

Filter by memory type

Value in

"user"
"feedback"
"project"
"reference"

sort?string

Order memory headers by recent modification or normalized name

Value in

"recent"
"name"

cursor?string

Continue after this query-bound memory cursor

limit?integer

Maximum number of memories to return; defaults to 50 and is capped at 200

Formatint32

include_system?boolean

Include system-managed memory entries

Response Body

`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"    }  ],  "page": {    "has_more": true,    "limit": 0,    "next_cursor": "string",    "total": 0  }}

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.

agent_name?string

agent_tier?string

Value in

"workspace"
"global"

attribute?string

content*string

description?string

dry_run?boolean

entity?string

idempotency_key?string

metadata?

name*string

origin?string

Value in

"cli"
"http"
"uds"
"tool"
"extractor"
"dreaming"
"file"
"provider"

scope*string

Value in

"global"
"workspace"
"agent"

type*string

Value in

"user"
"feedback"
"project"
"reference"

workspace_id?string

Response Body

`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",      "workspace_id": "string"    },    "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}

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.

agent_name?string

agent_tier?string

Value in

"workspace"
"global"

content*string

scope*string

Value in

"global"
"workspace"
"agent"

slug?string

workspace_id?string

Response Body

`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"}

Get Memory v2 config metadata and provider registry state

GET/api/memory/config

Response Body

`application/json`

curl -X GET "https://example.com/api/memory/config"

{  "config": {    "controller": {      "default_op_on_fail": "string",      "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": {      "check_interval": "string",      "debounce": "string",      "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",      "inbox_path": "string",      "mode": "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"      ]    }  ]}

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`

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"    }  ]}

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

filename?string

Target memory filename

since?string

Only decisions since this timestamp

Formatdate-time

limit?integer

Maximum number of decisions to return

Formatint32

Response Body

`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",        "workspace_id": "string"      },      "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"    }  ]}

Get one Memory v2 controller decision

GET/api/memory/decisions/{decision_id}

Path Parameters

decision_id*string

Controller decision id

Response Body

`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",      "workspace_id": "string"    },    "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"  }}

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.

dry_run?boolean

reason?string

Response Body

`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",      "workspace_id": "string"    },    "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}

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`

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"    }  ]}

Get Memory v2 dreaming status

GET/api/memory/dreams/status

Response Body

`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"    }  ]}

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.

agent_name?string

agent_tier?string

Value in

"workspace"
"global"

force?boolean

scope?string

Value in

"global"
"workspace"
"agent"

workspace_id?string

Response Body

`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}

Get one Memory v2 dreaming run

GET/api/memory/dreams/{dream_id}

Path Parameters

dream_id*string

Dreaming run id

Response Body

`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"  }}

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.

failure_id?string

force?boolean

Response Body

`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}

Drain Memory v2 extractor queue

POST/api/memory/extractor/drain

Response Body

`application/json`

curl -X POST "https://example.com/api/memory/extractor/drain"

{  "drained_at": "2019-08-24T14:15:22Z",  "remaining": 0}

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`

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"    }  ]}

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.

failure_id?string

session_id?string

Response Body

`application/json`

curl -X POST "https://example.com/api/memory/extractor/retry" \  -H "Content-Type: application/json" \  -d '{}'

{  "failed": 0,  "retried": 0}

Get Memory v2 extractor queue status

GET/api/memory/extractor/status

Response Body

`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"  }}

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`

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}

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`

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"    }  ]}

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.

dry_run?boolean

filename*string

from*

idempotency_key?string

to*

Response Body

`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",      "workspace_id": "string"    },    "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}

List registered Memory v2 providers

GET/api/memory/providers

Response Body

`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"      ]    }  ]}

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`

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"    ]  }}

Get one Memory v2 provider

GET/api/memory/providers/{provider_name}

Path Parameters

provider_name*string

Memory provider name

Response Body

`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"    ]  }}

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`

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"    ]  }}

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`

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"    ]  }}

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`

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  }}

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.

agent_name?string

agent_tier?string

Value in

"workspace"
"global"

include_system?boolean

scope?string

Value in

"global"
"workspace"
"agent"

workspace_id?string

Response Body

`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"}

Invalidate Memory v2 frozen snapshots for the next session boot

POST/api/memory/reload

Response Body

`application/json`

curl -X POST "https://example.com/api/memory/reload"

{  "generation": 0,  "reloaded_at": "2019-08-24T14:15:22Z"}

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.

agent_name?string

agent_tier?string

Value in

"workspace"
"global"

confirm*boolean

derived_only*boolean

scope?string

Value in

"global"
"workspace"
"agent"

workspace_id?string

Response Body

`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"}

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`

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"  }}

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.

agent_name?string

agent_tier?string

Value in

"workspace"
"global"

already_surfaced?array<string>

context_hint?string

explain?boolean

include_already_surfaced?boolean

include_system?boolean

query_text*string

raw_candidates?integer

scope?string

Value in

"global"
"workspace"
"agent"

top_k?integer

workspace_id?string

Response Body

`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"      ]    }  ]}

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.

dry_run?boolean

older_than_hours*integer

Response Body

`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}

Repair materialized Memory v2 session ledgers

POST/api/memory/sessions/repair

Response Body

`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}

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`

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"    }  }}

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.

agent_name?string

agent_tier?string

Value in

"workspace"
"global"

content*string

description?string

dry_run?boolean

idempotency_key?string

metadata?

name?string

scope?string

Value in

"global"
"workspace"
"agent"

type?string

Value in

"user"
"feedback"
"project"
"reference"

workspace_id?string

Response Body

`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",      "workspace_id": "string"    },    "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}

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`

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",      "workspace_id": "string"    },    "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"  }}

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`

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"  }}

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.

include_memory?boolean

include_tool_events?boolean

Response Body

`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"}

200application/json

400application/json

404application/json

500application/json

200application/json

400application/json

409application/json

422application/json

500application/json

200application/json

400application/json

422application/json

500application/json

200application/json

500application/json

200application/json

400application/json

500application/json

200application/json

400application/json

500application/json

200application/json

404application/json

500application/json

200application/json

400application/json

404application/json

409application/json

500application/json

200application/json

400application/json

500application/json

200application/json

500application/json

200application/json

400application/json

409application/json

500application/json

200application/json

404application/json

500application/json

200application/json

400application/json

404application/json

500application/json

200application/json

500application/json

200application/json

400application/json

500application/json

200application/json

400application/json

500application/json

200application/json

500application/json

200application/json

400application/json

500application/json

200application/json

400application/json

500application/json

200application/json

400application/json

404application/json

409application/json

500application/json

200application/json

500application/json

200application/json

400application/json

404application/json

409application/json

500application/json

200application/json

404application/json

500application/json

200application/json

400application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`