lodedb 0.1.2__tar.gz → 0.2.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lodedb
-Version: 0.1.2
+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`).
@@ -121,6 +159,9 @@ for hits in db.search_many(["fox", "dog"], k=5):   # batched; the GPU can serve
 db.search("fox", k=5, filter={"topic": "animals"})                      # bare scalar = exact
 db.search("fox", k=5, filter={"$or": [{"topic": "animals"}, {"year": {"$gte": 2020}}]})
 
+# hybrid search: vector recall plus exact lexical matches the embedding misses
+db.search("E1234", k=5, mode="hybrid")     # surfaces error codes, serials, dates in the body
+
 db.get(fox)     # -> "the quick brown fox jumps"  (text retained by default)
 db.persist()    # durable .tvim/.tvd/.jsd snapshot; replays on reopen
 ```
@@ -139,6 +180,68 @@ reader.search("fox", k=5)                 # reads a committed snapshot
 reader.add("nope")                        # raises ReadOnlyError
 ```
 
+## Hybrid search
+
+Vector search alone misses exact tokens the embedding does not capture: error codes
+(`E1234`), serial numbers (`ABC-123`), dates (`2024-01-15`). Pass `mode="hybrid"` to run a
+lexical BM25 ranker alongside the vector scan and fuse the two ranked lists with Reciprocal
+Rank Fusion. The lexical ranker matches those tokens exactly, so a document whose body carries
+the code is recovered even when the embedding ranks it nowhere near the top.
+
+```python
+db.add("the turbine tripped and reported fault code E1234 overnight", metadata={"unit": "t3"})
+
+db.search("E1234", k=5)                 # mode="vector" (default): may miss the exact code
+db.search("E1234", k=5, mode="hybrid")  # BM25 + RRF: surfaces it in the top-k
+db.search("E1234", k=5, mode="lexical") # BM25 ranking alone, no vector scan
+```
+
+### Prerequisites
+
+`mode="hybrid"` and `mode="lexical"` build a BM25 index over your text, so they need a text
+source enabled when you open the database. `mode="vector"` (the default) needs nothing.
+
+| Mode | Enable | Source of the BM25 index |
+| --- | --- | --- |
+| `"vector"` (default) | nothing | not used |
+| `"hybrid"`, `"lexical"` | `store_text=True` (on by default) | rebuilt in memory from the retained raw text |
+| `"hybrid"`, `"lexical"` | `index_text=True` | a durable on-disk postings store, no raw text required |
+
+Either source is enough and you can enable both. `store_text=True` is the default, so hybrid
+works out of the box. With neither source enabled, a hybrid or lexical query raises a clear,
+actionable error rather than silently degrading.
+
+### How it works
+
+A `filter` constrains both rankers, so `mode="hybrid"` with a filter returns the true top-k of
+the matching subset. The vector half of a hybrid query runs on the same scan as `mode="vector"`,
+including the GPU-resident batch scan that serves `search_many`; only the BM25 ranking and the
+fusion run on the CPU, and the vector kernel and on-disk format are untouched. The serving BM25
+index lives in memory and is maintained incrementally: a small mutation folds just the changed
+chunks into the existing index, so a single `add` never forces a full re-tokenization.
+
+### Durable lexical index (`index_text=True`)
+
+By default the BM25 index is rebuilt from the retained raw text, so it needs `store_text=True`
+and is re-tokenized on the first hybrid query after opening. Pass `index_text=True` to persist
+it instead: each document's per-chunk terms are captured at `add` time into a dedicated `.tvlex`
+sidecar (a base plus a `.lxd` delta journal, committed O(changed) per write), so hybrid and
+lexical search survive a reopen rebuilt straight from the persisted terms, with no
+re-tokenization and without retaining the raw text at all. The `.tvlex` sidecar holds
+payload-derived terms only and, like the raw-text sidecar, never reaches the redacted artifacts
+or telemetry. The tokenizer lowercases and splits on punctuation but keeps code-like tokens
+whole, so `ABC-123` and `2024-01-15` stay findable as single tokens. Reopen with the same
+`index_text` value you wrote with.
+
+```python
+db = LodeDB(path="./data", index_text=True, store_text=False)  # durable lexical index, no raw text
+db.add("the turbine tripped and reported fault code E1234 overnight")
+db.close()
+
+reopened = LodeDB(path="./data", index_text=True, store_text=False)
+reopened.search("E1234", k=5, mode="hybrid")  # works after reopen, rebuilt from persisted terms
+```
+
 ## GPU-resident index
 
 With the `[gpu]` extra on a CUDA host, LodeDB reconstructs the compact index into an fp16
@@ -227,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
@@ -255,6 +434,10 @@ lodedb benchmark   # local, metrics-only benchmark
   faster on the measured M1, so the MPS scan stays off by default until newer Apple GPUs are
   re-measured.
 - **Single queries run on the CPU**; the GPU serves batched `search_many`.
+- **Hybrid search needs a lexical source and serves from memory.** `mode="hybrid"`/`"lexical"`
+  need either `store_text=True` (the index built from raw text) or `index_text=True` (a durable
+  `.tvlex` postings store that survives reopens without raw text). The serving index is held in
+  memory and maintained incrementally across mutations.
 - **Single writer per path.** One writer at a time (many concurrent readers), with no live
   cross-process refresh, on local filesystems only. See
   [Concurrency & durability](#concurrency--durability).

{lodedb-0.1.2 → 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`).
@@ -87,6 +121,9 @@ for hits in db.search_many(["fox", "dog"], k=5):   # batched; the GPU can serve
 db.search("fox", k=5, filter={"topic": "animals"})                      # bare scalar = exact
 db.search("fox", k=5, filter={"$or": [{"topic": "animals"}, {"year": {"$gte": 2020}}]})
 
+# hybrid search: vector recall plus exact lexical matches the embedding misses
+db.search("E1234", k=5, mode="hybrid")     # surfaces error codes, serials, dates in the body
+
 db.get(fox)     # -> "the quick brown fox jumps"  (text retained by default)
 db.persist()    # durable .tvim/.tvd/.jsd snapshot; replays on reopen
 ```
@@ -105,6 +142,68 @@ reader.search("fox", k=5)                 # reads a committed snapshot
 reader.add("nope")                        # raises ReadOnlyError
 ```
 
+## Hybrid search
+
+Vector search alone misses exact tokens the embedding does not capture: error codes
+(`E1234`), serial numbers (`ABC-123`), dates (`2024-01-15`). Pass `mode="hybrid"` to run a
+lexical BM25 ranker alongside the vector scan and fuse the two ranked lists with Reciprocal
+Rank Fusion. The lexical ranker matches those tokens exactly, so a document whose body carries
+the code is recovered even when the embedding ranks it nowhere near the top.
+
+```python
+db.add("the turbine tripped and reported fault code E1234 overnight", metadata={"unit": "t3"})
+
+db.search("E1234", k=5)                 # mode="vector" (default): may miss the exact code
+db.search("E1234", k=5, mode="hybrid")  # BM25 + RRF: surfaces it in the top-k
+db.search("E1234", k=5, mode="lexical") # BM25 ranking alone, no vector scan
+```
+
+### Prerequisites
+
+`mode="hybrid"` and `mode="lexical"` build a BM25 index over your text, so they need a text
+source enabled when you open the database. `mode="vector"` (the default) needs nothing.
+
+| Mode | Enable | Source of the BM25 index |
+| --- | --- | --- |
+| `"vector"` (default) | nothing | not used |
+| `"hybrid"`, `"lexical"` | `store_text=True` (on by default) | rebuilt in memory from the retained raw text |
+| `"hybrid"`, `"lexical"` | `index_text=True` | a durable on-disk postings store, no raw text required |
+
+Either source is enough and you can enable both. `store_text=True` is the default, so hybrid
+works out of the box. With neither source enabled, a hybrid or lexical query raises a clear,
+actionable error rather than silently degrading.
+
+### How it works
+
+A `filter` constrains both rankers, so `mode="hybrid"` with a filter returns the true top-k of
+the matching subset. The vector half of a hybrid query runs on the same scan as `mode="vector"`,
+including the GPU-resident batch scan that serves `search_many`; only the BM25 ranking and the
+fusion run on the CPU, and the vector kernel and on-disk format are untouched. The serving BM25
+index lives in memory and is maintained incrementally: a small mutation folds just the changed
+chunks into the existing index, so a single `add` never forces a full re-tokenization.
+
+### Durable lexical index (`index_text=True`)
+
+By default the BM25 index is rebuilt from the retained raw text, so it needs `store_text=True`
+and is re-tokenized on the first hybrid query after opening. Pass `index_text=True` to persist
+it instead: each document's per-chunk terms are captured at `add` time into a dedicated `.tvlex`
+sidecar (a base plus a `.lxd` delta journal, committed O(changed) per write), so hybrid and
+lexical search survive a reopen rebuilt straight from the persisted terms, with no
+re-tokenization and without retaining the raw text at all. The `.tvlex` sidecar holds
+payload-derived terms only and, like the raw-text sidecar, never reaches the redacted artifacts
+or telemetry. The tokenizer lowercases and splits on punctuation but keeps code-like tokens
+whole, so `ABC-123` and `2024-01-15` stay findable as single tokens. Reopen with the same
+`index_text` value you wrote with.
+
+```python
+db = LodeDB(path="./data", index_text=True, store_text=False)  # durable lexical index, no raw text
+db.add("the turbine tripped and reported fault code E1234 overnight")
+db.close()
+
+reopened = LodeDB(path="./data", index_text=True, store_text=False)
+reopened.search("E1234", k=5, mode="hybrid")  # works after reopen, rebuilt from persisted terms
+```
+
 ## GPU-resident index
 
 With the `[gpu]` extra on a CUDA host, LodeDB reconstructs the compact index into an fp16
@@ -193,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
@@ -221,6 +396,10 @@ lodedb benchmark   # local, metrics-only benchmark
   faster on the measured M1, so the MPS scan stays off by default until newer Apple GPUs are
   re-measured.
 - **Single queries run on the CPU**; the GPU serves batched `search_many`.
+- **Hybrid search needs a lexical source and serves from memory.** `mode="hybrid"`/`"lexical"`
+  need either `store_text=True` (the index built from raw text) or `index_text=True` (a durable
+  `.tvlex` postings store that survives reopens without raw text). The serving index is held in
+  memory and maintained incrementally across mutations.
 - **Single writer per path.** One writer at a time (many concurrent readers), with no live
   cross-process refresh, on local filesystems only. See
   [Concurrency & durability](#concurrency--durability).

{lodedb-0.1.2 → 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.1.2"
+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.1.2 → 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.1.2"
+__version__ = "0.2.1"
 
 __all__ = [
     "LOCAL_MODEL_PRESETS",

{lodedb-0.1.2 → lodedb-0.2.1}/src/lodedb/engine/_commit_manifest.py

@@ -17,6 +17,8 @@ at which a full base was last written):
     <key>.gen/g<epoch>.tvim.tvim-delta/  its ``.tvd`` vector journal
     <key>.gen/g<epoch>.tvtext          opt-in raw-text base (full id->text map)
     <key>.gen/g<epoch>.tvtext.tvtext-delta/  its ``.txd`` raw-text journal
+    <key>.gen/g<epoch>.tvlex           opt-in lexical-index base (id->token lists)
+    <key>.gen/g<epoch>.tvlex.tvlex-delta/  its ``.lxd`` lexical-index journal
 
 and a single top-level pointer:
 
@@ -89,6 +91,12 @@ def base_tvtext_path(persistence_dir: str | Path, index_key: str, epoch: int) ->
     return generation_dir(persistence_dir, index_key) / f"g{int(epoch)}.tvtext"
 
 
+def base_tvlex_path(persistence_dir: str | Path, index_key: str, epoch: int) -> Path:
+    """Returns the lexical-index base path for one index key and base epoch."""
+
+    return generation_dir(persistence_dir, index_key) / f"g{int(epoch)}.tvlex"
+
+
 def is_commit_manifest_name(name: str) -> bool:
     """Returns whether a top-level file name is a root commit manifest."""
 
@@ -173,13 +181,19 @@ def build_commit_body(
     tvim_manifest: dict[str, Any] | None,
     tvim_present: bool,
     tvtext_manifest: dict[str, Any] | None,
+    tvlex_manifest: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """Assembles a root-manifest body capturing one consistent committed generation.
 
     ``tvtext_manifest`` is the raw-text journal manifest (base + delta segments)
     for this committed generation, or ``None`` when raw-text storage is disabled
-    or the index holds no text. It is pinned by the root exactly like the JSON
-    and TurboVec manifests, so raw text commits and rolls back atomically.
+    or the index holds no text. ``tvlex_manifest`` is the analogous lexical-index
+    (BM25 postings) journal manifest, or ``None`` when lexical-index persistence
+    is disabled or the index holds no tokens. Both are pinned by the root exactly
+    like the JSON and TurboVec manifests, so the text sidecar and the lexical
+    sidecar commit and roll back atomically with the generation. ``tvlex`` is an
+    optional key read via ``.get`` (like ``tvtext``), so an older reader that
+    does not know it ignores it.
     """
 
     return {
@@ -192,6 +206,7 @@ def build_commit_body(
         "tvim": tvim_manifest,
         "tvim_present": bool(tvim_present),
         "tvtext": tvtext_manifest,
+        "tvlex": tvlex_manifest,
     }