yams

yams

Content addressable storage with excellent search

Stars: 347

Visit
 screenshot

YAMS (Yet Another Memory System) is a persistent memory system designed for Large Language Models (LLMs) and applications. It provides content-addressed storage with features such as deduplication, compression, full-text search, and vector search. The system is built with SHA-256 content-addressed store, block-level deduplication, full-text search using SQLite FTS5, semantic search with embeddings, WAL-backed durability, high-throughput I/O, and thread-safe operations. YAMS supports Linux x86_64/ARM64 and macOS x86_64/ARM64 platforms. It is recommended to build using Conan for managing dependencies and ensuring proper installation. Users can interact with YAMS through a command-line interface for tasks like initialization, adding content, searching, and retrieving data. Additionally, YAMS provides LLM-friendly patterns for caching web content, storing code diffs, and integrating with other systems through an API in C++. Troubleshooting tips include creating a default Conan profile and handling PDF support issues during the build process. The project is licensed under Apache-2.0.

README:

YAMS — Yet Another Memory System

Persistent memory for LLMs and apps. Content‑addressed storage with dedupe, compression, full‑text and vector search.

license language github builds last commit

Features

  • SHA‑256 content‑addressed storage
  • Block‑level dedupe (Rabin)
  • Full‑text search (SQLite FTS5) + semantic search (embeddings)
  • WAL‑backed durability, high‑throughput I/O, thread‑safe
  • Portable CLI and MCP server
  • Extensible with Plugin Support

Links

Install

Supported platforms: Linux x86_64/ARM64, macOS x86_64/ARM64

Build with Meson (Recommended)

# 1. Resolve dependencies
conan install . -of build/release -s build_type=Release -b missing

# 2. Configure
meson setup build/release \
  --prefix /usr/local \
  --native-file build/release/build-release/conan/conan_meson_native.ini \
  --buildtype=release

# 3. Build
meson compile -C build/release

# 4. (Optional) Install
sudo meson install -C build/release

Dependencies quick ref:

  • Linux: libssl-dev sqlite3 libsqlite3-dev protobuf-compiler libncurses-dev ninja-build cmake
  • macOS (Homebrew): openssl@3 protobuf sqlite3 ncurses ninja cmake
    • Export OPENSSL_ROOT_DIR=$(brew --prefix openssl@3) if CMake cannot locate OpenSSL

Common build options (Meson): -Dbuild-tests=true|false, -Denable-tui=true|false, -Denable-onnx=enabled|disabled|auto, -Dplugin-onnx=true|false, -Dyams-version=.... Fast iteration: set FAST_MODE=1 when running meson setup --reconfigure to disable ONNX & tests in CI (SourceHut) or locally. Media metadata: install mediainfo + dev package (e.g. libmediainfo-dev) or FFmpeg (ffprobe) to enable richer video parsing.

Further build documentation:

  • GCC specifics / quick reference: docs/BUILD-GCC.md
  • Developer build system & internal ONNX Runtime path: docs/developer/build_system.md

ONNX embeddings (experimental):

  • The ONNX plugin is experimental and may not work as intended.
  • Conan: default profiles enable yams/*:enable_onnx=True. With custom profiles, pass -o yams/*:enable_onnx=True to conan install.
  • Plain CMake: configure with -DYAMS_ENABLE_ONNX=ON and ensure onnxruntime is discoverable (e.g., via CMAKE_PREFIX_PATH).
  • Verify configure logs include: ONNX Runtime found - enabling local embedding generation (and not disabled).
  • Internal newer ORT (GenAI headers) path: run Conan with -o yams/*:use_conan_onnx=False and configure with -DYAMS_BUILD_INTERNAL_ONNXRUNTIME=ON (see developer build doc for details).

Note: Plain CMake without Conan may miss dependencies; prefer Conan builds.

Quick Start

export YAMS_STORAGE="$HOME/.local/share/yams"
yams init --non-interactive

# add
echo hello | yams add - --tags demo

# search
yams search hello --limit 5

# get
yams list --format minimal --limit 1 

CLI Cheat Sheet

# set storage per-run
yams --data-dir /tmp/yams add -

# list (minimal for pipes)
yams list --format minimal

# fuzzy search
yams search database --fuzzy --similarity 0.8

# delete preview
yams delete --pattern "*.log" --dry-run

Plugins (ONNX Provider)

YAMS loads optional plugins via a stable C‑ABI host with a simple trust policy.

  • Trust file: ~/.config/yams/plugins_trust.txt (one absolute path per line; default deny)
  • Discovery order:
    • YAMS_PLUGIN_DIR (exclusive override)
    • $HOME/.local/lib/yams/plugins
    • /usr/local/lib/yams/plugins, /usr/lib/yams/plugins
    • ${CMAKE_INSTALL_PREFIX}/lib/yams/plugins
  • Disable plugin subsystem: start daemon with --no-plugins.

ONNX plugin build/install/runtime:

  • Prerequisite: onnxruntime (headers + shared libraries) must be available at build and runtime.
  • Build: yams_onnx_plugin is built when onnxruntime is found and ONNX is enabled.
  • Install: plugin installs under ${CMAKE_INSTALL_LIBDIR}/yams/plugins (e.g., /usr/local/lib/yams/plugins).
  • Packaging: set -DYAMS_PACKAGE_PLUGINS=ON (default) and run cpack to include the plugin in binary packages.
  • Discovery: daemon logs a line on startup with plugin scan directories (useful for troubleshooting).

Usage (CLI):

# scan, trust, load
yams plugin scan
yams plugin trust add /usr/local/lib/yams/plugins
yams plugin load /usr/local/lib/yams/plugins/libyams_onnx_plugin.so

First‑time setup with yams init:

  • The init dialog asks whether to enable plugins; if yes, it creates and trusts ~/.local/lib/yams/plugins.
  • Non‑interactive: pass --enable-plugins.

Dev overrides:

  • Set YAMS_PLUGIN_DIR to your build output (e.g., .../build/.../plugins/onnx) to have the daemon scan it.

Behavior:

  • If a trusted plugin advertises model_provider_v1, the daemon prefers it for embeddings. Otherwise it falls back to the legacy registry or mock/null providers (env: YAMS_USE_MOCK_PROVIDER, YAMS_DISABLE_ONNX).

MCP

yams serve  # stdio transport

MCP config (example):

{
  "mcpServers": { "yams": { "command": "/usr/local/bin/yams", "args": ["serve"] } }
}

Troubleshooting

Conan: create default profile

conan profile detect --force

PDF support issues: build with -DYAMS_ENABLE_PDF=OFF.

Plugins not listed by yams plugin list:

  • Ensure the ONNX plugin exists in a scanned directory (install prefix or ~/.local/lib/yams/plugins).
  • Ensure the directory is trusted (yams plugin trust add <dir> or via yams init).
  • Ensure onnxruntime shared libs are resolvable by the loader (e.g., ldd libyams_onnx_plugin.so).
  • Check the daemon startup log for: Plugin scan directories: dir1;dir2;... to confirm discovery paths.

Monitor with yams stats --verbose and yams doctor.

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for yams

Similar Open Source Tools

For similar tasks

For similar jobs