Basalt

Basalt

Basalt is a Python CLI that reads a Markdown vault (Obsidian, Logseq, plain folder of .md) and compiles a longitudinal model of the user. It runs locally — Ollama for embeddings, SQLite for storage, no network calls in the Open tier. The user-facing artifact is The First Brief: a single page of citation-grounded findings.

Project home: https://github.com/virtexvirtuoso/basalt Site: https://virtuosoai.dev/basalt/

When to invoke this skill

• User asks to "find a buried insight," "compile a brief," "see what my vault knows about me," "find contradictions in my notes," "find connections across folders"
• User mentions running basalt, basalt brief, basalt index, basalt connection, basalt contradiction, basalt demo
• User wants to install or update Basalt locally
• User wants the agent to interpret Basalt's output (extract the load-bearing claim, suggest follow-ups, write a vault note based on the brief)

When NOT to invoke

• For generic semantic search inside a vault — that's Smart Connections territory, not Basalt
• For editing or writing notes — pair with the obsidian-cli or obsidian-markdown skill instead; Basalt is read-only over the corpus
• For RAG-style "answer my question from my notes" — Basalt does not chat with the corpus

Install

git clone https://github.com/virtexvirtuoso/basalt.git
cd basalt
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e .

Prereqs: Python 3.12+, Ollama, and ollama pull nomic-embed-text.

PyPI distribution will be basalt-vault (the name basalt is taken by an unrelated package). For now install from source.

Verbs shipped (Phase 0)

Verb	Site language	What it surfaces
Buried Insight	(a 5th, deeper unlock)	A note the user wrote once and never returned to, that recent notes still cite or semantically validate
Connection	"The two ideas in different folders that turn out to be the same idea"	Pairs of notes across different top-level folders, no wikilink between them, embedding similarity ≥ 0.78
Contradiction (v0)	"The two notes you wrote that can't both be true"	Pairs of same-topic notes whose load-bearing sentences carry asymmetric negation, reversal markers, or polarity pairs. v0 is heuristic — output is candidates, not verdicts

Planned (Phase 1) — fail clearly when requested

If the user asks for Implicit Thesis or Drift, the CLI will return a clear error message — those verbs are not yet shipped. Do not attempt to fake them. Tell the user they're scheduled for Phase 1.

Command reference

basalt index --vault PATH

Walks the vault, parses frontmatter, builds the wikilink graph, embeds every note via Ollama. Idempotent — content-hash incremental, so re-running only embeds changed notes.

basalt index --vault ~/notes
basalt index --vault ~/notes --skip-embed   # graph only, no embeddings
basalt index --vault ~/notes --embed-model bge-m3

The DB lives at ~/.basalt/basalt.db by default. Override with --db PATH.

basalt brief

Runs one or more Brief sections against the index built by basalt index.

basalt brief                                        # buried-insight, top 1 (default)
basalt brief --top 3                                # buried-insight, top 3
basalt brief --section connection --top 3           # 3 latent connections
basalt brief --section contradiction --top 3        # 3 contradiction candidates
basalt brief --section all --top 2                  # every shipped verb, 2 each
basalt brief --strict-defaults                      # buried-insight only — fixed 180/90/180 thresholds

--section accepts: buried-insight, connection, contradiction, all. Asking for implicit-thesis or drift returns a clear "not yet shipped" error.

basalt connection / basalt contradiction

Convenience subcommands — same as basalt brief --section <name> but accept their own thresholds:

basalt connection --top 5 --min-sim 0.78
basalt contradiction --top 3 --min-sim 0.72

basalt demo

Indexes a 14-note synthetic sample vault bundled with the repo and runs a brief. Useful when the user has no vault to point at, or for showing the agent how Basalt's output is shaped.

basalt demo                          # buried-insight on sample vault
basalt demo --section all --top 2    # every verb on sample vault

How to read the output

Each Brief section is rendered as a Rich-formatted block to the terminal. The shape:

• Header — section name + small "thresholds used" line for transparency
• Findings — one or more numbered findings; each has a path, a load-bearing quote, and a provenance label (callout body, first prose sentence, etc.)
• Validators / pair-mate — for Buried Insight: notes that link back or semantically validate; for Connection / Contradiction: the second note in the pair plus its quote
• Action prompts — ▸ Promote to thesis, ▸ Link A ↔ B, ▸ Mark resolved — these are suggestions, not auto-executed. The agent should ask the user before acting on them.

Common workflows

"Run Basalt on my vault and tell me the most interesting thing"

basalt index --vault ~/path/to/vault
basalt brief --section all --top 2

Then read the output and lead with the highest-scoring buried insight if one exists; fall back to the highest-similarity Connection if not. Quote the load-bearing sentence verbatim with its file path.

"Find a contradiction in my notes"

basalt brief --section contradiction --top 5 --db ~/.basalt/basalt.db

Read the output and flag the v0-heuristic disclaimer to the user — Basalt itself surfaces this in the section header. Do not present candidates as proven contradictions.

"Why didn't Basalt find anything?"

Most common causes:

1. Vault not indexed yet — run basalt index --vault PATH first
2. Vault too young / too sparse — Buried Insight needs notes ≥ 60 days old, Connection needs ≥ 60 words per note
3. Threshold too strict — try --min-sim 0.72 for Connection or pass --strict-defaults off
4. Ollama not running — ollama serve then re-run basalt index

If Buried Insight returns "vault may be too young" but the vault is old, check that ~/.basalt/basalt.db exists and is non-empty. Re-index if not.

"Save the Brief output as a vault note"

Basalt's CLI is read-only — to save the output, capture it and pass to whichever skill you have for writing notes (e.g., obsidian-cli):

basalt brief --section all --top 2 > /tmp/brief.txt
# then with the obsidian-cli skill, create a note with that content

A future MCP server wrapper will expose Basalt's verbs to MCP hosts directly — until then, this two-step is the canonical pattern.

Output structure (for parsing)

Each section is human-rendered to the terminal. There is no --format=json flag in 0.0.2. If the agent needs structured output, parse stderr-clean stdout via the section markers (THE BURIED INSIGHT, CONNECTIONS (N), CONTRADICTIONS (N)) and the ─ rules. JSON output is on the Phase 0 roadmap.

Privacy posture

The Open tier (everything in this repo) makes no network calls — Ollama runs locally, SQLite is local, no telemetry. The Pro tier (not yet released) sends the brief artifact (not the vault content) to a frontier model for higher-quality reasoning; vault content stays on the user's machine. Repeat this to the user if they ask whether their notes are being uploaded — they are not.

Honest limits to flag to the user

• Contradiction v0 produces false positives. It is a surface-text heuristic — pairs are candidates, not proven. Mark this clearly in any summary.
• Implicit Thesis and Drift are unbuilt. If the user asks for them, say so. Do not invent output.
• Quote extraction picks the load-bearing claim, not the whole note. If the user wants context, open the file path — Basalt only quotes one or two sentences.
• Hub notes (MOCs / index pages) are intentionally excluded from Buried Insight and from Connection/Contradiction candidates — this is by design, not a bug.