sense
Use sense to locate evidence in a markdown tree before reading files. Every command reconciles changed files first. Results contain paths, metadata, excerpts, and line ranges. Read the returned files or ranges when the task needs their prose.
Setup, store selection, presets, and note design belong to the
skill. Translating an Obsidian Bases file belongs to
.
Start with the tree
Run these when the tree or its configuration is unfamiliar:
sh
sense status # config, store, cache, document count, preset coverage
sense map # fields, hubs, recent notes
sense --list # saved queries
If a command reports a missing config, run
only when the user wants the tree configured. A one-off query does not authorize changing the tree.
Choose the command
| Need | Command |
|---|
| Exact count, filter, grouping, or known-field report | or a saved SQL query |
| Notes about a subject | |
| One note's frontmatter, outline, links, and backlinks | |
| Shortest link chain between two notes | |
| Similar notes that a note does not link to | |
| Tree shape and available fields | |
Start with a bounded result. Raise
, widen the preset, or broaden the words only when the first result does not answer the question.
sh
sense search "pricing" --k 10
sense search "sourcing quotes" --preset raw
sense peek notes/pricing-model.md
sense path onboarding.md pricing-model.md
sense related notes/pricing-model.md --k 10
sense sql "SELECT path FROM frontmatter WHERE status = ? LIMIT 50" active
Read the store guide before composing syntax
The config's
key selects the SQL dialect and text-search grammar. An omitted key means
. Bare words and quoted phrases work in
on every store. Advanced operators and raw text-index SQL differ.
Read the matching guide before writing raw SQL that uses engine functions, dates, JSON, text matching, or native types. Also read it before using advanced search operators.
- SQLite query guide
- DuckDB query guide
- Turso query guide
The tables,
placeholders, quoted identifiers,
,
, and preset
binding are shared.
Portable SQL documents the schema and queries that work without depending on one engine.
Search and evidence
combines the signals enabled by the selected preset:
| Signal | Evidence |
|---|
| The note contains the search words. shows the matching passages. |
| A note that matched links to this note. |
| The embedding model placed this note near the query. The search words may be absent. |
Combinations such as
mean that more than one signal produced the row.
ranks rows within that result only. Do not compare it across searches.
ranks vector evidence within the current result and model. Do not carry a fixed similarity cutoff between trees.
The
value points at the section that earned the row. Read that range when it is present. A null range means the whole note is the reference. A vector-only row has no lexical snippet and is a lead, not proof that the note contains the query terms.
Read search evidence and troubleshooting when a search will support a factual claim, when absence matters, when results look noisy, or when tuning signal weights.
Scope and output
Bare commands use the
preset.
chooses another. For
,
,
, and
change the query scope for one invocation, but cannot reach files that no preset indexes.
shows actual coverage.
filters search and graph commands against frontmatter alias
:
sh
sense search "pricing" --where "f.status = 'active' AND has(f.tags, 'sales')"
is index-wide by default. With
, the command binds a temporary
table. The SQL must join it:
sh
sense sql "SELECT f.path FROM frontmatter f JOIN scope ON scope.path = f.path" --preset default
Table output is for people. Use
when code or an agent will parse rows. Use
when redirecting a large row set to a file.
,
,
, and saved queries support all three formats.
,
,
, and
support table and JSON.
Saved queries
Save a query in
only when it will be reused:
json
{
"queries": {
"by-tag": { "sql": "SELECT path, title FROM frontmatter WHERE has(tags, ?) ORDER BY path" },
"hot": { "search": "pricing", "preset": "raw", "k": 20 }
}
}
Run these as
and
. Invocation flags override a saved search's
,
, or
value.
Running a saved entry validates it. Exit code 0 means it ran, 2 means the invocation needs different arguments, and 1 means the query or store failed. An empty result can be valid data, so interpret it from the query's purpose.
Tables
| Table | Holds |
|---|
| One discovered column per frontmatter key, plus , , , , , and |
| , , , and authored text, plus store-owned search columns |
| , written , resolved , and |
| Merged and deduplicated frontmatter and inline tags |
| Heading, level, line range, and token estimate |
| Paths covered by each preset |
Features can add tables.
and
show which features are active.
A non-null
means the file has no recovered frontmatter values. To distinguish a missing field from invalid frontmatter, include
in the filter. Fixes appear on the next command because reconciliation runs first.
Reading discipline
Select only the columns needed for the answer. Use
for row-returning exploration. Prefer
,
,
, and bounded snippets over
. Aggregates such as
and
are already bounded by their result shape.
When a result identifies a large note, use
and then read the relevant line range. Small files are often cheaper to read whole.
Worked command traces are in EXAMPLES.md.
Upkeep
- Install a missing CLI with
npm install -g sensemaking
- prints the cache path and watcher state.
- Delete the cache directory printed by only when the derived index is in doubt. The next command rebuilds it.
- Use when another process should keep the index warm during frequent edits. Queries remain responsible for their own freshness check.