Docs
Everything you need to drive dig — the first run, every command, the policy file, and how any agent plugs in.
Quickstart
Index a directory, search it, reorganize by policy, and step back — all reversible.
Let your agent set it up
dig is built to be agent-operated. Once your agent has the dig skill, you don't run the commands — you ask. The skill is dig's canonical instruction set; it teaches the agent the whole surface and the safety rules, so it can do the setup for you, reversibly.
1 · Install the skill
The Claude Code and Codex plugins bundle the dig skill — one command installs the skill and the dig mcp server. Any other agent can read the portable skill at skills/dig/SKILL.md, or register the dig mcp server for the same tools.
2 · Ask it to set up dig
With the skill loaded, your agent knows the whole surface. Point it at a directory and it will:
- detect dig and install the CLI if it's missing
- dig init a knowledge base on the directory you point at
- draft and validate a .dig/policy.toml from your conventions
- scan, preview org --dry-run, apply, and reconcile drift
- keep every change reversible with dig undo
- “Set up dig on ~/Documents and file invoices under finance/{year}.”
- “Index my notes, make them searchable, and collapse duplicates.”
- “Remember this session so you can recall it next time.”
Command reference
Read commands (find, export, drift, log) support --json for other harnesses. Mutating commands (org, dedup, reconcile, merge, undo) journal every change.
| Command | What it does |
|---|---|
| dig init <root> | Create a knowledge base at a directory. Writes a per-KB .dig/ directory (store, index, config). |
| dig scan | Index files into the content-addressed store. --dry-run previews. Rebuilds the search index; queues vectors when retrieval is on. |
| dig find <query> | Search the KB, ranked. --mode fts|vector|hybrid (default fts, or the policy mode); --json; --limit. |
| dig embed | Drain the semantic-index backlog. Resumable, per-file commits. Needs a [retrieval] policy. |
| dig export | Emit a reproducible, manifest-pinned dataset. --at <manifest> pins a point in time; --filter by label/path/date. JSONL with provenance. |
| dig org | Apply organization policy (move/rename/label). --dry-run previews the full plan; conflicts are reported, never forced. |
| dig dedup | Collapse duplicates per policy. --dry-run previews. Never deletes the last copy; ties escalate. |
| dig drift | Report divergence from policy + external edits. --json. Surfaces misfiled/misnamed/duplicated/unsorted/pinned. |
| dig reconcile | Converge the KB to policy, one-shot. Auto where rules allow; human moves are pinned and escalated, never overwritten. |
| dig watch | Run continuously: observe, reconcile, escalate. --interval. Drains the semantic backlog per tick. Ctrl-C is a clean stop. |
| dig work <create|list|abort> | Open an isolated work view. Worktree-like; disjoint changesets merge back automatically. |
| dig merge <name> | Merge a work view back. Auto-resolves compatible ops; conflicts escalate surgically. |
| dig policy validate | Lint the policy file. Explains rule matches; unknown keys and path-escapes fail loudly. |
| dig log | Browse change history. --json. Newest first. |
| dig undo | Revert the last changeset. Disk mutations (org/dedup) are reversed; undoing a scan only rewinds history. |
Policy reference
The policy lives at .dig/policy.toml and travels with the KB. Validation is strict — unknown keys and path escapes fail loudly.
[[rule]]
Map matching files to a target folder, name, and labels. At least one of into/rename/label is required.
- name
- Unique rule name.
- match
- Conditions (all must hold): ext, mime, path glob, content_matches regex, size/date.
- into
- Target directory template, KB-root-relative. Vars: {year} {month} {day} {name} {ext}.
- rename
- Target filename template.
- label
- Labels to apply (accumulate across rules).
- autonomy
- "" | "auto" | "propose" — in watch, only "auto" rules act unattended.
[dedup]
Configure duplicate collapsing.
- strategy
- keep-oldest | keep-newest.
- on_conflict
- escalate (default) — never silently delete.
[retrieval]
Opt-in semantic retrieval. Off by default — find stays deterministic FTS.
- mode
- off (default) | hybrid | vector.
- base_url
- Any OpenAI-compatible /embeddings endpoint.
- model
- Embedding model name.
- doc_prefix / query_prefix
- Model task prefixes (model-specific, optional).
- api_key_env
- Env var holding the bearer token — keys never live in the file.
- rrf_k / chunk_size / …
- Tuning knobs (0 = default): rrf_k (60), candidate_factor (4), chunk_size (1000), chunk_overlap (200). Changing chunk size/overlap re-embeds the KB.
Integrate
Drive dig from any agent, app, or script — over MCP, the typed SDKs on a local daemon, or the CLI directly. One surface, three doors.
Any agent over MCP
Register the dig mcp server and your agent gets find, recall, retain, drift, log, export, org, reconcile, and undo as tools.
Vercel AI SDK
Expose dig as AI SDK tools so the model searches the knowledge base and remembers across sessions, locally.
TypeScript & Python SDKs
Dependency-light clients over the local dig serve daemon — the same surface, including recall and retain memory.
import { DigClient } from "@vllnt/dig";
const dig = new DigClient();
const hits = await dig.find("invoice acme 2024", { mode: "hybrid" });
const pack = await dig.recall("billing decision", { budget: 1000 });from dig_client import DigClient
dig = DigClient()
hits = dig.find("invoice acme 2024", mode="hybrid")
pack = dig.recall("billing decision", budget=1000)