@safetnsr/cortex

Headless Obsidian vault CLI powered by qmd search. Read, create, search, and analyze markdown vaults without Obsidian desktop.

Obsidian CLI command structure + qmd search backend = headless vault CLI.

Install

npm i -g @safetnsr/cortex
# Requires qmd: npm i -g @tobilu/qmd

Quick Start

# Initialize a vault
cortex init ~/my-vault

# Create notes
cortex create "project-plan" --content "# Project Plan"
cortex create "meeting-notes" -t meeting -t weekly

# Read & append
cortex read project-plan
cortex append project-plan --content "## Next Steps"

# Search (powered by qmd)
cortex search "project plan"       # BM25
cortex vsearch "architecture"      # Vector similarity
cortex query "design decisions"    # Hybrid with reranking

# Daily notes
cortex daily                       # Today's note
cortex daily --date 2026-03-01     # Specific date

# Vault analysis
cortex tasks                       # All tasks across vault
cortex tasks --open                # Only open tasks
cortex tags                        # All tags with counts
cortex links project-plan          # Outgoing wikilinks
cortex backlinks project-plan      # Notes linking TO this note
cortex orphans                     # Notes with no incoming links
cortex broken                      # Broken wikilinks
cortex health                      # Vault health score
cortex list                        # All notes
cortex list projects               # Notes in subfolder

Commands

| Command | Description | |---------|-------------| | cortex init [path] | Initialize vault, set up qmd collection and index | | cortex read <note> | Read note by wikilink name or path | | cortex create <name> | Create a new note (--content, --template, -t tag) | | cortex append <note> | Append to note (--content) | | cortex search <query> | Full-text search via qmd (BM25) | | cortex vsearch <query> | Vector similarity search via qmd | | cortex query <query> | Hybrid search with reranking via qmd | | cortex daily | Create/read today's daily note (--date) | | cortex tasks | List all tasks (--open, --done) | | cortex tags | List all tags with counts | | cortex links <note> | Outgoing wikilinks from a note | | cortex backlinks <note> | Notes that link TO this note | | cortex orphans | Notes with no incoming links | | cortex broken | Broken wikilinks | | cortex health | Vault health score and stats | | cortex list [path] | List notes in vault |

All commands support --json for machine-readable output.

Architecture

• Search: Delegates to qmd (BM25, vector, hybrid) — no search reimplementation
• Vault ops: Direct filesystem with gray-matter for frontmatter parsing
• Link graph: better-sqlite3 for wikilink graph, backlinks, tasks, tags index
• Wikilinks: Full [[target]] and [[target|alias]] parsing

How it works

cortex init → creates .cortex.json + .cortex.db + qmd collection
cortex search → shells out to qmd CLI
cortex backlinks → queries the SQLite link graph
cortex health → combines graph stats into a health score

The link graph (.cortex.db) is rebuilt on cortex init. It tracks:

• All wikilinks between notes
• Tags (frontmatter + inline #tag)
• Tasks (- [ ] and - [x])

License

MIT