diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..7a5da380
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,38 @@
+## Cursor Cloud specific instructions
+
+### Overview
+
+LEANN is a vector database / RAG system with C++ native backends (HNSW via FAISS, DiskANN). It uses `uv` as the package manager and Python 3.11 (pinned in `.python-version`).
+
+### Building from source
+
+The C++ backends require `CC=gcc CXX=g++` environment variables on Ubuntu — the default Clang compiler cannot find the C++ standard library headers. You must also create a `libstdc++.so` symlink:
+
+```bash
+sudo ln -sf /usr/lib/gcc/x86_64-linux-gnu/13/libstdc++.so /usr/lib/x86_64-linux-gnu/libstdc++.so
+```
+
+MKL install (`libmkl-full-dev`) requires `DEBIAN_FRONTEND=noninteractive` to avoid an interactive prompt.
+
+### Common commands
+
+All commands use `uv run` to execute within the project venv. See `pyproject.toml` for full configuration.
+
+| Task | Command |
+|------|---------|
+| Install all deps | `CC=gcc CXX=g++ uv sync --extra diskann --group lint --group test --group dev` |
+| Lint | `uv run ruff check .` |
+| Format check | `uv run ruff format --check .` |
+| Run tests | `uv run pytest tests/ -v --tb=short -m "not integration"` |
+| Run specific test | `uv run pytest tests/test_basic.py -v` |
+| Hello-world demo | See README Quick Start or `python -m apps.document_rag --query "..."` |
+
+### Known issues
+
+- **DiskANN partition tests** (`test_diskann_partition.py`): Several tests fail with abort signals in the DiskANN C++ backend. These are pre-existing failures, not caused by environment setup.
+- **Lint errors**: 29 pre-existing lint errors in demo scripts (`COMPREHENSIVE_GUIDE.py`, `ask_non_interactive.py`, `demo.py`, `demo_advanced.py`, `quick_search.py`). These are not in core library code.
+- **Embedding model download**: The first run downloads `facebook/contriever` (~500MB). Subsequent runs use the cached model from `~/.cache/huggingface/`.
+
+### System dependencies (already in VM snapshot)
+
+`libomp-dev libboost-all-dev protobuf-compiler libzmq3-dev pkg-config libabsl-dev libaio-dev libprotobuf-dev libmkl-full-dev patchelf swig g++`