https://github.com/trvon/yams
Persistent memory for LLMs and apps. Content-addressed storage with dedupe, compression, full-text and vector search.
https://github.com/trvon/yams
compression knowledge-base knowledge-graph llm localstorage memory
Last synced: 23 days ago
JSON representation
Persistent memory for LLMs and apps. Content-addressed storage with dedupe, compression, full-text and vector search.
- Host: GitHub
- URL: https://github.com/trvon/yams
- Owner: trvon
- License: gpl-3.0
- Created: 2025-07-24T03:22:11.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-05-20T17:00:37.000Z (27 days ago)
- Last Synced: 2026-05-20T19:42:42.511Z (27 days ago)
- Topics: compression, knowledge-base, knowledge-graph, llm, localstorage, memory
- Language: C++
- Homepage: https://yamsmemory.ai/
- Size: 32.8 MB
- Stars: 373
- Watchers: 2
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Governance: GOVERNANCE.md
- Roadmap: docs/roadmap.md
- Notice: NOTICE
- Maintainers: MAINTAINERS.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
YAMS — Yet Another Memory System
Persistent memory for LLMs and apps. Content-addressed storage with dedupe, compression, full-text and vector search.
> [!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/GLiNER/ColBERT, S3 storage, PDF via ZYP)
- Interactive relevance tuning through CLI tuning and doctor workflows
## 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 -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 MCP client 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).
### Simeon backend
YAMS uses `simeon` by default for both dense vector embeddings and lexical (BM25) search — no model download required. Set `embeddings.backend = "simeon"` in your TOML config (or leave it unset; simeon is the default). Fine-grained knobs live under `[embeddings.simeon]`.
Full config reference and dim tradeoffs: [docs/user_guide/embeddings.md](docs/user_guide/embeddings.md).
## 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}
}
```