Pages and buckets | Living Brain

Listing

listPages paginates automatically — iterate and the SDK fetches as it goes.

for await (const page of await client.workspace.listPages({ brainId, bucket: "ideas" })) {
  console.log(page.slug, page.status);
}

Filter by bucket (inbox, notes, ideas, projects) or status (active, deprecated, stale, contested, archived). Deprecated pages are hidden unless you pass includeDeprecated, and archived pages are hidden unless you pass includeArchived.

For bucket navigation with counts, buckets is one call instead of four:

const counts = await client.workspace.buckets({ brainId });

Reading a page

const page = await client.workspace.getPage({ brainId, slug: "attention-is-all-you-need" });

getPage bumps the page’s lastReferencedAt, which feeds the health score. Call it when a human or agent actually consumes the content — not to hydrate a list view.

Editing

Manual edits create a new version; the previous content stays in the history.

await client.workspace.editContent({ brainId, slug, body: "Revised content…" });
const versions = await client.workspace.pageVersions({ brainId, slug });

Organizing

await client.workspace.moveBucket({ brainId, slug, bucket: "projects" });
await client.workspace.pin({ brainId, slug, pinned: true });
await client.workspace.rename({ brainId, slug, title: "New title", newSlug: "new-title" });

Moving a page sets bucketSource: "user", which tells the brain not to re-route it. Pinned pages are prioritized in the prompt index and never deprecate.

Renaming changes the slug. Connections follow the page, but anything outside Living Brain holding the old slug will break.

Contested pages

When new material contradicts a page, its status becomes contested. Resolve it explicitly:

const contested = await client.workspace.listPages({ brainId, status: "contested" });
await client.workspace.resolve({ brainId, slug, resolution: "keep_new" });

Archiving

Archive a page to take it out of lists and search without losing anything. Its content, versions, and connections are kept, and restore brings it back as an active page.

await client.workspace.archive({ brainId, slug });
await client.workspace.restore({ brainId, slug });

To see archived pages, list with includeArchived or filter by status: "archived":

for await (const page of await client.workspace.listPages({ brainId, status: "archived" })) {
  console.log(page.slug);
}

Deleting

Use archive when a page might come back. Deleting is permanent.

await client.workspace.deletePermanently({ brainId, slug, permanent: "true" });
await client.workspace.recover({ brainId, slug });

permanent: "true" is required — the parameter exists as an explicit confirmation, not as a soft-delete toggle. The call removes the page, its versions, and its connections, and there is no undo. recover restores a deprecated page; it cannot bring back a deleted one.

reviewed is a legacy alias for recover, kept for backwards compatibility. Prefer recover.

Exporting

const bundle = await client.workspace.exportMarkdown({ brainId });