Logseq Zotero Sync

Logseq to Zotero Sync Skill

Automatically synchronize Logseq literature notes with Zotero by tagging referenced items with in_logseq.

When to Use This Skill

Use this skill when the user wants to:

• Tag Zotero items that are referenced in Logseq
• Maintain sync between Logseq #zotero pages and Zotero library
• Identify which Zotero items have been added to their Logseq knowledge base
• Periodically update the in_logseq tag for new literature notes

Keywords: logseq, zotero, sync, tagging, literature notes, bibliography, knowledge management

Overview

This skill syncs Logseq pages tagged with #zotero to Zotero by:

1. Query Logseq: Uses Logseq CLI to find all pages with #zotero tag and Zotero URL property
2. Extract Keys: Parses Zotero URLs to get item keys (e.g., "M2QGSQA9")
3. Batch Check: Queries Zotero for items already tagged with in_logseq
4. Smart Diff: Compares lists to find only items that need tagging
5. Tag: Adds in_logseq tag to items that don't have it

Key Feature: Idempotent batch processing - safe to run repeatedly, only tags what's needed.

Requirements

System Requirements

• Logseq Desktop app (CLI doesn't work with browser version)
• @logseq/cli installed globally (npm install -g @logseq/cli)
• Python 3.7+
• macOS (for Keychain credential storage)

Python Dependencies

pip3 install pyzotero keyring

Credentials

Shares credentials with zotero-tag-automation skill via macOS Keychain (service: zotero-tag-automation).

If credentials aren't set up yet:

python /Users/niyaro/.claude/skills/zotero-tag-automation/setup_credentials.py

Usage

Basic Command

cd /Users/niyaro/Documents/Code/logseq-zotero-sync
python sync_logseq_to_zotero.py

Auto-detects the most recent Logseq DB graph.

Specify Graph

python sync_logseq_to_zotero.py "2025-10-26 Logseq DB"

How It Works

Batch Check Approach (Efficient)

Instead of checking each item individually, this script:

1. Gets all Logseq items with Zotero URLs in one query
2. Gets all Zotero items with in_logseq tag in one query
3. Compares the two sets to find the difference
4. Only makes API calls to tag items that need it

This is much more efficient than checking each item one-by-one, especially as the library grows.

Logseq CLI Query

The script runs this datalog query via Logseq CLI:

[:find (pull ?b [:block/title {:user.property/ZoteroURL-om1JHnZv [:block/title]}])
 :where [?b :user.property/ZoteroURL-om1JHnZv]]

This finds all pages/blocks with the Zotero URL property and extracts the URLs.

URL Parsing

Zotero URLs have the format:

zotero://select/library/items/M2QGSQA9

The script extracts the item key (M2QGSQA9) using regex pattern matching.

Zotero API

Uses pyzotero to:

• Query items by tag: zot.items(tag='in_logseq')
• Get item data: zot.item(item_key)
• Update tags: zot.update_item(item)

Claude Code Integration

When the user asks to sync Logseq to Zotero or tag items in Zotero based on Logseq:

1. Verify credentials exist (check keychain or prompt user to run setup)
2. Identify the graph (ask user or auto-detect)
3. Run the script using Bash tool
4. Report results to user with summary

Example Workflow

User: "Tag all my Logseq literature notes in Zotero"

Claude:
1. Checks if credentials are set up
2. Lists available Logseq graphs
3. Asks user to confirm graph name
4. Runs: python sync_logseq_to_zotero.py "GraphName"
5. Shows summary of tagged items

Idempotency

The script is idempotent - running it multiple times has no negative effects:

• Items already tagged are skipped (with ⊙ symbol)
• Only new items get tagged
• No duplicate tags
• Safe to run daily/weekly as part of workflow

Output Format

==============================================================
Logseq to Zotero Sync
==============================================================

Querying Logseq graph: 2025-10-26 Logseq DB
Found 14 items in Logseq with Zotero URLs
Querying Zotero for items with 'in_logseq' tag...
Found 10 items already tagged with 'in_logseq'

Found 4 items that need tagging:
  - AA8CFB7Y
  - DUF7Q2B6
  - M2QGSQA9
  - ZTSWUK3C

Tagging 4 items with 'in_logseq'...

[1/4] ✓ AA8CFB7Y: Here we are together
[2/4] ✓ DUF7Q2B6: Reflections on Orthography
[3/4] ✓ M2QGSQA9: Taiwan Archaeology
[4/4] ✓ ZTSWUK3C: Who owns "the culture"

==============================================================
Summary:
  Successful: 4/4
  Failed: 0/4
  Tag: in_logseq
==============================================================

Troubleshooting

"Graph not found"

Problem: Logseq CLI can't find the graph Solutions:

• User is using browser version (CLI only works with Desktop)
• Run logseq list to see available graphs
• Make sure Logseq Desktop app is installed

"Credentials not found"

Problem: No credentials in Keychain Solution: Run setup script:

python /Users/niyaro/.claude/skills/zotero-tag-automation/setup_credentials.py

"Command not found: logseq"

Problem: @logseq/cli not installed Solution:

npm install -g @logseq/cli
logseq --version  # verify

Empty Results from Logseq

Problem: Query returns 0 items but user says items exist Possible causes:

• Property name changed (check actual property name in Logseq)
• Wrong graph selected
• Items are blocks not pages (query targets pages)
• Graph is file-based not DB-based (different query needed)

File Structure

/Users/niyaro/Documents/Code/logseq-zotero-sync/
├── sync_logseq_to_zotero.py    # Main script
├── requirements.txt             # Python dependencies
├── README.md                    # User documentation
├── SKILL.md                     # This file (skill documentation)
└── .gitignore                   # Git ignore rules

Related Skills

• logseq-cli: Interface with Logseq DB graphs
• zotero-tag-automation: Tag items after search
• zotero-mcp: Semantic search in Zotero
• zotero-mcp-agents: Autonomous Zotero search agents

Use Cases

1. Weekly Sync: Run script weekly to tag new literature notes
2. After Import: Run after importing items to Logseq
3. Curation: Use in_logseq tag in Zotero to see which items are in knowledge base
4. Workflow Integration: Part of literature review workflow

Future Enhancements

Potential improvements:

• Bidirectional sync (remove tag if removed from Logseq)
• Support multiple Logseq graphs
• Sync other metadata (notes, highlights)
• Web interface for manual sync
• Scheduled automatic sync

Security

• Credentials stored in macOS Keychain (encrypted)
• Shares keychain service with zotero-tag-automation
• No credentials in code or config files
• API key never displayed in output

Notes

• Claude Code only: This skill requires CLI access and Python execution
• Desktop only: Logseq browser version not supported by CLI
• Batch efficient: Uses smart diffing to minimize API calls
• Idempotent: Safe to run repeatedly without side effects