---
name: talon
description: Agent-facing contract for Obsidian vault search, ask, read, sync, recall, related, meta, changes, inspect, and status.
---
# Talon
Use Talon to search and inspect an indexed Obsidian vault. Talon is optimized for agents: start with natural-language search, inspect compact navigation metadata, follow the graph when useful, then read exact notes or sections.
> **Claude Code**: vault recall is injected automatically before each turn — no recall tool call needed. Use the MCP tools below for explicit queries only.
>
> **MCP** exposes `talon_search`, `talon_read`, and `talon_related`. It intentionally does not expose `talon_ask`; agents should use search/read and synthesize with their own model. If you truly need Talon's built-in synthesis, call the CLI.
Always pass `--agent` on every command (unless you specifically need metadata that only `--json` provides). The examples below are the pattern to follow.
## Default Search
Use normal search first:
```bash
talon --agent search "<natural language query>"
```
Search defaults to hybrid retrieval. It combines lexical matching, semantic/vector search, title and alias matching, query expansion, reranking, graph-refined ranking, and scope-aware ranking when the configured sidecar is available. A good natural-language query is usually the highest-value call.
Only switch modes when there is a reason:
- `--mode fulltext` for exact wording, command names, IDs, or when semantic search is over-broad.
- `--mode title` when you are looking for a note by title or alias.
- `--mode semantic` when wording may differ strongly from the user's phrasing.
- `--fast` only when you explicitly need lexical-only speed and can skip embeddings/rerank.
- `-n <count>` to cap result count.
## Optional Query Narrowing
Do not overuse tag and heading syntax. Add it only when the user gives an explicit tag/section constraint, or when an initial natural-language search is too broad.
- `#tag` or `tag:name` restricts results to notes with that tag.
- `heading:name` or `h:name` restricts results to notes with a matching indexed heading path.
- Scope is not query syntax; use scope flags.
```bash
talon --agent search "<natural language query> #<tag>"
talon --agent search "<natural language query> heading:<section>"
```
## Ask (CLI Fallback)
Use `ask` sparingly. It is mainly a human CLI convenience for quick vault-grounded answers:
```bash
talon --agent ask "<broad vault question>"
```
For agents, prefer `search` plus `read`: you can plan searches and synthesize better with your own model. `ask` is useful only when you need Talon to do the synthesis in one CLI call.
## Reading
Use `read` after search when you need source text, exact wording, or the body of a result.
You may also read the files directly with your file read tool.
`read` accepts vault paths and Obsidian references:
```bash
talon --agent read "<vault/path.md>"
talon --agent read "[[Note Title]]"
talon --agent read "[[Note Title#Heading]]"
talon --agent read "Note Title#Heading"
```
When a heading is provided, Talon returns only that section. The result includes `section.heading`, `section.fromLine`, `section.toLine`, and `section.obsidianRef`.
Use `--raw` only when frontmatter must be preserved. Use `--from-line N --max-lines M` for line slicing.
## Graph Navigation
Search and read results expose resolved Obsidian graph metadata. Use it instead of scraping markdown links.
- Search hits may include `citations`, `links`, `backlinks`, `tags`, and `aliases`.
- Read results include `links`, `backlinks`, `tags`, and `aliases`.
- Use `related` for ranked graph/provenance exploration from a known note. Related results use links, backlinks, shared sources, common neighbors, communities, and bridge signals; they are not raw traversal order.
```bash
talon --agent related "<vault/path.md>" --direction both --depth 1
talon --agent related "<vault/path.md>" --direction outgoing --depth 2
talon --agent related "<vault/path.md>" --direction backlinks --depth 1
```
## Recall (CLI Use Only)
In CLI contexts, use `recall` when you are about to answer a user and want Talon to supply compact vault context for that user request.
Pass the actual current user request, not a generic meta-prompt about what context might be useful.
```bash
talon --agent recall "<current user request>"
```
Recall returns active notes plus community-diverse graph-ranked linked context when evidence is strong enough.
**Note:** MCP users get automatic recall injection before each turn — no manual call needed.
## Scope Flags
Configured scopes decide which parts of the vault are searched by default. Scopes with `default = false` are excluded entirely unless explicitly included.
- No scope flag: search only default scopes.
- `--scope NAME`: include one additional named scope.
- `--scope-only NAME`: search only the named scope or scopes.
- `--scope-all`: include every configured scope.
Use scope flags when the user explicitly asks for a private/archive/raw area or when a default-scope search misses something you have reason to believe is outside the default pool.
```bash
talon --agent search "<query>" --scope <scope>
talon --agent search "<query>" --scope-only <scope>
talon --agent search "<query>" --scope-all
```
## Other Commands
- `talon --agent sync`: incremental index refresh, stale path cleanup, and pending/changed embeddings. Picks up changed files, deletes, moves, renames, and changed links in edited files.
- `talon --agent sync --fast`: same index refresh and stale path cleanup, with no embedding pass. Use for quick lexical freshness checks.
- `talon --agent sync --force`: incremental index refresh, then rebuild embeddings for every active chunk.
- `talon --agent sync --rebuild`: delete and recreate the SQLite index, then index the vault from scratch. Add global `--fast` for a lexical-only rebuild.
- `talon --agent meta --tag-counts`: inspect tag distribution.
- `talon --agent changes --since 7d`: inspect recent added/modified/deleted notes. `--since` accepts relative durations such as `7d`/`3h`, ISO 8601 timestamps, dates, or epoch milliseconds.
- `talon --agent inspect`: inspect broken links, orphan/unreferenced notes, graph health, and read-only missing-link opportunities.
- `talon --agent inspect graph`: inspect only graph-health and read-only missing-link findings; it does not edit files.
- `talon --agent status`: inspect index readiness.
Note: when MCP is active, the vault syncs in the background - no action needed.
### `--where` Filters (meta and search)
Filter by frontmatter fields or the note's vault path. Operators glue to the key — no spaces required.
| `=` | `status=archived` | Exact match |
| `!=` | `type!=method` | Not equal |
| `<` `<=` `>` `>=` | `score>0.5` | Ordered (dates, numbers) |
| `contains` | `tags contains workflow` | Substring in any value |
| `exists` | `source exists` | Field is present |
| `^=` | `path^=Templates/` | Prefix / starts-with |
| `~=` | `path~=Patients/*` | Glob pattern (full globset syntax) |
Prefix and glob work on any frontmatter field **and** the special `path` key:
```bash
# Show all notes under a directory subtree
talon --agent meta --where 'path^=Projects/' --select path
# Glob: all markdown files in artifacts/
talon --agent meta --where 'path~=artifacts/*.md' --select path
# Prefix on frontmatter field
talon --agent meta --where 'title^=Weekly' --select path,title
# Glob on frontmatter field
talon --agent meta --where 'tags~=workflow*' --select path,tags
```
Glob uses the [`globset`](https://docs.rs/globset) crate: `*` matches any chars (including `/`), `**` matches zero or more directories.
## Result Contract
Search hits with `--agent` include `path`, `title`, `snippet`, and `score`.
To see more metadata, pass `--json` instead:
- `isIndex`: index/overview page signal.
- `citations`: resolved notes from `sources:` frontmatter.
- `links`: outgoing resolved Obsidian links.
- `backlinks`: incoming resolved Obsidian links.
- `tags`: indexed tags.
- `aliases`: indexed aliases.
Read results include `path`, `title`, `content`, `links`, `backlinks`, `tags`, and `aliases`. Heading reads also include `section`.
Related results include `path`, `title`, `relation`, `linkText`, rounded `score`, and compact `reasons`.
Ask results include `answer`, `queries`, and `sources`. Sources use plain vault paths; they are not Obsidian wikilinks.