Files

---
name: tolvi
description: Read, write, and ask questions of a Tolvi engineering vault. Use when working in a repo with vault/.vault-meta.json, or when the user mentions decisions, sessions, or patterns.
---

# Tolvi

Tolvi is a per-repo engineering knowledge vault: decisions, sessions, and patterns stored as Markdown with YAML frontmatter under `<repo>/vault/`. This skill teaches your coding agent how to read, write, and query a Tolvi vault, and when to use the `tolvi` CLI versus direct file operations. It is the same skill for Claude Code, Codex, Cursor and OpenHands; sections marked Claude Code only describe slash commands and session hooks that the other agents do not have.

When you finish loading this skill, briefly acknowledge it (one sentence) and wait for the user's actual request. Do not auto-scan the vault or auto-invoke any CLI command.

## When to use this skill

**Triggers:**

- Explicit: the user types `/tolvi` in an agent that supports skill slash commands, such as Claude Code or Cursor, or names the Tolvi skill in a request
- Implicit: user asks "what did we decide about X", "what session notes do we have on Y", "write a decision about Z", or references `[[some-slug]]` in a request
- Repo state: cwd or an ancestor contains `vault/.vault-meta.json`

**Anti-triggers:**

- The repo has no `vault/.vault-meta.json` — offer `tolvi init` instead, with confirmation before running
- The user is asking about *code*, not *project knowledge*: use your normal file reading and search tools

## Vault structure

```
<repo>/
└── vault/
    ├── .vault-meta.json      # workspace + embedding model + schema version
    ├── decisions/            # YYYY-MM-DD-<slug>.md
    ├── sessions/             # YYYY-MM-DD.md (one per day; multiple blocks append)
    └── patterns/             # <slug>.md (no date prefix; timeless)
```

One workspace per repo. `.vault-meta.json` is the marker file the CLI uses to discover the vault (walk-up from `$PWD` to filesystem root or `$HOME`).

## Format spec — compact reference

### Frontmatter shape per doc type

**Decision** — required fields:

```yaml
---
tags: [decision]
date: 2026-04-12
repo: my-project
status: active
---
```

Optional decision fields: `ticket`, `user_impact`, `product_area`.

**Session** — required fields:

```yaml
---
tags: [session]
date: 2026-04-12
status: active
---
```

**Pattern** — required fields (no date, no repo; patterns are timeless):

```yaml
---
tags: [pattern]
status: active
---
```

### Slug rules

Slug regex: `^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$`

- Lowercase letters and digits only; hyphens allowed in the middle
- No leading hyphen, no trailing hyphen
- No underscores, no uppercase, no spaces
- Max 80 chars
- Single-character slugs (`a`, `1`) are allowed

Auto-derivation from a title: NFKD ASCII-fold → lowercase → non-alphanumeric runs replaced with `-` → trim leading/trailing `-` → cap at 80 → re-trim. The CLI does this automatically in `tolvi sync`.

### File path layout

- **Decision**: `vault/decisions/<date>-<slug>.md` (date is YYYY-MM-DD)
- **Session**: `vault/sessions/<date>.md` (one file per day; multiple session blocks append to the same file)
- **Pattern**: `vault/patterns/<slug>.md` (no date prefix)

### Status enum (six values)

| Status | When to use |
|---|---|
| `active` | Current, in effect |
| `in-progress` | Decided but implementation in flight |
| `superseded` | Replaced by a newer decision (point to the replacement in the body) |
| `deprecated` | No longer applies; kept for history |
| `draft` | Not finalized; ideas in progress |
| `historical` | Older context; valid but archival |

Search defaults to `active | in-progress | historical`. The other three are filtered out unless the caller passes `--include-status` explicitly.

### Wiki-link syntax

- `[[slug]]` — references a doc by slug in the same vault. Always resolvable to a file when the slug exists.
- `[[repo:slug]]` — cross-vault reference (the format spec supports it; the CLI v1 does not surface it in citations). Do not generate `[[repo:slug]]` citations in v1.

## CLI commands

The `tolvi` binary is the substrate. Shell out to it with your shell tool. If `tolvi` is not in `$PATH`, suggest installation (see Escape hatches below).

### `tolvi ask <query>`

Stream a cited answer to the query. Tokens print to stdout as they arrive; a `Sources` footer prints after the stream completes with verified `[[slug]]` references, file paths, and statuses.

Key flags:

- `--no-stream` — buffer output instead of streaming (use in CI logs or environments that mangle ANSI)
- `--json` — emit structured JSON (`{answer, citations, model, tokens, ...}`) instead of human-readable text; buffered, no streaming
- `--model <name>` — override the configured Anthropic model
- `--include-status <csv>` — override the default status filter (e.g., `--include-status active,superseded`)
- `--exclude-type <csv>` — omit a doc type (e.g., `--exclude-type session` when the vault is too large)
- `--vault <path>` — override walk-up discovery

### `tolvi sync <type> <title>`

`type` is one of `decision | session | pattern`. Writes a new vault doc with auto-derived slug and valid frontmatter. Opens `$EDITOR` for the body by default.

Key flags:

- `--body "..."` — pass the body inline; skips the `$EDITOR` flow
- `--no-edit` — skip `$EDITOR`; writes a skeleton-only file unless `--body` is given
- `--slug <name>` — override the auto-derived slug
- `--status <value>` — frontmatter status (default: `active`)
- `--print-path` — output only the resulting path to stdout (useful for piping)
- `--vault <path>` — override walk-up discovery

**Session same-day behavior:** if `vault/sessions/<date>.md` already exists, `tolvi sync session` appends a new session block to the existing file rather than refusing or overwriting. The new block uses an HH:MM-prefixed `## [HH:MM] Session — ...` heading.

### `tolvi recall`

Emit a session-resumption summary — recent sessions and decisions — without making any API call. Pure file-read; fast enough for use in Claude Code hooks (< 500 ms budget). Patterns are excluded by default because they are timeless reference, not session-resumption context.

Key flags:

- `--format human|hook-json` — output format:
  - `human` (default): plain-text `RECALL SUMMARY` block matching the Claude Code `/tolvi-recall` command's output
  - `hook-json` (Claude Code only): Claude Code `SessionStart` hook blob (`{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "..."}}`)
- `--session-count <n>` — number of recent sessions to surface (default: 3)
- `--decision-count <n>` — max recent active decisions to surface (default: 10)
- `--max-bytes <n>` — hard cap on the `additionalContext` string in hook-json output; content is truncated with a notice when the vault is large (default: 8000)
- `--include-patterns` — also surface pattern names (off by default)
- `--vault <path>` — override walk-up discovery

**Config-file defaults** (`~/.config/tolvi/config.yaml`):

```yaml
recall:
  session_count: 3
  decision_count: 10
  max_bytes: 8000
  include_patterns: false
```

Flag values override config-file values. Config-file values override compiled-in defaults.

**Used by session hooks (Claude Code only):** `skills/tolvi/hooks/tolvi-recall` calls `tolvi recall --format hook-json` on every Claude Code `SessionStart`. Install with `bash install.sh --with-hooks`.

### `tolvi init`

One-time provision: creates `vault/decisions/`, `vault/sessions/`, `vault/patterns/`, and `vault/.vault-meta.json`. Refuses if the vault already exists. Workspace name derived from `git remote get-url origin` parse, falling back to `basename $PWD`. Override with `--workspace <name>`.

## Synthesizing a working session

The highest-value thing this skill does is turn a finished working session into durable, schema-conformant vault docs — decisions, patterns, and a session log — without the user hand-writing them. This is distinct from `tolvi sync <type> <title>`, which captures a single note you already have in mind. Synthesis reconstructs the whole session and writes the records for it. Run it at the end of a meaningful session (or when the user asks to "sync the session").

### What to capture — the authority gate

Capture what a qualified actor **tried or considered inside this working session**, including reasoned rejections ("we tried X, Y broke, so we shipped Z"). A road not taken *for a stated reason* is some of the most valuable content — it stops the next person re-walking a dead end. Do **not** import unqualified chatter from outside the session (a passing suggestion that was never weighed is noise). The discriminator is not whether an idea was acted on; it is whether it entered the work through the session.

### Step 1 — Reconstruct the session

From the conversation, identify:

- **Files changed** — created, edited, or deleted
- **Tickets** — any issue IDs referenced or progressed
- **Decisions made** — non-obvious architectural, product, or implementation choices
- **Patterns observed** — reusable approaches that emerged
- **Left open** — anything unfinished, blocked, or deferred

### Step 2 — Discover the vault

Walk up from `$PWD` to the first `vault/.vault-meta.json` (the same discovery the CLI uses). Prefer `tolvi sync`/`tolvi recall`, which do this automatically; pass `--vault <path>` to override. Everything below writes into that single repo's `vault/`.

### Step 3 — Write the session log

Append to `vault/sessions/<date>.md` (one file per day; multiple blocks append). Frontmatter: `tags: [session]`, `date`, `status: active`. Block shape:

```markdown
## [HH:MM] Session — <one-line summary>

**Tickets:** <list or none>

### What happened
<3–5 concrete bullets>

### Files touched
<files with a one-line note each>

### Left open
<list or none>
```

### Step 4 — Write decisions (if any)

One file per decision: `vault/decisions/<date>-<slug>.md`. Frontmatter: `tags: [decision]`, `date`, `repo`, `status` (optional: `ticket`, `user_impact`, `product_area`). Use the layered-altitude body so a PM and an engineer each get what they need:

```markdown
# <Decision title>
**Date:** <date>
**Repo:** <repo>

## Why
<1–2 sentences, business-readable: the problem and who benefits>

## How
<variable depth — scales with technical weight: mechanism, contracts, rejected alternatives and *why* each was rejected, edge cases, snippets for load-bearing logic>

## Outcome
<1 sentence: what is now true about the system that was not before>
```

`## Why` and `## Outcome` stay short regardless of complexity; depth scales only at `## How`.

### Step 5 — Write patterns (if any)

`vault/patterns/<slug>.md` (no date prefix; patterns are timeless). Frontmatter: `tags: [pattern]`, `status: active`. If the file exists, append a new example rather than overwriting.

### Step 6 — Cross-link

Link related docs with `[[slug]]` within the same vault (the `[[repo:slug]]` cross-vault form is not surfaced in v1). Add a `See also: [[...]]` line to the session block for any decisions or patterns written.

### Writing mechanics

Prefer `tolvi sync <type> <title> --body "..."` per doc: it does atomic write, frontmatter validation, slug derivation, and same-day session append for you. Write the markdown file directly only when the CLI is unavailable or the user asks; if you do, validate the frontmatter against the rules above before writing.

## Behavioral rules

These are *preferences*, not hard gates. Use judgment.

### Reading a specific vault doc → read the file

For "show me the postgres decision" or any exact-doc request, read the file directly. Direct read is faster than shelling out for one file.

### Searching the vault → prefer `tolvi ask`

For semantic queries ("what did we decide about X", "any patterns for Y"), shell out to `tolvi ask`. The CLI handles CAG (whole vault → Anthropic context) plus citation verification plus streaming. Don't reimplement with `grep` unless the CLI is unavailable.

### Writing a new doc → prefer `tolvi sync`

The CLI handles atomic write, frontmatter validation against the embedded JSON Schema, slug auto-generation, and session same-day append. Writing the markdown file directly is acceptable when:

- The CLI is missing from `$PATH`
- The user explicitly asks for a direct file write
- You're iterating on a draft the user has not yet committed to capturing

When writing the file directly, validate the frontmatter mentally against the rules above before writing. Frontmatter-validation failures cause silent vault corruption that's annoying to debug.

### Citing vault content

When summarizing or quoting vault content in a response, cite with `[[slug]]`. Use exact slugs that exist in the vault — verify by reading the matching file before citing. Don't invent slugs.

### Pre-commit vault sync (Claude Code only)

Before every `git commit` in a Tolvi-vaulted repo, the `tolvi-sync` Claude Code `PreToolUse` hook fires. It auto-stages any modified `vault/` files so they land in the commit, then asks `tolvi roots --session-note` where today's note belongs and checks whether it is there. If it is missing the hook says so and **allows the commit anyway**: a missed vault entry is recoverable, a blocked commit is not acceptable friction, and a hook that fails closed turns any bug in it into an inability to commit. This happens automatically when hooks are installed (`bash install.sh --with-hooks`).

## Escape hatches

### `tolvi` binary not in `$PATH`

Suggest installation:

```bash
go install github.com/tolvi-labs/tolvi/cli/cmd/tolvi@latest
```

Or download from <https://github.com/tolvi-labs/tolvi/releases>. Until the user installs it, fall back to direct file operations with manual frontmatter validation.

### No vault in repo

Offer to run `tolvi init`. If the user proposes a workspace name, pass it via `--workspace <name>`. Confirm before running — don't auto-init silently.

### `tolvi ask` reports vault too large

The CLI errors at approximately 180,000 estimated tokens. Suggest one of:

- `--exclude-type session` — drops noisy session logs from the prompt
- `--include-status active` — already the default; mention only if the user widened it
- Migrate to the server arm — a separate `tolvi-server` deployment outside the scope of this skill

### No `ANTHROPIC_API_KEY`

`tolvi ask` errors with a clear pointer to `~/.config/tolvi/config.yaml` and the `ANTHROPIC_API_KEY` environment variable. Surface that message verbatim to the user rather than paraphrasing.

### Vault has invalid frontmatter in a file

`tolvi ask` prints a warning on stderr and skips the invalid file. Suggest the user inspect the file; offer to help fix the frontmatter against the rules above. The vault remains queryable for the other files.