170 lines
No EOL
5.1 KiB
Markdown
170 lines
No EOL
5.1 KiB
Markdown
# YAMS User Guide
|
|
|
|
Command-line interface for content-addressed storage with semantic search.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 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](./installation.md) | Install via Homebrew, Docker, or source |
|
|
| CLI Reference | [cli.md](./cli.md) | All commands and options |
|
|
| MCP Server | [mcp.md](./mcp.md) | Model Context Protocol integration |
|
|
| Embeddings | [embeddings.md](./embeddings.md) | Vector search and model setup |
|
|
| Tutorials | [tutorials](./tutorials/README.md) | Task-oriented guides |
|
|
| Operations | [../admin/operations.md](../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
|
|
|
|
```bash
|
|
# 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 |
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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](./cli.md#symbol-extraction).
|
|
|
|
## Plugins
|
|
|
|
```bash
|
|
yams plugin list # List loaded
|
|
yams plugin trust add ~/.local/lib/yams/plugins
|
|
yams plugin health # Check status
|
|
yams doctor plugin onnx # Diagnose
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
```bash
|
|
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
|
|
|
|
- **Docs:** [yamsmemory.ai](https://yamsmemory.ai)
|
|
- **GitHub:** [github.com/trvon/yams](https://github.com/trvon/yams)
|
|
- **Discord:** [discord.gg/rTBmRHdTEc](https://discord.gg/rTBmRHdTEc)
|
|
docs/index.md |