cocoindex-code 0.2.39__tar.gz → 0.2.40__tar.gz

cocoindex_code-0.2.39/README.md → cocoindex_code-0.2.40/PKG-INFO

@@ -1,3 +1,47 @@
+Metadata-Version: 2.4
+Name: cocoindex-code
+Version: 0.2.40
+Summary: MCP server for indexing and querying codebases using CocoIndex
+Project-URL: Homepage, https://github.com/cocoindex-io/cocoindex-code
+Project-URL: Repository, https://github.com/cocoindex-io/cocoindex-code
+Project-URL: Issues, https://github.com/cocoindex-io/cocoindex-code/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cocoindex,codebase,indexing,mcp,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: cocoindex[litellm]<1.1.0,>=1.0.17
+Requires-Dist: einops>=0.8.2
+Requires-Dist: mcp<3,>=2.0.0
+Requires-Dist: msgspec>=0.19.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pathspec<1.0,>=0.12.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: sqlite-vec>=0.1.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: cocoindex[sentence-transformers]<1.1.0,>=1.0.17; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: prek>=0.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: embeddings-local
+Requires-Dist: cocoindex[sentence-transformers]<1.1.0,>=1.0.17; extra == 'embeddings-local'
+Provides-Extra: full
+Requires-Dist: cocoindex[sentence-transformers]<1.1.0,>=1.0.17; extra == 'full'
+Description-Content-Type: text/markdown
+
 <p align="center">
 <img width="2428" alt="cocoindex code" src="https://github.com/user-attachments/assets/d05961b4-0b7b-42ea-834a-59c3c01717ca" />
 </p>
@@ -253,6 +297,7 @@ The background daemon starts automatically on first use.
 | `ccc mcp` | Run as MCP server in stdio mode |
 | `ccc doctor` | Run diagnostics — checks settings, daemon, model, file matching, and index health |
 | `ccc reset` | Delete index databases. `--all` also removes settings. `-f` skips confirmation. |
+| `ccc version` | Print the CLI version |
 | `ccc daemon status` | Show daemon version, uptime, and loaded projects |
 | `ccc daemon restart` | Restart the background daemon |
 | `ccc daemon stop` | Stop the daemon |
@@ -504,6 +549,8 @@ embedding:
   model: Snowflake/snowflake-arctic-embed-xs
   device: mps                                        # optional: cpu, cuda, mps (auto-detected if omitted)
   min_interval_ms: 300                               # optional: pace LiteLLM embedding requests to reduce 429s; defaults to 5 for LiteLLM
+  mps_low_watermark_ratio: 0.4                       # optional: PyTorch allocator soft limit
+  mps_high_watermark_ratio: 0.5                      # optional: PyTorch allocator hard limit
 
   # Optional extra kwargs passed to the embedder, separately for indexing vs query.
   # `ccc init` auto-populates these for known models (e.g. Cohere, Voyage, Nvidia NIM,
@@ -518,11 +565,16 @@ envs:                                                # extra environment variabl
 
 daemon:
   idle_timeout_minutes: 180                          # optional: exit the daemon after this long without client activity (default 180, 0 = never)
+  keep_alive_with_mcp: true                          # optional: keep the daemon warm while an MCP client is connected (default true)
 ```
 
 > **Note:** The daemon inherits your shell environment. If an API key (e.g. `OPENAI_API_KEY`) is already set as an environment variable, you don't need to duplicate it in `envs`. The `envs` field is only for values that aren't in your environment.
 
-> **Idle timeout:** the background daemon holds the embedding model in RAM, so it exits after `daemon.idle_timeout_minutes` without client activity and is restarted automatically on your next `ccc` command or MCP search. A live MCP session sends periodic heartbeats, so the daemon never idles out while your coding agent is connected. Set `0` to keep the daemon running forever.
+> **Apple Silicon memory safety:** MPS SentenceTransformer calls use [CocoIndex's isolated GPU subprocess](https://github.com/cocoindex-io/cocoindex/blob/v1.0.18/python/cocoindex/_internal/runner.py), keeping the model loaded while isolating Metal allocations from the daemon. The low and high watermarks are ratios of PyTorch's recommended maximum working set; they default here to `0.4` and `0.5`. CocoIndex retries MPS out-of-memory failures with progressively smaller batches, and cocoindex-code [releases unused allocator cache](https://docs.pytorch.org/docs/stable/generated/torch.mps.empty_cache.html) after each index run. Explicit `COCOINDEX_RUN_GPU_IN_SUBPROCESS`, `PYTORCH_MPS_LOW_WATERMARK_RATIO`, and `PYTORCH_MPS_HIGH_WATERMARK_RATIO` environment variables take precedence over these defaults.
+
+> **Indexing concurrency:** Multiple projects may prepare indexes concurrently, while CocoIndex serializes their GPU calls through its single MPS subprocess. A search waits only when its own project still needs the initial index.
+
+> **Idle timeout:** the background daemon holds the embedding model in RAM, so it exits after `daemon.idle_timeout_minutes` without client activity and is restarted automatically on your next `ccc` command or MCP search. By default, a live MCP session sends periodic heartbeats so the daemon remains warm while your coding agent is connected. Set `daemon.keep_alive_with_mcp: false` to let the daemon idle-exit during long-lived MCP sessions and release the model between real requests. Set `idle_timeout_minutes: 0` to keep the daemon running forever.
 
 > **Custom location:** set `COCOINDEX_CODE_DIR` to place `global_settings.yml` somewhere other than `~/.cocoindex_code/` — useful if you want the file to live alongside your projects (e.g. on a synced folder).
 
@@ -570,6 +622,8 @@ exclude_patterns:
   - "**/dist"
   # ...
 
+max_file_size: 500KB       # skip files larger than this (default: no limit)
+
 language_overrides:
   - ext: inc               # treat .inc files as PHP
     lang: php
@@ -581,7 +635,14 @@ chunkers:
 
 > `.cocoindex_code/` is automatically added to `.gitignore` during init.
 
-After editing `include_patterns`, `exclude_patterns`, or `language_overrides`:
+`max_file_size` keeps bundled or generated files out of the index without having
+to enumerate them in `exclude_patterns`. It accepts a plain byte count
+(`1048576`) or a size with a binary unit suffix: `B`, `KB`, `MB`, `GB`
+(case-insensitive, so `500KB` and `500 kb` are the same). The limit is
+inclusive, and omitting the key indexes files of any size. It applies wherever
+project file matching does, so `ccc grep` skips the same files.
+
+After editing `include_patterns`, `exclude_patterns`, `max_file_size`, or `language_overrides`:
 
 - Run `ccc doctor` to preview which files match.
 - Run `ccc index` or `ccc search --refresh ...` to update the existing index.

cocoindex_code-0.2.39/PKG-INFO → cocoindex_code-0.2.40/README.md

@@ -1,47 +1,3 @@
-Metadata-Version: 2.4
-Name: cocoindex-code
-Version: 0.2.39
-Summary: MCP server for indexing and querying codebases using CocoIndex
-Project-URL: Homepage, https://github.com/cocoindex-io/cocoindex-code
-Project-URL: Repository, https://github.com/cocoindex-io/cocoindex-code
-Project-URL: Issues, https://github.com/cocoindex-io/cocoindex-code/issues
-License-Expression: Apache-2.0
-License-File: LICENSE
-Keywords: cocoindex,codebase,indexing,mcp,vector-search
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
-Requires-Dist: cocoindex[litellm]<1.1.0,>=1.0.13
-Requires-Dist: einops>=0.8.2
-Requires-Dist: mcp>=1.0.0
-Requires-Dist: msgspec>=0.19.0
-Requires-Dist: numpy>=1.24.0
-Requires-Dist: pathspec>=0.12.1
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: questionary>=2.0.0
-Requires-Dist: sqlite-vec>=0.1.0
-Requires-Dist: typer>=0.9.0
-Provides-Extra: dev
-Requires-Dist: cocoindex[sentence-transformers]<1.1.0,>=1.0.13; extra == 'dev'
-Requires-Dist: mypy>=1.0.0; extra == 'dev'
-Requires-Dist: prek>=0.1.0; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
-Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
-Requires-Dist: pytest>=7.0.0; extra == 'dev'
-Requires-Dist: ruff>=0.1.0; extra == 'dev'
-Provides-Extra: embeddings-local
-Requires-Dist: cocoindex[sentence-transformers]<1.1.0,>=1.0.13; extra == 'embeddings-local'
-Provides-Extra: full
-Requires-Dist: cocoindex[sentence-transformers]<1.1.0,>=1.0.13; extra == 'full'
-Description-Content-Type: text/markdown
-
 <p align="center">
 <img width="2428" alt="cocoindex code" src="https://github.com/user-attachments/assets/d05961b4-0b7b-42ea-834a-59c3c01717ca" />
 </p>
@@ -297,6 +253,7 @@ The background daemon starts automatically on first use.
 | `ccc mcp` | Run as MCP server in stdio mode |
 | `ccc doctor` | Run diagnostics — checks settings, daemon, model, file matching, and index health |
 | `ccc reset` | Delete index databases. `--all` also removes settings. `-f` skips confirmation. |
+| `ccc version` | Print the CLI version |
 | `ccc daemon status` | Show daemon version, uptime, and loaded projects |
 | `ccc daemon restart` | Restart the background daemon |
 | `ccc daemon stop` | Stop the daemon |
@@ -548,6 +505,8 @@ embedding:
   model: Snowflake/snowflake-arctic-embed-xs
   device: mps                                        # optional: cpu, cuda, mps (auto-detected if omitted)
   min_interval_ms: 300                               # optional: pace LiteLLM embedding requests to reduce 429s; defaults to 5 for LiteLLM
+  mps_low_watermark_ratio: 0.4                       # optional: PyTorch allocator soft limit
+  mps_high_watermark_ratio: 0.5                      # optional: PyTorch allocator hard limit
 
   # Optional extra kwargs passed to the embedder, separately for indexing vs query.
   # `ccc init` auto-populates these for known models (e.g. Cohere, Voyage, Nvidia NIM,
@@ -562,11 +521,16 @@ envs:                                                # extra environment variabl
 
 daemon:
   idle_timeout_minutes: 180                          # optional: exit the daemon after this long without client activity (default 180, 0 = never)
+  keep_alive_with_mcp: true                          # optional: keep the daemon warm while an MCP client is connected (default true)
 ```
 
 > **Note:** The daemon inherits your shell environment. If an API key (e.g. `OPENAI_API_KEY`) is already set as an environment variable, you don't need to duplicate it in `envs`. The `envs` field is only for values that aren't in your environment.
 
-> **Idle timeout:** the background daemon holds the embedding model in RAM, so it exits after `daemon.idle_timeout_minutes` without client activity and is restarted automatically on your next `ccc` command or MCP search. A live MCP session sends periodic heartbeats, so the daemon never idles out while your coding agent is connected. Set `0` to keep the daemon running forever.
+> **Apple Silicon memory safety:** MPS SentenceTransformer calls use [CocoIndex's isolated GPU subprocess](https://github.com/cocoindex-io/cocoindex/blob/v1.0.18/python/cocoindex/_internal/runner.py), keeping the model loaded while isolating Metal allocations from the daemon. The low and high watermarks are ratios of PyTorch's recommended maximum working set; they default here to `0.4` and `0.5`. CocoIndex retries MPS out-of-memory failures with progressively smaller batches, and cocoindex-code [releases unused allocator cache](https://docs.pytorch.org/docs/stable/generated/torch.mps.empty_cache.html) after each index run. Explicit `COCOINDEX_RUN_GPU_IN_SUBPROCESS`, `PYTORCH_MPS_LOW_WATERMARK_RATIO`, and `PYTORCH_MPS_HIGH_WATERMARK_RATIO` environment variables take precedence over these defaults.
+
+> **Indexing concurrency:** Multiple projects may prepare indexes concurrently, while CocoIndex serializes their GPU calls through its single MPS subprocess. A search waits only when its own project still needs the initial index.
+
+> **Idle timeout:** the background daemon holds the embedding model in RAM, so it exits after `daemon.idle_timeout_minutes` without client activity and is restarted automatically on your next `ccc` command or MCP search. By default, a live MCP session sends periodic heartbeats so the daemon remains warm while your coding agent is connected. Set `daemon.keep_alive_with_mcp: false` to let the daemon idle-exit during long-lived MCP sessions and release the model between real requests. Set `idle_timeout_minutes: 0` to keep the daemon running forever.
 
 > **Custom location:** set `COCOINDEX_CODE_DIR` to place `global_settings.yml` somewhere other than `~/.cocoindex_code/` — useful if you want the file to live alongside your projects (e.g. on a synced folder).
 
@@ -614,6 +578,8 @@ exclude_patterns:
   - "**/dist"
   # ...
 
+max_file_size: 500KB       # skip files larger than this (default: no limit)
+
 language_overrides:
   - ext: inc               # treat .inc files as PHP
     lang: php
@@ -625,7 +591,14 @@ chunkers:
 
 > `.cocoindex_code/` is automatically added to `.gitignore` during init.
 
-After editing `include_patterns`, `exclude_patterns`, or `language_overrides`:
+`max_file_size` keeps bundled or generated files out of the index without having
+to enumerate them in `exclude_patterns`. It accepts a plain byte count
+(`1048576`) or a size with a binary unit suffix: `B`, `KB`, `MB`, `GB`
+(case-insensitive, so `500KB` and `500 kb` are the same). The limit is
+inclusive, and omitting the key indexes files of any size. It applies wherever
+project file matching does, so `ccc grep` skips the same files.
+
+After editing `include_patterns`, `exclude_patterns`, `max_file_size`, or `language_overrides`:
 
 - Run `ccc doctor` to preview which files match.
 - Run `ccc index` or `ccc search --refresh ...` to update the existing index.

{cocoindex_code-0.2.39 → cocoindex_code-0.2.40}/pyproject.toml

@@ -22,15 +22,15 @@ classifiers = [
 ]
 
 dependencies = [
-    "mcp>=1.0.0",
-    "cocoindex[litellm]>=1.0.13,<1.1.0",
+    "mcp>=2.0.0,<3",
+    "cocoindex[litellm]>=1.0.17,<1.1.0",
     "sqlite-vec>=0.1.0",
     "pydantic>=2.0.0",
     "numpy>=1.24.0",
     "einops>=0.8.2",
     "typer>=0.9.0",
     "msgspec>=0.19.0",
-    "pathspec>=0.12.1",
+    "pathspec>=0.12.1,<1.0",
     "pyyaml>=6.0",
     "questionary>=2.0.0",
 ]
@@ -39,7 +39,7 @@ dependencies = [
 # `embeddings-local` is the primary feature extra: it pulls in
 # `sentence-transformers` (via cocoindex) so local embeddings work without
 # an API key.
-embeddings-local = ["cocoindex[sentence-transformers]>=1.0.13,<1.1.0"]
+embeddings-local = ["cocoindex[sentence-transformers]>=1.0.17,<1.1.0"]
 # `full` is the umbrella "batteries-included" alias. Today it's just
 # `embeddings-local`, but we expect to bundle more optional niceties under
 # it over time — users who want everything can keep using `[full]` and pick
@@ -47,7 +47,7 @@ embeddings-local = ["cocoindex[sentence-transformers]>=1.0.13,<1.1.0"]
 # `:full` image variant for consistency across install paths. Contents are
 # inlined rather than self-referencing `cocoindex-code[embeddings-local]`
 # to avoid resolver edge cases with older pip.
-full = ["cocoindex[sentence-transformers]>=1.0.13,<1.1.0"]
+full = ["cocoindex[sentence-transformers]>=1.0.17,<1.1.0"]
 dev = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
@@ -55,7 +55,7 @@ dev = [
     "ruff>=0.1.0",
     "mypy>=1.0.0",
     "prek>=0.1.0",
-    "cocoindex[sentence-transformers]>=1.0.13,<1.1.0",
+    "cocoindex[sentence-transformers]>=1.0.17,<1.1.0",
 ]
 
 [project.scripts]
@@ -89,7 +89,7 @@ dev = [
     "mypy>=1.0.0",
     "prek>=0.1.0",
     "types-pyyaml>=6.0.12.20250915",
-    "cocoindex[sentence-transformers]>=1.0.13,<1.1.0",
+    "cocoindex[sentence-transformers]>=1.0.17,<1.1.0",
 ]
 
 [tool.ruff]

{cocoindex_code-0.2.39 → cocoindex_code-0.2.40}/src/cocoindex_code/_daemon_paths.py

@@ -6,15 +6,22 @@ can import these without pulling in the full daemon stack.
 
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import sys
+import tempfile
 import time
 from dataclasses import dataclass
 from pathlib import Path
 
 from .settings import user_settings_dir
 
+# Max bytes in sockaddr_un.sun_path, including the NUL terminator: 104 on the
+# BSDs (incl. macOS), 108 on Linux. Exceeding it makes bind() fail with
+# "AF_UNIX path too long" — unlike ordinary files, which get PATH_MAX (~1024).
+_SUN_PATH_MAX = 104 if sys.platform == "darwin" else 108
+
 
 def daemon_runtime_dir() -> Path:
     """Return the directory that holds daemon runtime artifacts.
@@ -39,18 +46,37 @@ def connection_family() -> str:
     return "AF_PIPE" if sys.platform == "win32" else "AF_UNIX"
 
 
+def _runtime_dir_hash() -> str:
+    """Stable short id for the current runtime dir.
+
+    Distinguishes daemon instances that differ only by
+    ``COCOINDEX_CODE_RUNTIME_DIR`` / ``COCOINDEX_CODE_DIR``, so tests, users,
+    and containers never collide on one address.
+    """
+    return hashlib.md5(str(daemon_runtime_dir()).encode()).hexdigest()[:12]
+
+
 def daemon_socket_path() -> str:
-    """Return the daemon socket/pipe address."""
+    """Return the daemon socket/pipe address.
+
+    Normally ``<runtime dir>/daemon.sock``. When that exceeds the platform's
+    ``sun_path`` limit — a deep ``$HOME``, a sandbox, a container path — it
+    would fail at bind() with a message that reads like a broken install, so
+    fall back to a short path under the temp dir keyed by the runtime dir.
+    Client and daemon both resolve through here, so they agree either way.
+    """
     if sys.platform == "win32":
-        import hashlib
-
-        # Hash the runtime dir so COCOINDEX_CODE_RUNTIME_DIR (or the
-        # COCOINDEX_CODE_DIR fallback) overrides produce unique pipe names,
-        # preventing conflicts between different daemon instances (tests,
-        # users, etc.)
-        dir_hash = hashlib.md5(str(daemon_runtime_dir()).encode()).hexdigest()[:12]
-        return rf"\\.\pipe\cocoindex_code_{dir_hash}"
-    return str(daemon_runtime_dir() / "daemon.sock")
+        return rf"\\.\pipe\cocoindex_code_{_runtime_dir_hash()}"
+
+    path = daemon_runtime_dir() / "daemon.sock"
+    if len(str(path).encode()) < _SUN_PATH_MAX:
+        return str(path)
+
+    # gettempdir() honors $TMPDIR, which is per-user and private on macOS; on
+    # Linux it is usually shared /tmp, so include the uid to avoid a foreign
+    # socket sitting at our address.
+    short = Path(tempfile.gettempdir()) / f"ccc-{os.getuid()}-{_runtime_dir_hash()}.sock"
+    return str(short)
 
 
 def daemon_pid_path() -> Path:

{cocoindex_code-0.2.39 → cocoindex_code-0.2.40}/src/cocoindex_code/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.39'
-__version_tuple__ = version_tuple = (0, 2, 39)
+__version__ = version = '0.2.40'
+__version_tuple__ = version_tuple = (0, 2, 40)
 
 __commit_id__ = commit_id = None

{cocoindex_code-0.2.39 → cocoindex_code-0.2.40}/src/cocoindex_code/cli.py

@@ -22,6 +22,7 @@ if TYPE_CHECKING:
         SearchResponse,
     )
 
+from ._version import __version__
 from .settings import (
     DEFAULT_ST_MODEL,
     EmbeddingSettings,
@@ -195,6 +196,15 @@ def print_index_stats(status: ProjectStatusResponse) -> None:
             _typer.echo(f"    {lang}: {count} chunks")
 
 
+def _echo_search_text(text: str) -> None:
+    """Echo result text, replacing characters unsupported by the console codec."""
+    try:
+        _typer.echo(text)
+    except UnicodeEncodeError as error:
+        safe_text = text.encode(error.encoding, errors="replace").decode(error.encoding)
+        _typer.echo(safe_text)
+
+
 def print_search_results(response: SearchResponse) -> None:
     """Print formatted search results."""
     if not response.success:
@@ -207,8 +217,8 @@ def print_search_results(response: SearchResponse) -> None:
 
     for i, r in enumerate(response.results, 1):
         _typer.echo(f"\n--- Result {i} (score: {r.score:.3f}) ---")
-        _typer.echo(f"File: {r.file_path}:{r.start_line}-{r.end_line} [{r.language}]")
-        _typer.echo(r.content)
+        _echo_search_text(f"File: {r.file_path}:{r.start_line}-{r.end_line} [{r.language}]")
+        _echo_search_text(r.content)
 
 
 def _run_index_with_progress(project_root: str) -> None:
@@ -1120,6 +1130,12 @@ def daemon_stop() -> None:
         _typer.echo("Daemon stopped.")
 
 
+@app.command()
+def version() -> None:
+    """Print the CLI version."""
+    _typer.echo(__version__)
+
+
 @app.command("run-daemon", hidden=True)
 def run_daemon_cmd() -> None:
     """Internal: run the daemon process."""

{cocoindex_code-0.2.39 → cocoindex_code-0.2.40}/src/cocoindex_code/daemon.py

@@ -73,7 +73,7 @@ from .settings import (
     target_sqlite_db_path,
     user_settings_path,
 )
-from .shared import Embedder, check_embedding, create_embedder
+from .shared import Embedder, check_embedding, configure_mps_environment, create_embedder
 
 logger = logging.getLogger(__name__)
 
@@ -135,6 +135,7 @@ class ProjectRegistry:
 
     _projects: dict[str, Project]
     _embedder: Embedder | None
+    _clear_mps_cache_after_index: bool
     indexing_params: dict[str, Any]
     query_params: dict[str, Any]
 
@@ -143,9 +144,11 @@ class ProjectRegistry:
         embedder: Embedder | None,
         indexing_params: dict[str, Any] | None = None,
         query_params: dict[str, Any] | None = None,
+        clear_mps_cache_after_index: bool = False,
     ) -> None:
         self._projects = {}
         self._embedder = embedder
+        self._clear_mps_cache_after_index = clear_mps_cache_after_index
         self.indexing_params = dict(indexing_params) if indexing_params else {}
         self.query_params = dict(query_params) if query_params else {}
 
@@ -165,6 +168,7 @@ class ProjectRegistry:
                 indexing_params=self.indexing_params,
                 query_params=self.query_params,
                 chunker_registry=chunker_registry,
+                clear_mps_cache_after_index=self._clear_mps_cache_after_index,
             )
             self._projects[project_root] = project
         return self._projects[project_root]
@@ -636,6 +640,7 @@ def run_daemon(
     embedder: Embedder | None
     indexing_params: dict[str, Any] = {}
     query_params: dict[str, Any] = {}
+    clear_mps_cache_after_index = False
     handshake_warnings: list[str] = []
     daemon_settings = DaemonSettings()
     if user_settings_path().is_file():
@@ -644,6 +649,7 @@ def run_daemon(
         settings_env_keys = list(user_settings.envs.keys())
         for key, value in user_settings.envs.items():
             os.environ[key] = value
+        clear_mps_cache_after_index = configure_mps_environment(user_settings.embedding)
         # Resolve params BEFORE constructing the embedder so invalid configs
         # fail fast without paying the model-load cost.
         try:
@@ -684,6 +690,7 @@ def run_daemon(
         embedder,
         indexing_params=indexing_params,
         query_params=query_params,
+        clear_mps_cache_after_index=clear_mps_cache_after_index,
     )
 
     sock_path = daemon_socket_path()

{cocoindex_code-0.2.39 → cocoindex_code-0.2.40}/src/cocoindex_code/file_walk.py

@@ -120,6 +120,33 @@ class GitignoreAwareMatcher(FilePathMatcher):
         return self._delegate.is_file_included(path)
 
 
+class SizeLimitedMatcher(FilePathMatcher):
+    """Wraps another matcher and drops files larger than ``max_bytes``.
+
+    The matcher protocol only sees paths relative to the project root, so this
+    resolves each candidate against ``project_root`` to stat it. Files that
+    cannot be stat'd (a broken symlink, a race with a delete) are left to the
+    delegate rather than silently dropped, since a size limit should not be the
+    thing that decides an unreadable file's fate.
+    """
+
+    def __init__(self, delegate: FilePathMatcher, project_root: Path, max_bytes: int) -> None:
+        self._delegate = delegate
+        self._root = project_root
+        self._max_bytes = max_bytes
+
+    def is_dir_included(self, path: PurePath) -> bool:
+        return self._delegate.is_dir_included(path)
+
+    def is_file_included(self, path: PurePath) -> bool:
+        if not self._delegate.is_file_included(path):
+            return False
+        try:
+            return (self._root / path).stat().st_size <= self._max_bytes
+        except OSError:
+            return True
+
+
 def find_git_root(start: Path) -> Path | None:
     """Walk up from ``start`` to the nearest directory holding a ``.git`` entry — a
     directory for a normal repo, or a *file* for a submodule or linked worktree.
@@ -140,14 +167,21 @@ def build_matcher(
     project_root: Path,
     included_patterns: list[str],
     excluded_patterns: list[str],
+    max_file_size: int | None = None,
 ) -> FilePathMatcher:
     """Build the project's file matcher: include/exclude globs plus nested
-    ``.gitignore`` awareness anchored at ``project_root``."""
+    ``.gitignore`` awareness anchored at ``project_root``, and an optional
+    ``max_file_size`` cap in bytes."""
     base_matcher = PatternFilePathMatcher(
         included_patterns=included_patterns,
         excluded_patterns=excluded_patterns,
     )
-    return GitignoreAwareMatcher(base_matcher, load_gitignore_spec(project_root), project_root)
+    matcher: FilePathMatcher = GitignoreAwareMatcher(
+        base_matcher, load_gitignore_spec(project_root), project_root
+    )
+    if max_file_size is not None:
+        matcher = SizeLimitedMatcher(matcher, project_root, max_file_size)
+    return matcher
 
 
 def iter_included_files(

{cocoindex_code-0.2.39 → cocoindex_code-0.2.40}/src/cocoindex_code/grep.py

@@ -214,17 +214,19 @@ def _iter_targets(req: GrepRequest, compiler: _PatternCompiler) -> Iterator[_Tar
     if project_root is not None:
         ps = load_project_settings(project_root)
         included, excluded = ps.include_patterns, ps.exclude_patterns
+        max_file_size = ps.max_file_size
         ext_overrides = {f".{lo.ext}": lo.lang for lo in ps.language_overrides}
         base = project_root
     else:
         included = list(DEFAULT_INCLUDED_PATTERNS)
         excluded = list(DEFAULT_EXCLUDED_PATTERNS)
         ext_overrides = {}
+        max_file_size = None
         # Anchor at the enclosing git repo so grepping a subdirectory still honors the
         # repo-root (and intervening) .gitignore; fall back to the target dir itself.
         base = find_git_root(root) or root
 
-    matcher = build_matcher(base, included, excluded)
+    matcher = build_matcher(base, included, excluded, max_file_size)
     path_filter = (
         PatternFilePathMatcher(included_patterns=[req.path_glob]) if req.path_glob else None
     )

{cocoindex_code-0.2.39 → cocoindex_code-0.2.40}/src/cocoindex_code/indexer.py

@@ -110,7 +110,9 @@ async def indexer_main() -> None:
         ),
     )
 
-    matcher = build_matcher(project_root, ps.include_patterns, ps.exclude_patterns)
+    matcher = build_matcher(
+        project_root, ps.include_patterns, ps.exclude_patterns, ps.max_file_size
+    )
 
     files = localfs.walk_dir(
         CODEBASE_DIR,

{cocoindex_code-0.2.39 → cocoindex_code-0.2.40}/src/cocoindex_code/project.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import logging
 import sqlite3
 from collections.abc import AsyncIterator, Callable
 from pathlib import Path
@@ -39,15 +40,21 @@ from .shared import (
     QUERY_EMBED_PARAMS,
     SQLITE_DB,
     Embedder,
+    clear_mps_allocator_cache,
 )
 
+logger = logging.getLogger(__name__)
+
 
 class Project:
     _env: coco.Environment
     _app: coco.App[[], None]
     _project_root: Path
     _index_lock: asyncio.Lock
+    _clear_mps_cache_after_index: bool
     _initial_index_done: asyncio.Event
+    _initial_index_task: asyncio.Task[None] | None
+    _initial_index_started: asyncio.Event | None
     _indexing_stats: IndexingProgress | None = None
 
     def close(self) -> None:
@@ -67,13 +74,15 @@ class Project:
         on_progress: Callable[[IndexingProgress], None] | None = None,
         on_started: asyncio.Event | None = None,
     ) -> None:
-        """Acquire the index lock, run indexing, and release.
+        """Acquire the project lock, run indexing, and release it.
 
-        If *on_started* is provided, it is set once the lock is acquired
-        (i.e. indexing has truly begun).  On completion (success or failure)
-        ``_initial_index_done`` is set.
+        If *on_started* is provided, it is set once the project lock is
+        acquired. On completion (success or failure) ``_initial_index_done``
+        is set.
         """
         async with self._index_lock:
+            if on_started is not None:
+                on_started.set()
             self._indexing_stats = IndexingProgress(
                 num_execution_starts=0,
                 num_unchanged=0,
@@ -82,8 +91,6 @@ class Project:
                 num_reprocesses=0,
                 num_errors=0,
             )
-            if on_started is not None:
-                on_started.set()
             await self._run_index_inner(on_progress=on_progress)
 
     async def _run_index_inner(
@@ -109,20 +116,32 @@ class Project:
                         on_progress(progress)
                     await asyncio.sleep(0.1)
         finally:
-            self._initial_index_done.set()
-            self._indexing_stats = None
+            try:
+                if self._clear_mps_cache_after_index:
+                    try:
+                        await clear_mps_allocator_cache()
+                    except Exception:
+                        logger.exception("Unable to clear the MPS allocator cache after indexing")
+            finally:
+                self._initial_index_done.set()
+                self._indexing_stats = None
 
     async def ensure_indexing_started(self) -> None:
-        """Kick off background indexing and wait until it has actually started.
+        """Kick off background indexing and wait until it is active or queued.
 
-        Returns once the indexing task holds the lock.  Safe to call multiple
-        times — only the first call spawns a task; subsequent calls return
-        immediately.
+        Returns once the indexing task holds the project lock. Safe to call
+        multiple times — only the first call spawns a task; subsequent calls
+        return immediately.
         """
         if self._initial_index_done.is_set() or self._index_lock.locked():
             return
-        started = asyncio.Event()
-        asyncio.create_task(self.run_index(on_started=started))
+        if self._initial_index_task is None or self._initial_index_task.done():
+            self._initial_index_started = asyncio.Event()
+            self._initial_index_task = asyncio.create_task(
+                self.run_index(on_started=self._initial_index_started)
+            )
+        started = self._initial_index_started
+        assert started is not None
         await started.wait()
 
     async def stream_index(self) -> AsyncIterator[IndexStreamResponse]:
@@ -263,6 +282,7 @@ class Project:
         indexing_params: dict[str, Any],
         query_params: dict[str, Any],
         chunker_registry: dict[str, ChunkerFn] | None = None,
+        clear_mps_cache_after_index: bool = False,
     ) -> Project:
         """Create a project with explicit embedder and per-call params.
 
@@ -281,6 +301,8 @@ class Project:
             chunker_registry: Optional mapping of file suffix (e.g. ``".toml"``)
                 to a ``ChunkerFn``. When a suffix matches, the registered
                 chunker is called instead of the built-in splitter.
+            clear_mps_cache_after_index: Whether to release unused MPS allocator
+                memory in CocoIndex's GPU subprocess after each index run.
         """
         settings_dir = project_root / ".cocoindex_code"
         settings_dir.mkdir(parents=True, exist_ok=True)
@@ -315,5 +337,8 @@ class Project:
         result._app = app
         result._project_root = project_root
         result._index_lock = asyncio.Lock()
+        result._clear_mps_cache_after_index = clear_mps_cache_after_index
         result._initial_index_done = asyncio.Event()
+        result._initial_index_task = None
+        result._initial_index_started = None
         return result

{cocoindex_code-0.2.39 → cocoindex_code-0.2.40}/src/cocoindex_code/server.py

@@ -14,9 +14,10 @@ import json
 import os
 from pathlib import Path
 
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
 from pydantic import BaseModel, Field
 
+from ._version import __version__
 from .settings import DaemonSettings, load_user_settings
 
 _MCP_INSTRUCTIONS = (
@@ -58,9 +59,9 @@ class SearchResultModel(BaseModel):
 # === Daemon-backed MCP server factory ===
 
 
-def create_mcp_server(project_root: str) -> FastMCP:
+def create_mcp_server(project_root: str) -> MCPServer:
     """Create a lightweight MCP server that delegates to the daemon."""
-    mcp = FastMCP("cocoindex-code", instructions=_MCP_INSTRUCTIONS)
+    mcp = MCPServer("cocoindex-code", instructions=_MCP_INSTRUCTIONS, version=__version__)
 
     @mcp.tool(
         name="search",
@@ -174,24 +175,27 @@ def heartbeat_interval_s(idle_timeout_minutes: int) -> int:
 
 async def run_heartbeat_loop() -> None:
     """Periodically heartbeat the daemon so it never idle-exits under this
-    live MCP session; when this process dies (even SIGKILL) the heartbeats
-    stop and the daemon exits on its normal idle timeout.
+    live MCP session when ``daemon.keep_alive_with_mcp`` is enabled. When the
+    option is disabled, the daemon may idle-exit and the next real request
+    restarts it transparently. When this process dies (even SIGKILL), the
+    heartbeats stop and the daemon exits on its normal idle timeout.
 
     Reads the timeout from the same ``global_settings.yml`` the daemon reads
     (dataclass default when the file is missing or invalid). Returns
-    immediately when the timeout is 0 (daemon never idle-exits). The
-    heartbeat itself never starts or restarts a daemon — see
-    ``client.send_heartbeat``.
+    immediately when the timeout is 0 (daemon never idle-exits) or MCP
+    keep-alive is disabled. The heartbeat itself never starts or restarts a
+    daemon — see ``client.send_heartbeat``.
     """
-    from .client import send_heartbeat
-
     try:
-        timeout_minutes = load_user_settings().daemon.idle_timeout_minutes
+        daemon_settings = load_user_settings().daemon
     except (FileNotFoundError, ValueError):
-        timeout_minutes = DaemonSettings().idle_timeout_minutes
-    if timeout_minutes <= 0:
+        daemon_settings = DaemonSettings()
+    timeout_minutes = daemon_settings.idle_timeout_minutes
+    if timeout_minutes <= 0 or not daemon_settings.keep_alive_with_mcp:
         return
 
+    from .client import send_heartbeat
+
     interval = heartbeat_interval_s(timeout_minutes)
     loop = asyncio.get_event_loop()
     while True:
@@ -201,7 +205,7 @@ async def run_heartbeat_loop() -> None:
 
 
 # Keep the old `mcp` global for backward compatibility in __init__.py
-mcp: FastMCP | None = None
+mcp: MCPServer | None = None
 
 
 # === Backward-compatible entry point ===

{cocoindex_code-0.2.39 → cocoindex_code-0.2.40}/src/cocoindex_code/settings.py

@@ -98,18 +98,38 @@ class EmbeddingSettings:
     provider: str = "litellm"
     device: str | None = None
     min_interval_ms: int | None = None
+    # PyTorch MPS allocator limits used by CocoIndex's isolated GPU runner.
+    mps_low_watermark_ratio: float = 0.4
+    mps_high_watermark_ratio: float = 0.5
     # Extra kwargs spread into ``embedder.embed()`` during indexing/query.
     # ``None`` means the user did not set the key; ``{}`` is an explicit empty
     # dict (used to opt out of the legacy-bridge warning).
     indexing_params: dict[str, Any] | None = None
     query_params: dict[str, Any] | None = None
 
+    def __post_init__(self) -> None:
+        ratios = (
+            ("mps_low_watermark_ratio", self.mps_low_watermark_ratio),
+            ("mps_high_watermark_ratio", self.mps_high_watermark_ratio),
+        )
+        for name, value in ratios:
+            if isinstance(value, bool) or not 0 < value <= 1:
+                raise ValueError(f"embedding.{name} must be greater than 0 and at most 1")
+
+        if self.mps_low_watermark_ratio > self.mps_high_watermark_ratio:
+            raise ValueError(
+                "embedding.mps_low_watermark_ratio must be at most "
+                "embedding.mps_high_watermark_ratio"
+            )
+
 
 @dataclass
 class DaemonSettings:
     # Minutes without client activity before the daemon exits (0 = never exit).
     # Clients auto-restart the daemon on the next request, so exiting is cheap.
     idle_timeout_minutes: int = 180
+    # Keep the daemon warm while a long-lived MCP client is connected.
+    keep_alive_with_mcp: bool = True
 
 
 @dataclass
@@ -137,6 +157,8 @@ class ProjectSettings:
     exclude_patterns: list[str] = field(default_factory=lambda: list(DEFAULT_EXCLUDED_PATTERNS))
     language_overrides: list[LanguageOverride] = field(default_factory=list)
     chunkers: list[ChunkerMapping] = field(default_factory=list)
+    #: Files larger than this many bytes are excluded. ``None`` means no limit.
+    max_file_size: int | None = None
 
 
 # ---------------------------------------------------------------------------
@@ -430,6 +452,11 @@ def _embedding_settings_to_dict(embedding: EmbeddingSettings) -> dict[str, Any]:
         d["device"] = embedding.device
     if embedding.min_interval_ms is not None:
         d["min_interval_ms"] = embedding.min_interval_ms
+    defaults = EmbeddingSettings(model=embedding.model)
+    if embedding.mps_low_watermark_ratio != defaults.mps_low_watermark_ratio:
+        d["mps_low_watermark_ratio"] = embedding.mps_low_watermark_ratio
+    if embedding.mps_high_watermark_ratio != defaults.mps_high_watermark_ratio:
+        d["mps_high_watermark_ratio"] = embedding.mps_high_watermark_ratio
     if embedding.indexing_params is not None:
         d["indexing_params"] = dict(embedding.indexing_params)
     if embedding.query_params is not None:
@@ -441,8 +468,14 @@ def _user_settings_to_dict(settings: UserSettings) -> dict[str, Any]:
     d: dict[str, Any] = {"embedding": _embedding_settings_to_dict(settings.embedding)}
     if settings.envs:
         d["envs"] = dict(settings.envs)
-    if settings.daemon != DaemonSettings():
-        d["daemon"] = {"idle_timeout_minutes": settings.daemon.idle_timeout_minutes}
+    daemon_defaults = DaemonSettings()
+    daemon_dict: dict[str, Any] = {}
+    if settings.daemon.idle_timeout_minutes != daemon_defaults.idle_timeout_minutes:
+        daemon_dict["idle_timeout_minutes"] = settings.daemon.idle_timeout_minutes
+    if settings.daemon.keep_alive_with_mcp != daemon_defaults.keep_alive_with_mcp:
+        daemon_dict["keep_alive_with_mcp"] = settings.daemon.keep_alive_with_mcp
+    if daemon_dict:
+        d["daemon"] = daemon_dict
     return d
 
 
@@ -458,6 +491,10 @@ def _user_settings_from_dict(d: dict[str, Any]) -> UserSettings:
         emb_kwargs["device"] = emb_dict["device"]
     if "min_interval_ms" in emb_dict:
         emb_kwargs["min_interval_ms"] = emb_dict["min_interval_ms"]
+    if "mps_low_watermark_ratio" in emb_dict:
+        emb_kwargs["mps_low_watermark_ratio"] = float(emb_dict["mps_low_watermark_ratio"])
+    if "mps_high_watermark_ratio" in emb_dict:
+        emb_kwargs["mps_high_watermark_ratio"] = float(emb_dict["mps_high_watermark_ratio"])
     # indexing_params / query_params: missing → None (dataclass default);
     # present-but-null → {} (treat the same as an empty dict, since both mean
     # "user acknowledged the key and wants no extra kwargs").
@@ -472,15 +509,66 @@ def _user_settings_from_dict(d: dict[str, Any]) -> UserSettings:
     daemon_kwargs: dict[str, Any] = {}
     if "idle_timeout_minutes" in daemon_dict:
         daemon_kwargs["idle_timeout_minutes"] = int(daemon_dict["idle_timeout_minutes"])
+    if "keep_alive_with_mcp" in daemon_dict:
+        keep_alive_with_mcp = daemon_dict["keep_alive_with_mcp"]
+        if not isinstance(keep_alive_with_mcp, bool):
+            raise ValueError("daemon.keep_alive_with_mcp must be a boolean")
+        daemon_kwargs["keep_alive_with_mcp"] = keep_alive_with_mcp
     daemon = DaemonSettings(**daemon_kwargs)
     return UserSettings(embedding=embedding, envs=envs, daemon=daemon)
 
 
+_SIZE_UNITS: dict[str, int] = {
+    "B": 1,
+    "KB": 1024,
+    "MB": 1024**2,
+    "GB": 1024**3,
+}
+
+
+def parse_file_size(value: Any) -> int:
+    """Parse a ``max_file_size`` value into bytes.
+
+    Accepts a plain number of bytes (``1048576``) or a string with an optional
+    unit suffix (``500KB``, ``1.5 MB``, ``2048``). Units are binary (1KB = 1024
+    bytes) and case-insensitive.
+    """
+    if isinstance(value, bool):  # bool is an int subclass; reject it explicitly.
+        raise ValueError(f"invalid max_file_size: {value!r}")
+    if isinstance(value, int):
+        size = value
+    elif isinstance(value, float):
+        size = int(value)
+    elif isinstance(value, str):
+        text = value.strip().upper()
+        if not text:
+            raise ValueError("invalid max_file_size: empty value")
+        for suffix in ("GB", "MB", "KB", "B"):
+            if text.endswith(suffix):
+                number = text[: -len(suffix)].strip()
+                multiplier = _SIZE_UNITS[suffix]
+                break
+        else:
+            number, multiplier = text, 1
+        try:
+            size = int(float(number) * multiplier)
+        except ValueError as exc:
+            raise ValueError(f"invalid max_file_size: {value!r}") from exc
+    else:
+        raise ValueError(f"invalid max_file_size: {value!r}")
+
+    if size <= 0:
+        raise ValueError(f"max_file_size must be positive, got {value!r}")
+    return size
+
+
 def _project_settings_to_dict(settings: ProjectSettings) -> dict[str, Any]:
     d: dict[str, Any] = {
         "include_patterns": settings.include_patterns,
         "exclude_patterns": settings.exclude_patterns,
     }
+    if settings.max_file_size is not None:
+        d["max_file_size"] = settings.max_file_size
     if settings.language_overrides:
         d["language_overrides"] = [
             {"ext": lo.ext, "lang": lo.lang} for lo in settings.language_overrides
@@ -495,11 +583,14 @@ def _project_settings_from_dict(d: dict[str, Any]) -> ProjectSettings:
         LanguageOverride(ext=lo["ext"], lang=lo["lang"]) for lo in d.get("language_overrides", [])
     ]
     chunkers = [ChunkerMapping(ext=cm["ext"], module=cm["module"]) for cm in d.get("chunkers", [])]
+    raw_max_size = d.get("max_file_size")
+    max_file_size = None if raw_max_size is None else parse_file_size(raw_max_size)
     return ProjectSettings(
         include_patterns=d.get("include_patterns", list(DEFAULT_INCLUDED_PATTERNS)),
         exclude_patterns=d.get("exclude_patterns", list(DEFAULT_EXCLUDED_PATTERNS)),
         language_overrides=overrides,
         chunkers=chunkers,
+        max_file_size=max_file_size,
     )
 
 
@@ -573,6 +664,13 @@ _PARAMS_COMMENT_BY_PROVIDER: dict[str, str] = {
     ),
 }
 
+_MPS_SAFETY_COMMENT = (
+    "  #\n"
+    "  # Apple Silicon MPS allocator limits for CocoIndex's GPU subprocess.\n"
+    "  # mps_low_watermark_ratio: 0.4\n"
+    "  # mps_high_watermark_ratio: 0.5\n"
+)
+
 
 def save_initial_user_settings(
     embedding: EmbeddingSettings,
@@ -595,6 +693,8 @@ def save_initial_user_settings(
         sort_keys=False,
     )
     content = _INITIAL_HEADER + emb_block
+    if embedding.provider == "sentence-transformers":
+        content += _MPS_SAFETY_COMMENT
     if not defaults_applied:
         hint = _PARAMS_COMMENT_BY_PROVIDER.get(embedding.provider)
         if hint is not None:

{cocoindex_code-0.2.39 → cocoindex_code-0.2.40}/src/cocoindex_code/shared.py

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 import importlib.util
 import logging
+import os
 import pathlib
+import sys
 import traceback as _tb
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Annotated, Any, NamedTuple, Union
@@ -26,7 +28,10 @@ SBERT_PREFIX = "sbert/"
 DEFAULT_LITELLM_MIN_INTERVAL_MS = 5
 
 # Type alias
-Embedder = Union["SentenceTransformerEmbedder", "LiteLLMEmbedder"]
+Embedder = Union[
+    "SentenceTransformerEmbedder",
+    "LiteLLMEmbedder",
+]
 
 # Context keys
 EMBEDDER = coco.ContextKey[Embedder]("embedder", detect_change=True)
@@ -45,6 +50,46 @@ def is_sentence_transformers_installed() -> bool:
     return importlib.util.find_spec("sentence_transformers") is not None
 
 
+def configure_mps_environment(settings: EmbeddingSettings) -> bool:
+    """Install MPS safety defaults before CocoIndex's first GPU invocation.
+
+    CocoIndex reads ``COCOINDEX_RUN_GPU_IN_SUBPROCESS`` lazily on the first
+    ``coco.GPU`` call, while PyTorch reads the allocator watermarks when the
+    child initializes MPS. Explicit user environment variables always win.
+
+    Returns whether this embedding configuration uses the guarded MPS path.
+    """
+
+    use_mps = settings.provider == "sentence-transformers" and (
+        settings.device == "mps" or (settings.device is None and sys.platform == "darwin")
+    )
+    if not use_mps:
+        return False
+
+    os.environ.setdefault("COCOINDEX_RUN_GPU_IN_SUBPROCESS", "1")
+    os.environ.setdefault("PYTORCH_MPS_LOW_WATERMARK_RATIO", str(settings.mps_low_watermark_ratio))
+    os.environ.setdefault(
+        "PYTORCH_MPS_HIGH_WATERMARK_RATIO", str(settings.mps_high_watermark_ratio)
+    )
+    return os.environ.get("COCOINDEX_RUN_GPU_IN_SUBPROCESS") == "1"
+
+
+@coco.fn.as_async(runner=coco.GPU)
+def clear_mps_allocator_cache() -> None:
+    """Release unused MPS allocator cache inside CocoIndex's GPU child."""
+
+    import gc
+
+    import torch
+
+    if not torch.backends.mps.is_available():
+        return
+    torch.mps.synchronize()
+    gc.collect()
+    torch.mps.empty_cache()
+    torch.mps.synchronize()
+
+
 class EmbeddingCheckResult(NamedTuple):
     """Outcome of a single embed-test call. See `check_embedding`.
 
@@ -100,6 +145,7 @@ def create_embedder(
     only and the indexing default is supplied at the call site via
     :data:`INDEXING_EMBED_PARAMS`.
     """
+    instance: Embedder
     if settings.provider == "sentence-transformers":
         from cocoindex.ops.sentence_transformers import SentenceTransformerEmbedder
 
@@ -108,7 +154,7 @@ def create_embedder(
         if model_name.startswith(SBERT_PREFIX):
             model_name = model_name[len(SBERT_PREFIX) :]
 
-        instance: Embedder = SentenceTransformerEmbedder(
+        instance = SentenceTransformerEmbedder(
             model_name,
             device=settings.device,
             trust_remote_code=True,