YAMS User Guide
Command-line interface for content-addressed storage with semantic search.
Quick Start
# Initialize storage (interactive - prompts for grammar downloads)
yams init
# Or auto mode for containers/headless
yams init --auto
# Or specify custom location
export YAMS_STORAGE="$HOME/.local/share/yams"
yams init --non-interactive
# Init also bootstraps a per-project session (scoping + watch) unless
# Enable auto-ingest for an existing project
yams watch
# Add content
yams add ./README.md --tags docs
yams add src/ --recursive --include="*.cpp,*.h" --tags code
echo "note" | yams add - --name "quick-note.txt"
# Search and retrieve
yams search "config file" --limit 5
yams grep "TODO" --include="*.cpp"
yams list --limit 20
yams get <hash> -o ./output.bin
# System status
yams status
yams doctor
Documentation
| Topic |
File |
Description |
| Installation |
installation.md |
Install via Homebrew, Docker, or source |
| CLI Reference |
cli.md |
All commands and options |
| MCP Server |
mcp.md |
Model Context Protocol integration |
| Embeddings |
embeddings.md |
Vector search and model setup |
| Operations |
../admin/operations.md |
Tuning, maintenance, configuration |
Key Commands
| Command |
Description |
yams init |
Initialize storage (interactive or --auto) |
yams add |
Add files/directories (--recursive, --include, --tags) |
yams search |
Hybrid search (keyword + semantic) |
yams grep |
Regex search with semantic suggestions |
yams list |
List documents (--snapshots, --format json) |
yams get |
Retrieve by hash or name |
yams diff |
Compare snapshots (Merkle tree diff) |
yams watch |
Enable auto-ingest for a project session |
yams serve |
Start MCP server (stdio) |
yams doctor |
Diagnose issues |
yams repair |
Fix storage/embeddings |
Build Options (Meson)
| Option |
Default |
Description |
build-cli |
true |
Build CLI binary |
build-mcp-server |
true |
Build MCP server |
build-tests |
false |
Build test suite |
plugin-onnx |
true |
ONNX embedding models |
plugin-symbols |
true |
Tree-sitter symbol extraction |
plugin-s3 |
true |
S3 object storage |
Environment Variables
| Variable |
Description |
YAMS_STORAGE |
Storage root directory (overrides default) |
XDG_DATA_HOME |
Default storage location (~/.local/share/yams) |
XDG_CONFIG_HOME |
Config location (~/.config/yams) |
YAMS_PLUGIN_DIR |
Plugin search directory |
YAMS_DAEMON_SOCKET |
Daemon socket path override |
YAMS_EMBEDDED |
Daemon transport mode: 1/true in-process, 0/false socket, auto probe |
Common Patterns
# JSON output for scripting
yams list --format json | jq '.'
yams search "query" --limit 10 --json
# Per-project storage
YAMS_STORAGE="$PWD/.yams" yams init --non-interactive
YAMS_STORAGE="$PWD/.yams" yams add ./src/
# Auto-ingest for the current project
yams watch --interval 2000
# Batch indexing with tags
yams add src/ --recursive --include="*.cpp,*.hpp,*.h" --tags "code,source"
yams add docs/ --recursive --include="*.md" --tags "docs"
# Snapshot workflow
yams add . --recursive --include="*.cpp,*.h" --snapshot-label "v1.0"
yams list --snapshots
yams diff v1.0 v1.1 --stats
# MCP server for AI assistants
yams serve
Embedding Models
| Model |
Dimensions |
Notes |
all-MiniLM-L6-v2 |
384 |
Recommended: fast, lightweight |
all-mpnet-base-v2 |
768 |
Higher quality, slower |
# Download and configure a model
yams model download all-MiniLM-L6-v2
yams model check
# Set preferred model
yams config set embeddings.preferred_model all-MiniLM-L6-v2
Extract functions, classes, and methods from source code:
# Download grammars
yams config grammar list
yams config grammar download cpp python rust
# Symbols are extracted automatically on add
yams add src/ --recursive --include="*.cpp,*.py,*.rs"
Supported languages (18): C, C++, C#, Dart, Go, Java, JavaScript, Kotlin, P4, Perl, PHP, Python, R, Rust, Solidity, SQL, TypeScript, Zig. Full list: cli.md#symbol-extraction.
Plugins
yams plugin list # List loaded
yams plugin trust add ~/.local/lib/yams/plugins
yams plugin health # Check status
yams doctor plugin onnx # Diagnose
Troubleshooting
yams doctor # Full diagnostics
yams doctor --json # JSON output
yams stats --verbose # Storage statistics
yams repair --all # Fix common issues
yams repair --embeddings # Generate missing embeddings
Links
3f37e8f564