Skip to content

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

# 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
Tutorials tutorials/ Task-oriented guides
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 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-pdf false PDF text extraction
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

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/

# 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

Symbol Extraction

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: C, C++, Python, JavaScript, TypeScript, Rust, Go, Java, C#, PHP, Kotlin, Dart, SQL, Solidity

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