YAMS — Yet Another Memory System

<p align="center">
<h1 align="center">YAMS — Yet Another Memory System</h1>
<h6 align="center">Persistent memory for LLMs and apps. Content-addressed storage with dedupe, compression, full-text and vector search.</h6>
</p>
<p align="center">
<img alt="license" src="https://img.shields.io/github/license/trvon/yams?style=flat-square">
<img alt="language" src="https://img.shields.io/github/languages/top/trvon/yams?style=flat-square">
<img alt="github builds" src="https://img.shields.io/github/actions/workflow/status/trvon/yams/release.yml">
<img alt="last commit" src="https://img.shields.io/github/last-commit/trvon/yams?style=flat-square">
</p>

> [!WARNING]
> **Experimental — not production ready.** Expect bugs and breaking changes until 1.0.

## Features

- SHA-256 content-addressed storage with block-level dedupe (Rabin chunking)
- Full-text search (SQLite FTS5) + semantic vector search (embeddings)
- Tree-sitter symbol extraction for 18 languages ([list](docs/user_guide/cli.md#symbol-extraction))
- Snapshot management with Merkle tree diffs and rename detection
- WAL-backed durability, high-throughput I/O, thread-safe
- CLI, MCP server, and C-ABI plugins (ONNX embeddings, S3 storage, PDF via ZYP)
- Interactive relevance tuning: [`yams tune`](docs/guides/interactive-tuning.md)

## Documentation

| Topic                | Link                                                                |
|----------------------|---------------------------------------------------------------------|
| Install              | [docs/user_guide/installation.md](docs/user_guide/installation.md)  |
| CLI reference        | [docs/user_guide/cli.md](docs/user_guide/cli.md)                    |
| MCP server           | [docs/user_guide/mcp.md](docs/user_guide/mcp.md)                    |
| Embeddings           | [docs/user_guide/embeddings.md](docs/user_guide/embeddings.md)      |
| Plugins              | [docs/PLUGINS.md](docs/PLUGINS.md)                                  |
| Build from source    | [docs/BUILD.md](docs/BUILD.md)                                      |
| Architecture         | [docs/architecture/](docs/architecture/)                            |
| Benchmarks           | [docs/benchmarks/README.md](docs/benchmarks/README.md)              |
| Changelog            | [docs/changelogs/](docs/changelogs/)                                |
| Roadmap              | [docs/roadmap.md](docs/roadmap.md)                                  |

## Links

- SourceHut: https://sr.ht/~trvon/yams/
- GitHub mirror: https://github.com/trvon/yams
- Docs site: https://yamsmemory.ai
- Discord: https://discord.gg/rTBmRHdTEc
- License: GPL-3.0-or-later

## Install

Supported: Linux x86_64/ARM64, macOS x86_64/ARM64, Windows x86_64.

```bash
# macOS
brew install trvon/yams/yams

# Docker
docker pull ghcr.io/trvon/yams:latest

# Debian/Ubuntu, Fedora/RHEL, Windows: see installation guide
```

Full install matrix and package repos: [docs/user_guide/installation.md](docs/user_guide/installation.md).

### Build from source

```bash
./setup.sh Release          # Linux/macOS (auto-detects toolchain, runs Conan + Meson)
meson compile -C build/release
```

```pwsh
./setup.ps1 Release         # Windows
meson compile -C build/release
```

Requires a C++20 toolchain (GCC 13+, Clang 16+, or MSVC 2022+ recommended), Meson, Ninja, CMake, pkg-config, and Conan. See [docs/BUILD.md](docs/BUILD.md).

## Quick Start

```bash
yams init                                # interactive; use --auto for headless
yams add ./README.md --tags docs
yams add src/ --recursive --include="*.cpp,*.h" --tags code

yams search "config file" --limit 5
yams grep "TODO" --include="*.cpp"

yams list --limit 20
yams get <hash> -o ./output.bin
```

Shell completions: `yams completion bash|zsh|fish|powershell`. Install instructions: [docs/user_guide/cli.md#cmd-completion](docs/user_guide/cli.md#cmd-completion).

## MCP Server

YAMS ships an MCP server over stdio (JSON-RPC) for AI assistants.

```bash
yams serve
```

```json
{
  "mcpServers": {
    "yams": { "command": "yams", "args": ["serve"] }
  }
}
```

Tool reference and Claude Desktop setup: [docs/user_guide/mcp.md](docs/user_guide/mcp.md).

## Plugins

```bash
yams plugin list                                  # loaded plugins
yams plugin trust add ~/.local/lib/yams/plugins   # trust a directory
yams plugin health                                # status
yams doctor plugin onnx                           # diagnose
```

Plugin architecture, trust model, and bundled plugins (ONNX, S3, ZYP, GLiNER, symbol extractor): [docs/PLUGINS.md](docs/PLUGINS.md).

### GPU acceleration (ONNX)

| Platform | Provider   | Hardware                                    |
|----------|------------|---------------------------------------------|
| macOS    | CoreML     | Apple Silicon Neural Engine + GPU           |
| Linux    | CUDA       | NVIDIA GPUs                                 |
| Linux    | MIGraphX   | AMD GPUs (ROCm)                             |
| Windows  | DirectML   | Any DirectX 12 GPU (NVIDIA, AMD, Intel)     |

Auto-detected at build. Override with `YAMS_ONNX_GPU=auto|cuda|coreml|directml|migraphx|none`. Details: [plugins/onnx/README.md](plugins/onnx/README.md).

Recommended model: `all-MiniLM-L6-v2` (384-dim).

## Troubleshooting

```bash
yams doctor              # full diagnostics
yams stats --verbose     # storage statistics
yams repair --all        # repair common issues
```

Build issues: [docs/BUILD.md](docs/BUILD.md). Empty `yams plugin list`? Add a trust path: `yams plugin trust add ~/.local/lib/yams/plugins`.

## Cite

```bibtex
@misc{yams,
  author = {Trevon Williams},
  title = {YAMS: Content-addressable storage with semantic search},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/trvon/yams}
}
```