---
type: project
title: "mql — Markdown Query Language CLI"
status: active
started: 2026-04-19
tags: [tooling, go, pkb]
---

# mql — Markdown Query Language CLI

## Why

The Council's members currently reach for Grep + Read to find patterns across `daily/`, `notes/`, `projects/`, `reading/`. Grep is stringly-typed; it doesn't understand YAML frontmatter, wikilinks, tags, or Obsidian Bases. As the PKB grows, "find all sessions where winner = X" or "list permanent notes tagged with Y linked to project Z" will be load-bearing queries, and a proper query tool pays off.

`mql` is a Go CLI that indexes and queries any repo with Markdown + YAML frontmatter + wikilinks + tags + Obsidian Bases, exposing a Dataview-compatible query language from outside Obsidian.

## Outcome definition

v0.1 shipped and installed in `~/.local/bin/mql`:
- Cold-scan builds a SQLite index under `~/.cache/mql/<vault-hash>.sqlite`.
- `mql 'LIST FROM "sessions" WHERE winner = "vaasa"'` returns JSON.
- `mql base <name>` executes an Obsidian `.base` file as a query.
- Researcher and `/ask-*`-invoked members can shell out to `mql` instead of grep-walking directories.

## Constraints

- Go (single static binary across Linux/macOS/Windows).
- Pure-Go SQLite (modernc.org/sqlite) — no cgo, no C toolchain at build time.
- MIT or Apache-2.0 license (open-source candidate).
- Dataview-compatible subset; `GROUP BY`, `FLATTEN`, `TASK`/`CALENDAR`, inline fields in prose, and `dataviewjs` are explicitly out for v0.1.

## Log

See [[log]].

## Links

- Sibling repo: `~/projects/mql/` (separate from this repo).
- Design: `~/projects/mql/docs/structure/initial-plan.md`.
- First customer: this vault. `/var/mnt/data/projects/council/` is the v0.1 integration-test fixture.