Logseq Rag Rs

logseq-rag-rs

A Rust toolkit for Logseq knowledge graphs with RAG (Retrieval-Augmented Generation) capabilities and graph utilities.

Features

• Vector Search: Semantic search across your Logseq notes using embeddings
• Full-Text Search: Traditional keyword-based search
• Hybrid Search: Combines vector and full-text search for best results
• URL Enrichment: Automatically fetch and add titles to bare URLs in your notes
• Logseq-Aware Parsing: Understands Logseq's outliner format and block hierarchy
• Smart Chunking: Context-preserving chunks that respect block structure
• MCP Server: Model Context Protocol server for AI assistant integration

Installation

# Build from source
cargo build --release

# The binaries will be at:
# target/release/logseq-rag      (CLI)
# target/release/logseq-rag-mcp  (MCP server)

Configuration

Create a .env file or set environment variables:

# Required
OPENROUTER_API_KEY=sk-or-v1-...

# Optional (with defaults)
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
EMBEDDING_MODEL=qwen/qwen3-embedding-8b
DATABASE_PATH=data/logseq.lance
VECTOR_SIZE=4096
CHUNK_SIZE=1200
CHUNK_OVERLAP=180

Usage

URL Enrichment

Before indexing, enrich your notes by fetching titles for bare URLs:

# Preview changes (dry run)
logseq-rag enrich-urls --logseq-dir ~/Documents/notes --dry-run

# Apply changes
logseq-rag enrich-urls --logseq-dir ~/Documents/notes

# Re-fetch titles (ignore cache)
logseq-rag enrich-urls --logseq-dir ~/Documents/notes --refresh-cache

This transforms:

- https://without.boats/blog/why-async-rust/

Into:

- Why Async Rust (https://without.boats/blog/why-async-rust/)

Indexing

Index your Logseq notes for search:

# Index with smart chunking (recommended, includes journals by default)
logseq-rag ingest --logseq-dir ~/Documents/notes

# Without journals
logseq-rag ingest --logseq-dir ~/Documents/notes --include-journals false

# Legacy mode (simple paragraph-based chunking)
logseq-rag ingest --logseq-dir ~/Documents/notes --smart false

Searching

# Hybrid search (recommended)
logseq-rag search "async rust executor"

# Vector-only search
logseq-rag search "async rust executor" --mode vector

# Full-text search
logseq-rag search "async rust executor" --mode text

# Limit results
logseq-rag search "async rust executor" --limit 5

# Filter by type
logseq-rag search "async rust executor" --only-journals
logseq-rag search "async rust executor" --exclude-journals

Database Management

# View statistics
logseq-rag stats

# List indexed files
logseq-rag list

Smart Chunking

The smart chunker understands Logseq's outliner format:

- Parent block
    - Child block 1
    - Child block 2
        - Grandchild

Instead of splitting arbitrarily, it:

1. Groups parent blocks with their children
2. Preserves context by including parent text in nested chunks
3. Respects block boundaries
4. Extracts [[page links]] and URLs as metadata
5. Stores block path (e.g., "Parent > Child > Grandchild")

MCP Server

For integration with AI assistants (Claude, etc.):

# Run the MCP server
logseq-rag-mcp

Add to your MCP client configuration:

{
  "mcpServers": {
    "logseq": {
      "command": "/path/to/logseq-rag-mcp",
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

Architecture

logseq-rag-rs/
├── logseq-rag-core/     # Shared library
│   ├── config.rs        # Configuration from env vars
│   ├── db.rs            # LanceDB wrapper (vector + FTS)
│   ├── embeddings.rs    # OpenRouter embeddings client
│   ├── logseq_parser.rs # Logseq block tree parser
│   ├── smart_chunker.rs # Hierarchy-aware chunking
│   ├── url_enricher.rs  # URL title fetching
│   └── url_cache.rs     # Persistent URL title cache
├── logseq-rag-cli/      # CLI binary
└── logseq-rag-mcp/      # MCP server binary

Future Tool Ideas

• Broken link checker - Find dead URLs and [[missing pages]]
• Orphan page finder - Pages with no incoming links
• Duplicate content detector - Find similar/duplicate blocks
• Graph visualization export - Export link graph for visualization tools
• Tag statistics - Analyze #tag usage across your graph
• Journal streaks - Track daily journaling habits
• Backlink analyzer - Deep analysis of page connections
• Content age report - Find stale/outdated notes

License

MIT