@younndai/lyt-vault Part of the Lyt (Link Your Think™) toolchain — federated markdown vaults you own, made legible to AI.
Website · Repository · Apache 2.0 · Trademark Policy · Contributing
[](https://www.npmjs.com/package/@younndai/lyt-vault)
[](./LICENSE)
[](https://github.com/YounndAI/lyt#status)
> ⚠️ **Public alpha — under active testing.** Lyt works and we use it daily, but surfaces change between releases and docs are still growing. The normal install follows `latest`; `@alpha` is the opt-in preview channel. Your vaults are plain markdown in plain git repos — your data is never locked in, and Lyt never phones home.
## What is this?
`@younndai/lyt-vault` is the **vault primitive** of [Lyt](https://github.com/YounndAI/lyt) — the package that turns a folder of plain markdown notes into a **local-first, Git-native knowledge vault** with structured metadata, fast full-text search, and an AI-readable declaration file. A Lyt vault is editor-neutral markdown-in-Git: your notes stay plain `.md` files in a plain git repo, while a `.lyt/` area carries the [YON](https://yon.younndai.com)-structured vault declaration and a regenerable libSQL index. Obsidian users can explicitly add its scaffold with `lyt vault init --template obsidian-default`.
Lyt is **AI-first by design** — a vault is as legible to an AI agent as it is to you. Capture a note and an agent can find it by full-text search seconds later; every vault speaks YON, so agents read structure directly instead of scraping prose. This package implements the verbs that create, adopt, inspect, search, and maintain individual vaults — plus the shared `help`, `doctor`, and `pattern` command groups.
You usually do not install this package directly — install [`@younndai/lyt`](https://www.npmjs.com/package/@younndai/lyt) for the unified `lyt` binary.
## Install (standalone)
```bash
npm install -g @younndai/lyt-vault
```
This exposes a `lyt-vault` binary for the vault-owned verb groups. Install
`@younndai/lyt` for the unified `lyt` binary used in the examples below,
including `capture`, `search`, and `reindex`.
## Unified CLI examples
```bash
# Create or adopt a vault
lyt vault init / # create-if-missing; destination is inherited,
# overridden with --target, or explicitly --local
lyt vault adopt # bring an existing markdown folder under Lyt
lyt vault list [--json] # every registered vault (computed {mesh}/{vault} names)
lyt vault info [--json] # status, mesh, writability, origin coordinate
lyt alias # pod-local name → vault rid (survives rename + move)
# Capture and find knowledge
lyt capture "" [--dir ] # save a Figment (markdown note) with frontmatter;
# --dir chooses where it lands, topic picked interactively
lyt search "" [--vault ] [--mesh ] [--limit ] [--meaning-limit ]
[--fields ] [--no-semantic] [--json]
# labelled direct matches + metadata-only meaning candidates
lyt reindex [--all|--mesh |--vault ]
# rebuild the libSQL search caches from the markdown SoT
lyt sync --check --vault / --json
# exact one-vault, zero-mutation inspection
# Your Pod (the per-user view across every mesh you participate in)
lyt federation init [--public|--private] # forge {handle}/lyt-pod + the pod.yon manifest
lyt federation list [--json] # cached pod manifest, deterministic ordering
# Identity, machine roles, provenance
lyt identity show|refresh # GitHub-authoritative identity, cached locally
lyt machine status [--json] # roles (client / automator-runner / …) + region
lyt provenance trace # follow the @STAMP provenance chain
# Health and help
lyt doctor [--json|--full] # git/gh/node/npm checks, registry integrity, self-heal hints
lyt help [] # getting-started, mesh, agents, patterns, troubleshooting…
lyt pattern list|run|fork|… # the bundled pattern runtime (1 bundled: knowledge-capture)
```
Mesh names are independent from GitHub accounts and organizations. A new vault
snapshots its mesh destination unless `--target` or `--local` overrides it.
Creation never publishes; Receipt V1 reports terminal status, effective
destination, checkpoint/mutation evidence, and exact next-sync evidence. Read
policy source afterward through read-only vault/mesh info.
The full v1 verb set also includes `vault clone|forget|disconnect|delete|add-edge|verify|regen-context`, the registry verbs, audit export, and friction tracking. Run `lyt help commands` for the complete list.
## Search
`lyt search` runs a tiered cascade — arc membership, lane membership, full-text (FTS5/BM25), then one-hop mesh edges — with an **optional on-device semantic layer** that can surface notes keyword matching misses (different words, same meaning). The compatibility `results` array preserves the settled rank, while human and machine receipts separate rows into **Direct text matches** and metadata-only **Meaning-based candidates**. Defaults are 20 direct results plus up to 10 additional meaning candidates (30 maximum); `--limit` and `--meaning-limit` control those allowances independently. Every row carries additive `foundBy` provenance, and `--fields ` requests a bounded extra frontmatter projection.
- Semantic search is **on by default when the model is available**, and degrades silently to the lexical cascade when it isn't — no error, no cloud call, byte-identical to `--no-semantic`.
- Meaning candidates are bounded similarity suggestions, not confirmed matches. They are not filtered by a calibrated absolute score threshold; the consuming agent decides whether they are useful for the current question.
- The one-time local model download is **handler-gated**: `lyt reindex` on an interactive terminal prompts before fetching; non-interactive / scripted / MCP runs never auto-download. The model caches under `~/lyt/.embeddings-cache/`, never inside a vault.
- Embeddings run **locally on CPU** — there is no remote inference and `fastembed` is an `optionalDependency`, so install succeeds even where its native runtime can't build.
- Turn fusion off with `lyt search --no-semantic`, or disable it globally via `LYT_EMBEDDINGS=0`.
## Metadata & frontmatter
Every note carries an 8-field frontmatter contract — `title`, `created`, `modified`, `tags`, `topic`, `purpose`, `mesh-visibility`, `weight`. Lyt keeps it correct at rest, sets it at capture, and heals legacy files without touching your prose. The `backfill` and `reconcile` verbs below ship in the unified [`@younndai/lyt`](https://www.npmjs.com/package/@younndai/lyt) binary (they compose the automation runner, which this package deliberately does not depend on).
- **`lyt vault files [--path ]`** inventories every Markdown file and explains whether policy includes it, whether it is indexed, whether it needs missing frontmatter, or whether a stale cache row needs removal. A root `.lytignore` is versioned policy; it supports `#`, `!`, `*`, `**`, `?`, and `/`, while `.lyt`, `.obsidian`, and `.git` always remain excluded.
- **`lyt vault backfill `** is a read-only sealed preview by default. It lists exactly which missing fields would be added — title, genuine `created`/`modified` dates (from git history, falling back to file mtime), keyword `tags`, `topic`, and defaults — without moving files or changing authored values. Apply that exact preview with `--apply --receipt `; non-interactive apply also requires `--yes`. The deprecated `--dry-run` alias warns, and preview-time `--push` warns that it binds intent without changing anything.
- **`lyt vault reconcile `** uses the same preview/apply rail while also finding present-but-unindexed files and stale FTS/dense rows. Receipts expire after 30 minutes, are single-use, and refuse drift before writing; failures distinguish refusal-before-write from partial mutation. A subtree receipt names its candidates separately from the vault-wide derived-cache rebuild. `--push` binds both preview and apply to commit-and-push instead of the default local commit. Direct `lyt automator run metadata-filler` is refused so there is only one broad-write rail.
- **Tags need no model** — keyword extraction runs on any vault, including a freshly imported one. When a local embedding model is present, `topic:` is enriched too: capture _suggests_ one for you to confirm (never auto-selected), and backfill assigns a confident match from your vault's existing labels, leaving it blank when unsure — ranked against your current on-disk labels and computed on-device. With no model, tags still fill and topic stays blank.
- **Your writing is never overwritten** — `purpose` is left blank and flagged rather than guessed, authored values are preserved byte-for-byte, and machine-filled field provenance is recorded in the ledger. Nothing is ever sent off your machine.
- **`lyt doctor`** counts notes with missing or invalid frontmatter (`--full` scans every vault; the default samples).
## Key features
- **Markdown is the source of truth.** The libSQL index is a regenerable cache — delete it and `lyt reindex` restores it from your notes. No black-box database ever owns your knowledge.
- **Search agents can use** — `lyt search --json` reports `lexicalLimit`, `meaningLimit`, and `maxResults`, preserves the compatibility-ranked `results`, separates direct matches from caveated meaning candidates, and returns bounded metadata plus `foundBy` provenance; the same contract backs the agent-harness skills and MCP server.
- **YON-structured declarations** — `.lyt/vault.yon` is the machine-readable source of truth for the vault's mesh shape; any AI agent reads it directly.
- **Self-healing** — corrupt index files are quarantined and rebuilt; `lyt doctor` and `lyt repair` diagnose and fix registry drift.
- **Never phones home** — zero passive telemetry; every network operation is user-initiated and inspectable.
## Programmatic use
```ts
import {
applyOperation,
buildVaultSubcommand,
buildRegistrySubcommand,
buildHelpCommand,
buildDoctorCommand,
buildPatternCommand,
} from "@younndai/lyt-vault";
```
The package also exports the small, caller-supplied `afterOperation` and
`doctorChecks` lifecycle hooks. Lyt does not discover, persist, authorize, or
invoke external layers; the embedding caller owns hook lifetime and policy.
The [`@younndai/lyt`](https://www.npmjs.com/package/@younndai/lyt) meta package
composes these factories; you can do the same in custom CLI builds.
## The Lyt toolchain
| Package | Role |
| --------------------------------------------------------------------------------------- | ------------------------------------------------- |
| [`@younndai/lyt`](https://github.com/YounndAI/lyt/tree/main/packages/lyt) | The unified `lyt` CLI (meta package) |
| [`@younndai/lyt-vault`](https://github.com/YounndAI/lyt/tree/main/packages/lyt-vault) | **This package** — the vault primitive |
| [`@younndai/lyt-mesh`](https://github.com/YounndAI/lyt/tree/main/packages/lyt-mesh) | The mesh layer — multi-vault operations |
| [`@younndai/lyt-skills`](https://github.com/YounndAI/lyt/tree/main/packages/lyt-skills) | Agent-harness skills (Claude Code, Codex, agents) |
| [`@younndai/lyt-mcp`](https://github.com/YounndAI/lyt/tree/main/packages/lyt-mcp) | The MCP server |
| [`@younndai/lyt-runner`](https://github.com/YounndAI/lyt/tree/main/packages/lyt-runner) | The YON automation runner |
| [`@younndai/lyt-llm`](https://github.com/YounndAI/lyt/tree/main/packages/lyt-llm) | The LLM gateway |
---
## About YounndAI
**YounndAI™ — You and AI, unified.** (pronounced _"yoon-dye"_)
A philosophy of intelligence: building with intention, so humans and machines
think together without losing what makes either whole.
## License & Attribution
Apache-2.0. © 2026 MARLINK TRADING SRL (YounndAI). See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE).
"Lyt" and "YounndAI" are trademarks of MARLINK TRADING SRL — see [`TRADEMARK.md`](https://github.com/YounndAI/lyt/blob/main/TRADEMARK.md).
Created by [Alexandru Mareș](https://allemaar.com).
Website: [linkyourthink.com](https://linkyourthink.com)
Structure before scale. Harmony above all.
---
| | |
| ------------- | ---------------------------------------------------------------------------------------- |
| **Project** | [Lyt — Link Your Think](https://linkyourthink.com) |
| **Author** | [Alexandru Mareș](https://allemaar.com) |
| **Company** | [MARLINK TRADING SRL](https://younndai.com) · YounndAI™ |
| **License** | [Apache 2.0](./LICENSE) — © 2026 MARLINK TRADING SRL |
| **Trademark** | [YounndAI™ Trademark Guidelines](https://github.com/YounndAI/lyt/blob/main/TRADEMARK.md) |
