npm package: @safetnsr/cortex
Description: Headless Obsidian vault CLI powered by qmd search. Read, create, search, and analyze markdown vaults without Obsidian desktop.
Author: safetnsr
Latest version: 0.1.0

# @safetnsr/cortex

Headless Obsidian vault CLI powered by [qmd](https://github.com/nicholasgasior/qmd) search. Read, create, search, and analyze markdown vaults without Obsidian desktop.

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

## Install

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

## Quick Start

```bash
# 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