# Agent: Memory

**Page:** api/agent/memory

[Download Raw Markdown](./api/agent/memory.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Agent: Memory

Persistent memory blocks, journal entries, and history events for agent sessions. Use these endpoints to manage structured memory (`global` and `workspace` scopes), search and write journal entries, and audit memory changes over time.

All endpoints are scoped to a workspace via the `{workspaceID}` path parameter.

---

## Configuration

### `GET /api/v1/workspaces/{workspaceID}/memory/config`

Retrieve the memory system configuration for the workspace, including whether memory is enabled and the journal subsystem status.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |

### Response



```json
{
  "enabled": true,
  "journal": {
    "provider": "anthropic",
    "model": "claude-3-5-sonnet"
  }
}
```



### SDK

```ts
const config = await client.agent.memory.getConfig({
  workspaceID: "ws_01HXYZ..."
});
```

---

## Memory Blocks

Memory blocks are named, bounded text containers that agents can read from and write to. Each block has a `label`, a `scope` (`global` or `workspace`), an optional `limit`, and a `value`.

### `GET /api/v1/workspaces/{workspaceID}/memory/blocks`

List all memory blocks. Use the `?scope=global` or `?scope=workspace` query parameter to filter.

### Parameters



| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | workspaceID path parameter |


### Response



```json
[
  {
    "label": "persona",
    "scope": "global",
    "description": "Default agent persona and tone",
    "limit": 2000,
    "readOnly": false,
    "value": "You are a careful, concise coding assistant.",
    "projectID": null,
    "lastModified": 1717000000000,
    "charCount": 47
  },
  {
    "label": "user_prefs",
    "scope": "workspace",
    "description": "User preferences for the current workspace",
    "limit": 5000,
    "readOnly": true,
    "value": "Prefers TypeScript. Avoid emojis.",
    "projectID": "proj_abc123",
    "lastModified": 1717100000000,
    "charCount": 33
  }
]
```



### SDK

```ts
const blocks = await client.agent.memory.listBlocks({
  workspaceID: "ws_01HXYZ..."
});
```

---

### `GET /api/v1/workspaces/{workspaceID}/memory/blocks/{label}`

Retrieve a single memory block by its `label`.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |
| `label` | path | string | Yes | The memory block label. |

### Response



```json
{
  "label": "persona",
  "scope": "global",
  "description": "Default agent persona and tone",
  "limit": 2000,
  "readOnly": false,
  "value": "You are a careful, concise coding assistant.",
  "projectID": null,
  "lastModified": 1717000000000,
  "charCount": 47
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Memory block not found"
  }
}
```



### SDK

```ts
const block = await client.agent.memory.getBlock({
  workspaceID: "ws_01HXYZ...",
  label: "persona"
});
```

---

### `PUT /api/v1/workspaces/{workspaceID}/memory/blocks/{label}`

Create or overwrite a memory block. If a block with the given `label` and `scope` already exists, its `value` (and any other provided fields) are replaced.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |
| `label` | path | string | Yes | The memory block label. |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `scope` | string | Yes | Block scope. One of: `global`, `workspace`. |
| `value` | string | Yes | The block's text content. |
| `description` | string | No | Human-readable description of the block's purpose. |
| `limit` | number | No | Maximum character count for the block's value. |
| `readOnly` | boolean | No | When `true`, the block cannot be modified by the agent. |

```json
{
  "scope": "workspace",
  "value": "User prefers TypeScript and concise responses.",
  "description": "User coding preferences",
  "limit": 5000,
  "readOnly": true
}
```

### Response



```json
{
  "label": "user_prefs",
  "scope": "workspace",
  "description": "User coding preferences",
  "limit": 5000,
  "readOnly": true,
  "value": "User prefers TypeScript and concise responses.",
  "projectID": "proj_abc123",
  "lastModified": 1717200000000,
  "charCount": 49
}
```


```json
{
  "data": null,
  "errors": [
    {
      "code": "INVALID_SCOPE",
      "message": "scope must be one of: global, workspace"
    }
  ],
  "success": false
}
```



### SDK

```ts
const block = await client.agent.memory.setBlock({
  workspaceID: "ws_01HXYZ...",
  label: "user_prefs",
  scope: "workspace",
  value: "User prefers TypeScript and concise responses.",
  description: "User coding preferences",
  limit: 5000,
  readOnly: true
});
```

---

### `PATCH /api/v1/workspaces/{workspaceID}/memory/blocks/{label}`

Surgically replace a substring within a memory block's `value` without rewriting the entire block. The `old_str` must match exactly once within the current value.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |
| `label` | path | string | Yes | The memory block label. |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `scope` | string | Yes | Block scope. One of: `global`, `workspace`. |
| `old_str` | string | Yes | The exact substring to find in the current value. |
| `new_str` | string | Yes | The replacement string. |

```json
{
  "scope": "workspace",
  "old_str": "TypeScript",
  "new_str": "TypeScript and Go"
}
```

### Response



```json
{
  "label": "user_prefs",
  "scope": "workspace",
  "description": "User coding preferences",
  "limit": 5000,
  "readOnly": true,
  "value": "User prefers TypeScript and Go and concise responses.",
  "projectID": "proj_abc123",
  "lastModified": 1717300000000,
  "charCount": 53
}
```


```json
{
  "data": null,
  "errors": [
    {
      "code": "STRING_NOT_FOUND",
      "message": "old_str was not found in the block value"
    }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Memory block not found"
  }
}
```



### SDK

```ts
const block = await client.agent.memory.replaceBlock({
  workspaceID: "ws_01HXYZ...",
  label: "user_prefs",
  scope: "workspace",
  old_str: "TypeScript",
  new_str: "TypeScript and Go"
});
```

---

### `DELETE /api/v1/workspaces/{workspaceID}/memory/blocks/{label}`

Delete a custom memory block. Always pass the `scope` explicitly via the `?scope=global` or `?scope=workspace` query parameter to disambiguate which block to remove.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |
| `label` | path | string | Yes | The memory block label. |

### Response



```json
{
  "success": true
}
```


```json
{
  "data": null,
  "errors": [
    {
      "code": "MISSING_SCOPE",
      "message": "scope query parameter is required"
    }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Memory block not found"
  }
}
```



### SDK

```ts
const result = await client.agent.memory.deleteBlock({
  workspaceID: "ws_01HXYZ...",
  label: "user_prefs"
});
```

---

## Journal Entries

Journal entries are dated, tagged, free-form text records. Use them for session notes, decisions, and context the agent should retain across sessions.

### `GET /api/v1/workspaces/{workspaceID}/memory/journal`

List journal entries with optional filters (e.g. by project, tags, or date range).

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |

### Response



```json
[
  {
    "id": "jrn_01HABC...",
    "title": "Refactored auth middleware",
    "body": "Migrated from session cookies to JWT. Updated middleware in src/auth.ts.",
    "tags": ["refactor", "auth"],
    "created": 1717400000000,
    "projectID": "proj_abc123",
    "model": "claude-3-5-sonnet",
    "provider": "anthropic",
    "filePath": "memory/journal/2024-06-01-jrn_01HABC.md"
  }
]
```



### SDK

```ts
const entries = await client.agent.memory.listJournalEntries({
  workspaceID: "ws_01HXYZ..."
});
```

---

### `GET /api/v1/workspaces/{workspaceID}/memory/journal/{id}`

Retrieve a single journal entry by its ID.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |
| `id` | path | string | Yes | The journal entry ID. |

### Response



```json
{
  "id": "jrn_01HABC...",
  "title": "Refactored auth middleware",
  "body": "Migrated from session cookies to JWT. Updated middleware in src/auth.ts.",
  "tags": ["refactor", "auth"],
  "created": 1717400000000,
  "projectID": "proj_abc123",
  "model": "claude-3-5-sonnet",
  "provider": "anthropic",
  "filePath": "memory/journal/2024-06-01-jrn_01HABC.md"
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Journal entry not found"
  }
}
```



### SDK

```ts
const entry = await client.agent.memory.getJournalEntry({
  workspaceID: "ws_01HXYZ...",
  id: "jrn_01HABC..."
});
```

---

### `GET /api/v1/workspaces/{workspaceID}/memory/journal/count`

Return the number of journal entries for the current project. Useful for dashboards and quota checks.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |

### Response



```json
{
  "count": 42
}
```



### SDK

```ts
const { count } = await client.agent.memory.countJournalEntries({
  workspaceID: "ws_01HXYZ..."
});
```

---

### `POST /api/v1/workspaces/{workspaceID}/memory/journal`

Create a new journal entry. The `title` and `body` are required; `tags`, `projectID`, `model`, and `provider` are optional metadata.

### Parameters



| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | workspaceID path parameter |


### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `title` | string | Yes | Short title for the entry (max 1000 characters). |
| `body` | string | Yes | The entry body (max 100000 characters). |
| `tags` | array | No | Tags to associate with the entry (max 50, each max 100 characters). |
| `projectID` | string | No | Project scope for the entry. |
| `model` | string | No | Model identifier that produced the entry. |
| `provider` | string | No | Provider identifier (e.g. `anthropic`, `openai`). |

```json
{
  "title": "Decided on Vitest for unit tests",
  "body": "Vitest selected over Jest for better ESM support and faster startup.",
  "tags": ["testing", "decision"],
  "projectID": "proj_abc123",
  "model": "claude-3-5-sonnet",
  "provider": "anthropic"
}
```

### Response



```json
{
  "id": "jrn_01HDEF...",
  "title": "Decided on Vitest for unit tests",
  "body": "Vitest selected over Jest for better ESM support and faster startup.",
  "tags": ["testing", "decision"],
  "created": 1717500000000,
  "projectID": "proj_abc123",
  "model": "claude-3-5-sonnet",
  "provider": "anthropic",
  "filePath": "memory/journal/2024-06-02-jrn_01HDEF.md"
}
```



### SDK

```ts
const entry = await client.agent.memory.createJournalEntry({
  workspaceID: "ws_01HXYZ...",
  title: "Decided on Vitest for unit tests",
  body: "Vitest selected over Jest for better ESM support and faster startup.",
  tags: ["testing", "decision"],
  projectID: "proj_abc123",
  model: "claude-3-5-sonnet",
  provider: "anthropic"
});
```

---

### `POST /api/v1/workspaces/{workspaceID}/memory/journal/search`

Search journal entries by free-text query and/or tag filters. All fields in the request body are optional; omit them to broaden the search.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | No | Free-text query matched against title and body (max 1000 characters). |
| `projectID` | string | No | Restrict results to a specific project. |
| `tags` | array | No | Restrict results to entries with all of the specified tags (max 50, each max 100 characters). |
| `limit` | number | No | Maximum number of results to return. |

```json
{
  "text": "Vitest",
  "tags": ["testing"],
  "projectID": "proj_abc123",
  "limit": 20
}
```

### Response



```json
[
  {
    "id": "jrn_01HDEF...",
    "title": "Decided on Vitest for unit tests",
    "body": "Vitest selected over Jest for better ESM support and faster startup.",
    "tags": ["testing", "decision"],
    "created": 1717500000000,
    "projectID": "proj_abc123",
    "model": "claude-3-5-sonnet",
    "provider": "anthropic",
    "filePath": "memory/journal/2024-06-02-jrn_01HDEF.md"
  }
]
```



### SDK

```ts
const results = await client.agent.memory.searchJournalEntries({
  workspaceID: "ws_01HXYZ...",
  text: "Vitest",
  tags: ["testing"],
  projectID: "proj_abc123",
  limit: 20
});
```

---

### `DELETE /api/v1/workspaces/{workspaceID}/memory/journal/{id}`

Delete a journal entry by ID.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |
| `id` | path | string | Yes | The journal entry ID. |

### Response



```json
{
  "success": true
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Journal entry not found"
  }
}
```



### SDK

```ts
const result = await client.agent.memory.deleteJournalEntry({
  workspaceID: "ws_01HXYZ...",
  id: "jrn_01HDEF..."
});
```

---

## History

The history is an append-only audit log of memory mutations. Each event records the action (`set`, `replace`, `delete`, `create_journal`, `delete_journal`), its origin (`tool`, `ui`, `system`), and contextual metadata.

### `GET /api/v1/workspaces/{workspaceID}/memory/history`

List memory change history events with cursor-based pagination.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |

### Response



```json
{
  "items": [
    {
      "id": "evt_01HGHI...",
      "timestamp": 1717500000000,
      "action": "replace",
      "origin": "tool",
      "sessionID": "ses_abc123",
      "projectID": "proj_abc123",
      "scope": "workspace",
      "label": "user_prefs",
      "oldCharCount": 47,
      "newCharCount": 53,
      "journalID": null,
      "journalTitle": null,
      "journalTags": null
    },
    {
      "id": "evt_01HJKL...",
      "timestamp": 1717400000000,
      "action": "create_journal",
      "origin": "tool",
      "sessionID": "ses_abc123",
      "projectID": "proj_abc123",
      "scope": null,
      "label": null,
      "oldCharCount": null,
      "newCharCount": null,
      "journalID": "jrn_01HABC...",
      "journalTitle": "Refactored auth middleware",
      "journalTags": ["refactor", "auth"]
    }
  ],
  "total": 128,
  "hasMore": true,
  "nextCursor": "eyJ0cyI6MTcxNzUwMDAwMDAwMH0="
}
```



### SDK

```ts
const page = await client.agent.memory.listHistory({
  workspaceID: "ws_01HXYZ..."
});
```

---

### `GET /api/v1/workspaces/{workspaceID}/memory/history/{id}`

Retrieve a single history event with its full payload, including the old and new values, and any associated journal or block metadata.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |
| `id` | path | string | Yes | The history event ID. |

### Response



```json
{
  "id": "evt_01HJKL...",
  "timestamp": 1717400000000,
  "action": "create_journal",
  "origin": "tool",
  "sessionID": "ses_abc123",
  "projectID": "proj_abc123",
  "scope": null,
  "label": null,
  "oldCharCount": null,
  "newCharCount": null,
  "journalID": "jrn_01HABC...",
  "journalTitle": "Refactored auth middleware",
  "journalTags": ["refactor", "auth"],
  "oldValue": null,
  "newValue": null,
  "blockDescription": null,
  "blockLimit": null,
  "blockReadOnly": null,
  "journalBody": "Migrated from session cookies to JWT. Updated middleware in src/auth.ts.",
  "journalModel": "claude-3-5-sonnet",
  "journalProvider": "anthropic"
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "History event not found"
  }
}
```



### SDK

```ts
const event = await client.agent.memory.getHistoryEvent({
  workspaceID: "ws_01HXYZ...",
  id: "evt_01HJKL..."
});
```