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

200

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

SDK

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

200

[
  {
    "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

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

200

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

404

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

SDK

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.

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

Response

200

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

400

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

SDK

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.

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

Response

200

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

400

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

404

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

SDK

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

200

{
  "success": true
}

400

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

404

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

SDK

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

200

[
  {
    "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

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

200

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

404

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

SDK

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

200

{
  "count": 42
}

SDK

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).

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

200

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

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.

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

Response

200

[
  {
    "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

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

200

{
  "success": true
}

404

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

SDK

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

200

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

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

200

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

404

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

SDK

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