Pages and buckets | Living Brain

Listing

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

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

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

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

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

Reading a page

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

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

Organizing

1 await client.workspace.moveBucket({ brainId, slug, bucket: "projects" });
2 await client.workspace.pin({ brainId, slug, pinned: true });
3 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:

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

Retiring

1 await client.workspace.deletePermanently({ brainId, slug, permanent: "true" });
2 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

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