# Knowledge

The knowledge base is three layers deep:

```
Domain Index  →  Knowledge Units  →  Raw Notes (sources)
```

- **Domain Index** — one index per domain; lists all knowledge units in that domain; the entry point.
- **Knowledge Units** — compiled, synthesized notes distilled from raw notes; usually sufficient to answer a question. Each unit contains links to its source raw notes.
- **Raw Notes** — original source notes; follow the source links inside a knowledge unit to read them directly when more detail is needed.

Retrieval path: `list-indexes` → read domain index → read matching knowledge units → follow source links to raw notes → `vaultr search` as last-resort fallback only.

Knowledge notes are auto-generated and are read-only (except for explicit deletes).

## Retrieval Workflow

1. `vaultr knowledge list-indexes --table` — identify relevant domains
2. `vaultr knowledge read <index-path>` — read the domain index to find matching knowledge units
3. `vaultr extract outline <unit-path>` — preview the knowledge unit's structure before reading in full
4. `vaultr extract section <unit-path> "<heading>"` — read only the relevant section if the outline is sufficient to pinpoint it; otherwise `vaultr knowledge read <unit-path>`
5. If more detail is needed: follow the source links inside the knowledge unit; use `vaultr extract outline <source-path>` first, then `vaultr read <source-path>` for full content
6. Last resort only: `vaultr search "X"` — use when source links are absent or the above steps don't cover the question

If the domain is unclear, skip steps 1–2 and go straight to `vaultr knowledge search "X"`.

## Command Reference

### List domain indexes

```bash
vaultr knowledge list-indexes           # all domains with vault path (JSON)
vaultr knowledge list-indexes --table   # table format
```

### List knowledge notes

```bash
vaultr knowledge list --kind knowledge                                          # knowledge notes, newest first
vaultr knowledge list --kind knowledge --latest 7                               # updated in the last 7 days
vaultr knowledge list --kind knowledge --start 2026-01-01 --end 2026-01-31      # date range
vaultr knowledge list --kind knowledge --limit 20                               # capped
```

### Read a knowledge note

```bash
vaultr knowledge read "/_knowledge/summary.md"   # vault-absolute path
vaultr knowledge read summary.md                  # bare filename — most recent match
```

### Search knowledge notes

```bash
vaultr knowledge search "machine learning"         # name + content (default)
vaultr knowledge search topic --field name         # filename only
vaultr knowledge search "key idea" --field content # content only
vaultr knowledge search "project" --limit 10
```

Query syntax: bare words are OR-joined; `"quoted phrase"` matches exactly.

# Regular Notes — CRUD

All note writes (create, modify, delete) must go through the CLI — never touch note files directly.

## List notes

```bash
vaultr list                                          # all notes, sorted by most recently updated
vaultr list /journal                                 # scope to a vault directory
vaultr list --latest 7                               # updated in the last 7 days
vaultr list --start 2026-01-01 --end 2026-01-31      # date range
vaultr list --limit 20                               # cap results
```

## Search notes

```bash
vaultr search "meeting notes"          # search filename + content (default)
vaultr search april --field name       # filename only
vaultr search "TODO" --field content   # content only
vaultr search "project" --limit 10
```

Query syntax: bare words are OR-joined; `"quoted phrase"` matches exactly.

## Read a note

```bash
vaultr read /journal/today.md    # vault-absolute path
vaultr read today.md             # bare filename — resolves to most recently updated match
```

If multiple notes share the same name, use the full vault path to be unambiguous.

## Preview / partial read (save tokens)

Before reading a note in full, use `vaultr extract` to inspect only what you need.

**Decide whether to read the whole note:**
```bash
vaultr extract outline today.md          # heading structure — see if the note is relevant
vaultr extract segment today.md --head 20  # first 20 lines — quick content preview
vaultr extract tag today.md              # front-matter tags only
```

**Read only the part you need:**
```bash
vaultr extract section today.md "Goals"         # extract a named section (case-insensitive)
vaultr extract section today.md "## meeting notes"
vaultr extract segment today.md --start 10 --end 30   # specific line range
vaultr extract segment today.md --tail 15        # last 15 lines
```

**Extract specific content types:**
```bash
vaultr extract code today.md     # all fenced code blocks
vaultr extract list today.md     # all bullet/numbered lists
vaultr extract link today.md     # all links
```

**Recommended workflow for unknown or long notes:**
1. `vaultr extract outline <note>` — scan the structure
2. `vaultr extract section <note> "<heading>"` — read only the relevant section(s)
3. `vaultr read <note>` — fall back to full read only when the above isn't enough

## Create a note

```bash
vaultr create /path/note.md --content "# Title\n\nContent here."
vaultr create /path/note.md --file local.md       # copy from a local file
```

Path rules:
- Must be vault-absolute and start with `/`
- Use a meaningful folder: `/journal/`, `/projects/`, `/research/`, etc.
- Use `.md` extension

## Modify a note

**Overwrite** (replace entire content):
```bash
vaultr create /path/note.md --content "updated content" --force
```

**Append** to the end:
```bash
vaultr append /path/note.md --content "new paragraph"
```

**Prepend** to the top:
```bash
vaultr prepend /path/note.md --content "header line"
```

Read the note first (`vaultr read`) if you need its current content before modifying.

## Delete a note

```bash
vaultr delete /path/note.md
```

Path must be vault-absolute. Use `vaultr resolve <filename>` first if you only know the filename.

# Short Notes

Short notes are quick-capture entries appended to a daily file inside the `_shorts` directory. Use these for fleeting thoughts, quick todos, and daily log entries — not for structured notes with their own files.

## Create a short note

```bash
vaultr short create --content "Quick thought"
```

Content goes to today's daily shorts file automatically — no path needed.

## List short notes

Each daily file is parsed into individual entries; you see one row per note, not one row per day.

```bash
vaultr short list --latest 7                              # entries from the last 7 days
vaultr short list --start 2026-01-01 --end 2026-01-31    # date range
vaultr short list --limit 20                              # cap results
```

## When to use short notes vs regular notes

| Use short notes                 | Use regular notes                    |
| ------------------------------- | ------------------------------------ |
| Quick capture, fleeting thought | Structured content with its own file |
| Daily log entry                 | Journal entry at `/journal/`         |
| Temporary reminder              | Research or reference material       |

---
name: vaultr-notes
description: "Guide for working with Vaultr, an AI-native personal note-taking system. Use this skill whenever the user wants to search, find, read, write, save, create, modify, delete, or capture notes — including journal entries, research notes, quick thoughts, knowledge retrieval, or any note-taking task. Trigger when the user says things like 'save this as a note', 'find my notes about X', 'create a note', 'look up my notes on X', 'read my note about Y', 'delete a note', 'quick note', 'short note', 'what do I know about X', or any variation of managing notes in Vaultr."
---

# Vaultr Notes — Router

## Environment check

```bash
vaultr --help
```

If `vaultr` is not found, inform the user and stop.

---

## Identify intent → load sub-skill

| Scenario          | Trigger signals                                                                                        | Sub-skill       |
| ----------------- | ------------------------------------------------------------------------------------------------------ | --------------- |
| **Regular notes** | create / read / modify / delete / list / search notes; journal entries; research notes; markdown files | @notes-crud.md  |
| **Short notes**   | quick capture, fleeting thought, short note, daily log, "jot down"                                     | @short-notes.md |
| **Knowledge**     | "what do I know about", knowledge base, compiled knowledge, index notes                                | @knowledge.md   |

Load the matching sub-skill. If the request spans multiple scenarios, handle them sequentially.