lodedb 0.2.0__tar.gz → 0.2.1__tar.gz

{lodedb-0.2.0 → lodedb-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lodedb
-Version: 0.2.0
+Version: 0.2.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -14,11 +14,15 @@ Requires-Dist: pytest>=8.3.0 ; extra == 'dev'
 Requires-Dist: ruff==0.15.17 ; extra == 'dev'
 Requires-Dist: cupy-cuda12x>=13.0.0 ; platform_system == 'Linux' and extra == 'gpu'
 Requires-Dist: langchain-core>=0.3.0 ; extra == 'langchain'
+Requires-Dist: llama-index-core>=0.11.0 ; extra == 'llama-index'
 Requires-Dist: mcp>=1.0.0 ; extra == 'mcp'
+Requires-Dist: mem0ai>=2.0.0 ; extra == 'mem0'
 Provides-Extra: dev
 Provides-Extra: gpu
 Provides-Extra: langchain
+Provides-Extra: llama-index
 Provides-Extra: mcp
+Provides-Extra: mem0
 License-File: LICENSE
 License-File: NOTICE
 Summary: Local-first, privacy-by-default embedded vector database. Your data never leaves your machine.
@@ -62,8 +66,9 @@ Fast on a laptop. Faster on a GPU. Exact every time. Never phones home.
 - **Private by default**: text, ids, and vectors stay local; telemetry is metrics-only
   (counts, bytes, latency), never raw payloads.
 - **Local embeddings**: `sentence-transformers` on CUDA, MPS, or CPU.
-- **Batteries included**: a `lodedb` CLI, a loopback dev server, an MCP server, and a
-  LangChain `VectorStore` adapter.
+- **Batteries included**: a `lodedb` CLI, a loopback dev server, an
+  [MCP server](#use-as-an-mcp-server), and LangChain, LlamaIndex, and mem0 adapters
+  (`VectorStore`s, plus a LlamaIndex `PropertyGraphStore`).
 
 > 🏢 **Enterprise** The LodeDB core is Apache-2.0 and free to use. Enterprise licensing is
 > available for commercial support, managed and at-scale serving, and on-prem / BYOC
@@ -80,10 +85,43 @@ Python 3.11+, and bundle the TurboVec (Rust) core, so there's nothing to compile
 the install with `lodedb doctor`. Optional extras:
 
 ```bash
-pip install "lodedb[gpu]"            # GPU-resident scan (Linux/CUDA)
-pip install "lodedb[mcp,langchain]"  # MCP server + LangChain adapter
+pip install "lodedb[gpu]"                            # GPU-resident scan (Linux/CUDA)
+pip install "lodedb[mcp,langchain,llama-index,mem0]" # MCP server + LangChain/LlamaIndex/mem0 adapters
 ```
 
+Using LodeDB as memory for a coding assistant? After installing the `mcp` extra, register its
+server in one step (details under [Use as an MCP server](#use-as-an-mcp-server)):
+
+```bash
+lodedb mcp install --client claude-code        # or: claude-desktop | cursor | lm-studio | codex | all
+```
+
+<details>
+<summary><b>Windows: NVIDIA GPU embeddings</b></summary>
+
+On Windows, PyPI serves the CPU-only PyTorch build by default, so `pip install lodedb` (and
+`uv`) leave embeddings on the CPU even on a CUDA machine, and no package metadata can override
+which torch wheel pip resolves. `lodedb doctor` detects this and prints the fix; `lodedb doctor
+--fix` reinstalls the CUDA build for you:
+
+```bash
+lodedb doctor          # flags a CPU-only PyTorch on Windows and prints the command
+lodedb doctor --fix    # reinstalls the CUDA build so embeddings use your NVIDIA GPU
+```
+
+Or reinstall manually, picking the index for your CUDA version (`cu121`, `cu124`, ...) from the
+[PyTorch install guide](https://pytorch.org/get-started/locally/):
+
+```bash
+pip install torch --force-reinstall --no-deps --index-url https://download.pytorch.org/whl/cu121
+uv pip install torch --reinstall --index-url https://download.pytorch.org/whl/cu121   # with uv
+```
+
+This is Windows-only: the default Linux PyPI wheel already bundles CUDA, and macOS uses CPU
+or MPS.
+
+</details>
+
 <details>
 <summary><b>Build from source</b> (contributors, or a platform without a wheel)</summary>
 
@@ -93,8 +131,8 @@ Linux). [uv](https://docs.astral.sh/uv/) builds and bundles the core for you:
 ```bash
 git clone https://github.com/Egoist-Machines/LodeDB && cd LodeDB
 uv sync                                 # builds + bundles the TurboVec core via maturin
-uv sync --extra mcp --extra langchain   # + MCP server, LangChain adapter
-uv sync --extra gpu                     # + GPU-resident scan (Linux/CUDA)
+uv sync --extra mcp --extra langchain --extra llama-index --extra mem0  # + MCP server, adapters
+uv sync --extra gpu                                                     # + GPU-resident scan (Linux/CUDA)
 ```
 
 Run with `uv run` (e.g. `uv run lodedb doctor`).
@@ -292,6 +330,82 @@ lodedb mcp         # stdio MCP server for agent memory
 lodedb benchmark   # local, metrics-only benchmark
 ```
 
+## Use as an MCP server
+
+LodeDB ships a [Model Context Protocol](https://modelcontextprotocol.io) server, so an agent
+can use a local on-disk database as long-term memory or a RAG store. It runs over stdio, adds
+no storage logic of its own, and your data stays on the machine. Install the extra and point
+your host at `lodedb mcp`:
+
+```bash
+pip install "lodedb[mcp]"
+```
+
+It exposes `lodedb_add`, `lodedb_search`, `lodedb_remove`, and `lodedb_stats`, plus
+`lodedb_get` when text is available. `lodedb_search` returns each hit's stored text alongside
+the score, id, and metadata, so a model can rank and answer in a single call rather than
+chaining a follow-up lookup. It runs [hybrid search](#hybrid-search) (BM25 lexical + vector,
+fused with RRF) by default when text is retained, so exact tokens like error codes and serials
+surface next to semantic matches; with no text retained it falls back to a vector scan. Start
+the server with `--exclude-text` to return metrics only (this also withdraws `lodedb_get`), or
+`--no-store-text` to keep no text on disk at all. `lodedb_stats` is always metrics-only and raw
+query text never leaves the process.
+
+### One command
+
+`lodedb mcp install` writes the correct entry to a client's config for you, so you do not have to
+find the file or hand-write the JSON/TOML:
+
+```bash
+lodedb mcp install --client claude-code        # or: claude-desktop | cursor | lm-studio | codex | all
+lodedb mcp install --client cursor --path ./data --model bge
+```
+
+It resolves the launch command for your environment, so `command` and `args` are correct even when
+`lodedb` is not on `PATH` (it falls back to the `uv run --project ...` form, then an absolute path to
+the entry point), and it resolves `--path` to an absolute path so the server opens the right
+directory wherever the client starts it. The edit is idempotent (an existing `lodedb` entry is
+updated, never duplicated) and never touches other servers in the file. It passes through the same
+options as `lodedb mcp` (`--path`, `--model`, `--device`, `--exclude-text`, `--no-store-text`);
+`--dry-run` prints the entry and target file without writing, and `lodedb mcp uninstall --client
+<client>` removes it again. Override the config location with `--config <path>` (Claude Desktop and
+LM Studio paths differ per OS), and use `--project <dir>` to write Cursor's project-level
+`.cursor/mcp.json`. For Claude Code it runs `claude mcp add`; for the others it edits the config file
+directly.
+
+<details>
+<summary><b>Register by hand</b> (Claude Code, Claude Desktop, Cursor, LM Studio, Codex)</summary>
+
+The `lodedb` command must be on the host's `PATH`; if you installed into a virtual environment
+(including a `uv` project) where it isn't, use the `uv run` form at the bottom.
+
+**Claude Code, Claude Desktop, Cursor, LM Studio**: add the stdio entry to the host's MCP
+config (`claude_desktop_config.json`, `.cursor/mcp.json`, or LM Studio's `mcp.json`), or run
+`claude mcp add lodedb -- lodedb mcp --path ./data`:
+
+```json
+{ "mcpServers": { "lodedb": { "command": "lodedb", "args": ["mcp", "--path", "./data"] } } }
+```
+
+**Codex**: add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.lodedb]
+command = "lodedb"
+args = ["mcp", "--path", "./data"]
+```
+
+**From a virtual environment (uv)**, when `lodedb` is not on `PATH`:
+
+```json
+{ "mcpServers": { "lodedb": { "command": "uv",
+  "args": ["run", "--project", "/path/to/LodeDB", "lodedb", "mcp", "--path", "/path/to/data"] } } }
+```
+
+See [`examples/mcp_config.json`](examples/mcp_config.json) for a copy-paste starting point.
+
+</details>
+
 ## Concurrency & durability
 
 - **Single writer, many readers, per path.** One handle holds the path open for *writing* at

{lodedb-0.2.0 → lodedb-0.2.1}/README.md

@@ -28,8 +28,9 @@ Fast on a laptop. Faster on a GPU. Exact every time. Never phones home.
 - **Private by default**: text, ids, and vectors stay local; telemetry is metrics-only
   (counts, bytes, latency), never raw payloads.
 - **Local embeddings**: `sentence-transformers` on CUDA, MPS, or CPU.
-- **Batteries included**: a `lodedb` CLI, a loopback dev server, an MCP server, and a
-  LangChain `VectorStore` adapter.
+- **Batteries included**: a `lodedb` CLI, a loopback dev server, an
+  [MCP server](#use-as-an-mcp-server), and LangChain, LlamaIndex, and mem0 adapters
+  (`VectorStore`s, plus a LlamaIndex `PropertyGraphStore`).
 
 > 🏢 **Enterprise** The LodeDB core is Apache-2.0 and free to use. Enterprise licensing is
 > available for commercial support, managed and at-scale serving, and on-prem / BYOC
@@ -46,10 +47,43 @@ Python 3.11+, and bundle the TurboVec (Rust) core, so there's nothing to compile
 the install with `lodedb doctor`. Optional extras:
 
 ```bash
-pip install "lodedb[gpu]"            # GPU-resident scan (Linux/CUDA)
-pip install "lodedb[mcp,langchain]"  # MCP server + LangChain adapter
+pip install "lodedb[gpu]"                            # GPU-resident scan (Linux/CUDA)
+pip install "lodedb[mcp,langchain,llama-index,mem0]" # MCP server + LangChain/LlamaIndex/mem0 adapters
 ```
 
+Using LodeDB as memory for a coding assistant? After installing the `mcp` extra, register its
+server in one step (details under [Use as an MCP server](#use-as-an-mcp-server)):
+
+```bash
+lodedb mcp install --client claude-code        # or: claude-desktop | cursor | lm-studio | codex | all
+```
+
+<details>
+<summary><b>Windows: NVIDIA GPU embeddings</b></summary>
+
+On Windows, PyPI serves the CPU-only PyTorch build by default, so `pip install lodedb` (and
+`uv`) leave embeddings on the CPU even on a CUDA machine, and no package metadata can override
+which torch wheel pip resolves. `lodedb doctor` detects this and prints the fix; `lodedb doctor
+--fix` reinstalls the CUDA build for you:
+
+```bash
+lodedb doctor          # flags a CPU-only PyTorch on Windows and prints the command
+lodedb doctor --fix    # reinstalls the CUDA build so embeddings use your NVIDIA GPU
+```
+
+Or reinstall manually, picking the index for your CUDA version (`cu121`, `cu124`, ...) from the
+[PyTorch install guide](https://pytorch.org/get-started/locally/):
+
+```bash
+pip install torch --force-reinstall --no-deps --index-url https://download.pytorch.org/whl/cu121
+uv pip install torch --reinstall --index-url https://download.pytorch.org/whl/cu121   # with uv
+```
+
+This is Windows-only: the default Linux PyPI wheel already bundles CUDA, and macOS uses CPU
+or MPS.
+
+</details>
+
 <details>
 <summary><b>Build from source</b> (contributors, or a platform without a wheel)</summary>
 
@@ -59,8 +93,8 @@ Linux). [uv](https://docs.astral.sh/uv/) builds and bundles the core for you:
 ```bash
 git clone https://github.com/Egoist-Machines/LodeDB && cd LodeDB
 uv sync                                 # builds + bundles the TurboVec core via maturin
-uv sync --extra mcp --extra langchain   # + MCP server, LangChain adapter
-uv sync --extra gpu                     # + GPU-resident scan (Linux/CUDA)
+uv sync --extra mcp --extra langchain --extra llama-index --extra mem0  # + MCP server, adapters
+uv sync --extra gpu                                                     # + GPU-resident scan (Linux/CUDA)
 ```
 
 Run with `uv run` (e.g. `uv run lodedb doctor`).
@@ -258,6 +292,82 @@ lodedb mcp         # stdio MCP server for agent memory
 lodedb benchmark   # local, metrics-only benchmark
 ```
 
+## Use as an MCP server
+
+LodeDB ships a [Model Context Protocol](https://modelcontextprotocol.io) server, so an agent
+can use a local on-disk database as long-term memory or a RAG store. It runs over stdio, adds
+no storage logic of its own, and your data stays on the machine. Install the extra and point
+your host at `lodedb mcp`:
+
+```bash
+pip install "lodedb[mcp]"
+```
+
+It exposes `lodedb_add`, `lodedb_search`, `lodedb_remove`, and `lodedb_stats`, plus
+`lodedb_get` when text is available. `lodedb_search` returns each hit's stored text alongside
+the score, id, and metadata, so a model can rank and answer in a single call rather than
+chaining a follow-up lookup. It runs [hybrid search](#hybrid-search) (BM25 lexical + vector,
+fused with RRF) by default when text is retained, so exact tokens like error codes and serials
+surface next to semantic matches; with no text retained it falls back to a vector scan. Start
+the server with `--exclude-text` to return metrics only (this also withdraws `lodedb_get`), or
+`--no-store-text` to keep no text on disk at all. `lodedb_stats` is always metrics-only and raw
+query text never leaves the process.
+
+### One command
+
+`lodedb mcp install` writes the correct entry to a client's config for you, so you do not have to
+find the file or hand-write the JSON/TOML:
+
+```bash
+lodedb mcp install --client claude-code        # or: claude-desktop | cursor | lm-studio | codex | all
+lodedb mcp install --client cursor --path ./data --model bge
+```
+
+It resolves the launch command for your environment, so `command` and `args` are correct even when
+`lodedb` is not on `PATH` (it falls back to the `uv run --project ...` form, then an absolute path to
+the entry point), and it resolves `--path` to an absolute path so the server opens the right
+directory wherever the client starts it. The edit is idempotent (an existing `lodedb` entry is
+updated, never duplicated) and never touches other servers in the file. It passes through the same
+options as `lodedb mcp` (`--path`, `--model`, `--device`, `--exclude-text`, `--no-store-text`);
+`--dry-run` prints the entry and target file without writing, and `lodedb mcp uninstall --client
+<client>` removes it again. Override the config location with `--config <path>` (Claude Desktop and
+LM Studio paths differ per OS), and use `--project <dir>` to write Cursor's project-level
+`.cursor/mcp.json`. For Claude Code it runs `claude mcp add`; for the others it edits the config file
+directly.
+
+<details>
+<summary><b>Register by hand</b> (Claude Code, Claude Desktop, Cursor, LM Studio, Codex)</summary>
+
+The `lodedb` command must be on the host's `PATH`; if you installed into a virtual environment
+(including a `uv` project) where it isn't, use the `uv run` form at the bottom.
+
+**Claude Code, Claude Desktop, Cursor, LM Studio**: add the stdio entry to the host's MCP
+config (`claude_desktop_config.json`, `.cursor/mcp.json`, or LM Studio's `mcp.json`), or run
+`claude mcp add lodedb -- lodedb mcp --path ./data`:
+
+```json
+{ "mcpServers": { "lodedb": { "command": "lodedb", "args": ["mcp", "--path", "./data"] } } }
+```
+
+**Codex**: add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.lodedb]
+command = "lodedb"
+args = ["mcp", "--path", "./data"]
+```
+
+**From a virtual environment (uv)**, when `lodedb` is not on `PATH`:
+
+```json
+{ "mcpServers": { "lodedb": { "command": "uv",
+  "args": ["run", "--project", "/path/to/LodeDB", "lodedb", "mcp", "--path", "/path/to/data"] } } }
+```
+
+See [`examples/mcp_config.json`](examples/mcp_config.json) for a copy-paste starting point.
+
+</details>
+
 ## Concurrency & durability
 
 - **Single writer, many readers, per path.** One handle holds the path open for *writing* at

{lodedb-0.2.0 → lodedb-0.2.1}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "maturin"
 [project]
 name = "lodedb"
 # Static (maturin reads it here); keep in sync with src/lodedb/__init__.py __version__.
-version = "0.2.0"
+version = "0.2.1"
 description = "Local-first, privacy-by-default embedded vector database. Your data never leaves your machine."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -52,6 +52,10 @@ gpu = ["cupy-cuda12x>=13.0.0; platform_system == 'Linux'"]
 mcp = ["mcp>=1.0.0"]
 # Optional LangChain VectorStore adapter.
 langchain = ["langchain-core>=0.3.0"]
+# Optional LlamaIndex VectorStore adapter.
+llama-index = ["llama-index-core>=0.11.0"]
+# Optional mem0 vector-store adapter.
+mem0 = ["mem0ai>=2.0.0"]
 # ruff is pinned (not floored) so `ruff format`/`ruff check` are reproducible across
 # contributors and CI — the formatter's output can change between ruff releases.
 dev = ["pytest>=8.3.0", "ruff==0.15.17"]

{lodedb-0.2.0 → lodedb-0.2.1}/src/lodedb/__init__.py

@@ -19,7 +19,7 @@ from lodedb.local import (
 from lodedb.local.cli import app, main
 
 # Keep in sync with `version` in pyproject.toml (the release workflow asserts they match).
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 __all__ = [
     "LOCAL_MODEL_PRESETS",

{lodedb-0.2.0 → lodedb-0.2.1}/src/lodedb/engine/core.py

@@ -188,15 +188,18 @@ class EngineVectorDocument:
     """Stores one pre-embedded document supplied to the local engine (vector-in).
 
     Unlike :class:`EngineDocument`, the caller supplies the embedding vector
-    directly and there is no text: the engine skips chunking and embedding and
-    stores the vector as a single chunk. The vector must match the index's
-    ``native_dim`` and is expected to be L2-normalized (the SDK normalizes by
-    default) so cosine scoring stays comparable with the text path.
+    directly: the engine skips chunking and embedding and stores the vector as a
+    single chunk. ``text`` is optional retained payload text only; when present
+    and raw-text storage is enabled it is stored in the dedicated text sidecar,
+    never in the redacted snapshot or metadata. The vector must match the
+    index's ``native_dim`` and is expected to be L2-normalized (the SDK
+    normalizes by default) so cosine scoring stays comparable with the text path.
     """
 
     document_id: str
     vector: tuple[float, ...]
     metadata: dict[str, str] = field(default_factory=dict)
+    text: str | None = None
 
 
 @dataclass(frozen=True)
@@ -1107,10 +1110,12 @@ class LodeEngine:
         """Upserts pre-embedded documents (vector-in), skipping chunking/embedding.
 
         The caller supplies embedding vectors directly; each is stored as a
-        single chunk and **no** raw text is captured. Vectors must match the
-        index ``native_dim``. Reuses the same atomic-commit + O(changed) direct
-        TurboVec sync path as :meth:`upsert_documents`, so vector-in inherits
-        crash-atomic commits and incremental persistence unchanged.
+        single chunk. If a vector document carries optional ``text``, that text
+        is captured only in the raw-text sidecar when enabled; it is never
+        embedded, chunked, or written to redacted metadata. Vectors must match
+        the index ``native_dim``. Reuses the same atomic-commit + O(changed)
+        direct TurboVec sync path as :meth:`upsert_documents`, so vector-in
+        inherits crash-atomic commits and incremental persistence unchanged.
         """
 
         state = self._index_for_context(context, index_id=index_id, operation="upsert_vectors")
@@ -1124,8 +1129,7 @@ class LodeEngine:
         )
         if isinstance(result, EngineResponse):
             return result
-        # Deliberately no _capture_document_text: vector-in documents carry no
-        # raw text, so get()/get_text() return None for them by design.
+        self._capture_vector_document_text(state, vectors)
         self._finalize_document_ingest(
             context=context,
             state=state,
@@ -1140,6 +1144,92 @@ class LodeEngine:
             },
         )
 
+    @_synchronized
+    def update_document_payload(
+        self,
+        *,
+        context: EngineRequestContext,
+        document_id: str,
+        metadata: Mapping[str, Any] | None = None,
+        text: str | None = None,
+        clear_text: bool = False,
+        index_id: str | None = None,
+    ) -> EngineResponse:
+        """Updates an existing document's metadata and/or retained raw text.
+
+        This is intentionally narrow: it does not alter vectors or chunk
+        membership, and it never embeds. It exists for adapters that maintain
+        host-framework payloads beside precomputed vectors, such as mem0's
+        payload-only entity-link updates.
+        """
+
+        state = self._index_for_context(
+            context, index_id=index_id, operation="update_document_payload"
+        )
+        if isinstance(state, EngineResponse):
+            return state
+        document_id = str(document_id).strip()
+        if not document_id:
+            return self._error(
+                400, "document_id is required", "update_document_payload", context.client_id
+            )
+        if document_id not in state.document_hashes:
+            return self._error(
+                404, "document not found", "update_document_payload", context.client_id
+            )
+
+        changed = False
+        if metadata is not None:
+            try:
+                state.document_metadata[document_id] = _validate_metadata(metadata)
+            except ValueError as exc:
+                return self._error(400, str(exc), "update_document_payload", context.client_id)
+            self._metadata_posting_indexes.pop(state.index_key, None)
+            changed = True
+
+        if text is not None or clear_text:
+            if not self.raw_text_storage_enabled:
+                return self._error(
+                    400,
+                    "raw document text storage is not enabled for this index",
+                    "update_document_payload",
+                    context.client_id,
+                )
+            if clear_text:
+                state.document_text.pop(document_id, None)
+            else:
+                if not isinstance(text, str):
+                    return self._error(
+                        400,
+                        "text must be a string",
+                        "update_document_payload",
+                        context.client_id,
+                    )
+                state.document_text[document_id] = text
+            changed = True
+
+        if changed:
+            state.updated_at = _utc_now_iso(context.now)
+            self._record_pending_state_journal_documents(
+                state, upserted_document_ids=(document_id,)
+            )
+            # Run the incremental TurboVec sync even though no vectors changed: it is
+            # also what marks this commit delta-eligible (it sets the pending TVIM
+            # delta that _delta_append_ok requires), so _persist_state appends an
+            # O(changed) journal delta instead of rewriting the full O(corpus) base.
+            self._sync_direct_turbovec_index(state)
+            self._persist_state(state)
+
+        return EngineResponse(
+            200,
+            {
+                "status": "updated",
+                "document_id": document_id,
+                "metadata_updated": metadata is not None,
+                "text_updated": text is not None or clear_text,
+            },
+        )
+
     def _build_initial_documents(
         self,
         *,
@@ -4491,6 +4581,21 @@ class LodeEngine:
         for document in documents:
             state.document_text[document.document_id] = document.text
 
+    def _capture_vector_document_text(
+        self,
+        state: ClientIndexState,
+        documents: tuple[EngineVectorDocument, ...],
+    ) -> None:
+        """Records optional vector-in payload text without embedding it."""
+
+        if not self.raw_text_storage_enabled:
+            return
+        for document in documents:
+            if document.text is None:
+                state.document_text.pop(document.document_id, None)
+            else:
+                state.document_text[document.document_id] = document.text
+
     def _capture_lexical_tokens(
         self,
         state: ClientIndexState,

{lodedb-0.2.0 → lodedb-0.2.1}/src/lodedb/engine/index.py

@@ -227,6 +227,27 @@ class LodeIndex:
             )
         )
 
+    def update_document_payload(
+        self,
+        document_id: str,
+        *,
+        metadata: Mapping[str, Any] | None = None,
+        text: str | None = None,
+        clear_text: bool = False,
+    ) -> dict[str, Any]:
+        """Updates an existing document's metadata and/or retained raw text."""
+
+        return self._unwrap(
+            self.engine.update_document_payload(
+                context=self._context(),
+                index_id=self.index_id,
+                document_id=_required_text(document_id, "document_id"),
+                metadata=metadata,
+                text=text,
+                clear_text=clear_text,
+            )
+        )
+
     def query_vector(
         self,
         vector: Iterable[float],
@@ -540,6 +561,7 @@ def _vector_document_from_item(
         document_id=_required_text(item.get("document_id"), "document_id"),
         vector=tuple(float(value) for value in vector),
         metadata=safe_metadata,
+        text=_optional_text(item.get("text"), "text"),
     )
 
 
@@ -666,6 +688,20 @@ def _required_text(value: Any, name: str) -> str:
     return stripped
 
 
+def _optional_text(value: Any, name: str) -> str | None:
+    """Returns an optional string for vector-in retained payload text."""
+
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise EngineError(
+            f"{name} must be a string",
+            status_code=400,
+            response={"status": "error", "error": f"{name} must be a string"},
+        )
+    return value
+
+
 def _required_bool(value: Any, name: str) -> bool:
     """Returns a JSON-style boolean value while rejecting strings and integers."""