Logseq DB Graph

Logseq DB Graph

Overview

This skill provides a structured workflow for working with Logseq DB graphs through the Logseq app. It assumes the bundled Logseq app is connected so the Logseq tools are available for graph search, pages, blocks, tags, objects, properties, tasks, and assets.

Always treat the connected graph as a Logseq DB graph. Do not use legacy file-graph markdown conventions.

Prerequisites

• Logseq tools must be connected and accessible through OAuth.
• The target graph must be available through the Logseq app and must be non-E2EE.
• Confirm the graph, page, block, tag, object, property, or asset target before mutating data.
• Use read-only tools first when the user's target is ambiguous.

Required Workflow

Follow these steps in order. Do not skip steps.

Step 0: Connect the Logseq app if tools are unavailable

If Logseq tools are unavailable, pause and ask the user to connect the Logseq app:

1. Enable the Logseq app for this plugin or session.
2. Complete the Logseq OAuth flow if ChatGPT prompts for it.
3. Refresh the connector or restart the current session if tools still do not appear.

After the app is connected, finish your answer and tell the user to retry so the workflow can continue with Step 1.

Step 1: Clarify the user's goal and scope

Identify the intended graph and operation type:

• Capture a note or task.
• Create or update pages.
• Create, move, append, prepend, or delete blocks.
• Create or update tasks.
• Manage tags, objects, or properties.
• Upload, list, retrieve, or display assets.
• Search or list structured graph data.

Ask for missing graph, page, block, property, or asset identifiers only when the target cannot be resolved safely.

Step 2: Select DB semantic tools

Use dedicated Logseq DB semantic tools instead of legacy markdown patterns.

• Use task tools or DB batch transaction tools for tasks.
• Use page tools for page CRUD and page block listing.
• Use block tools for block CRUD, move, append, prepend, capture, insert tree, and property edits.
• Use tag, object, and property tools for structured metadata.
• Use asset tools for upload, listing, lookup, temporary links, and display.
• Use search only for discovery or unstructured lookup, not as a substitute for list APIs.

Step 3: Read first, then write

Execute tool calls in logical batches:

1. Read/list/search to resolve graph context and identifiers.
2. Create or update using DB semantic APIs.
3. For bulk operations, group related writes and use batch APIs when available.
4. For task creation or multi-field creation, prefer one DB batch transaction so the block and its typed properties are committed together.

Step 4: Summarize results

Report what changed, the graph/page/block identifiers involved when useful, and any unresolved ambiguity or failed operation. Do not claim a mutation succeeded unless the tool call completed successfully.

DB Semantics Rules

These rules are mandatory.

• Do not encode properties in block content with key:: value.
• Do not create markdown task content such as TODO buy milk, DONE buy milk, - [ ] buy milk, or - [x] buy milk.
• Do not use file-graph page property syntax, markdown front matter, or markdown checkboxes.
• Pages are blocks too, but use page APIs for page CRUD and page block listing when available.
• Use DB typed properties, DB classes, DB tags, and DB objects.
• Resolve property/class/tag/object identifiers through the API when needed.
• Use structured list APIs for pages, tasks, objects, tags, properties, assets, and filtered results.
• Exclude hidden items from returned or displayed results when the API exposes hidden item filtering.

Task Rules

When the user asks to create a task, always create a DB task through the dedicated task API or an equivalent DB batch transaction.

Examples:

• User says: create a task TODO buy milk
  • Interpret the task title as buy milk.
  • Set the DB status property to Todo.
  • Do not create a block titled TODO buy milk.
• User says: mark buy milk done
  • Find the existing DB task.
  • Update its DB status property to Done.
  • Do not rewrite markdown task prefixes.
• User says: create task buy milk priority urgent
  • Create the task block and set the DB Priority property with the API-supported value encoding.
  • If Priority is a choice/object property, resolve or create/select the supported value through the semantic API.

Property Rules

Always use DB property APIs and typed values.

• Set a property with the block/property API, not by appending property:: value to text.
• Remove a property with the property removal API, not by editing text.
• For batch property changes, use batch property APIs.
• Preserve existing values unless the user explicitly asks to replace them or the API parameter isResetExistingValues is set to true.
• Treat user-extensible property choices as data, not hard-coded enums.
• For class/tag-like values such as Task, pass the API-supported class/entity encoding.
• For status-like values such as Todo, use the API-supported status/choice/string encoding. Do not force every property value through entity-reference resolution.

Available Tool Categories

Use the currently exposed Logseq tool names. The exact names can differ between deployments, but they should fall into these categories:

• Graph discovery: list graphs, get graph metadata.
• Search: search graph content or filtered search results.
• Pages: list pages, get page, create page, update page, delete page, list page blocks.
• Blocks: get block, create block, update block, delete block, move blocks, append, prepend, capture to today's journal, insert block tree.
• Tasks: create tasks, list tasks, update task status or task properties.
• Tags and objects: list, get, create, update, delete tags or objects.
• Properties: list, get, create, update, delete properties; set/delete block property values; batch set/delete property values.
• Assets: upload asset, list assets, get asset metadata or temporary link, display image assets.

Practical Workflows

Capture a note

Resolve the graph, then use the capture API to append the content to today's journal. If today's journal does not exist, let the API create it.

Create a DB task

Use the task API or one DB batch transaction. Store the natural title without markdown task prefixes and set DB properties such as Status, Priority, Tags, or due date through typed property APIs.

Update task status or priority

Find the task by structured task/list APIs when possible. Update the DB Status or Priority property through semantic property APIs. Do not edit the block title to add or remove task markers.

Organize page content

Use page APIs to create or find the page. Use block tree insertion, append, prepend, or move APIs to change page content. Use page block listing instead of graph-wide search when the user asks for a page's blocks.

Manage tags or objects

Use tag/object CRUD APIs. Do not simulate tags by appending hashtags to block text unless the user specifically asks to edit text content.

Manage properties

Use property CRUD APIs for definitions and block property APIs for values. For multiple values or multiple blocks, use batch APIs and set isResetExistingValues only when replacing existing values is intended.

Work with assets

Use asset upload/list/get/display tools. When the user asks ChatGPT to show an image asset, use the dedicated image display tool. Do not modify R2 directly.

Troubleshooting

• Authentication: Ask the user to reconnect the Logseq app and complete OAuth.
• Missing tools: Ask the user to refresh or reinstall the Logseq connector, then retry.
• Ambiguous graph or page: list likely matches and ask the user to choose.
• Property validation errors: inspect the property schema and use the typed value encoding required by the API.
• Task created as plain text: correct it by creating/updating a DB task and removing the accidental markdown-style block only if the user permits deletion.
• Search returns too much data: use structured list APIs and filters instead of broad graph search.
• Rate limits or large graphs: narrow filters, paginate list APIs, and batch related writes.