Scubiee

Local Context Engine: Merkle sync → Graphify AST → mix compress → CodeRankEmbed FP16 (MLX on Apple Silicon, FastEmbed CUDA/DirectML/CPU elsewhere) → TurboQuant/FAISS → Conductor R_plan

Install (no git clone)

Requires Python 3.10+. Two steps on a clean machine.

Recommended — uv (fast, isolated CLI; no venv juggling):

uv tool install scubiee
scubiee setup

Upgrade later: uv tool install --force scubiee then scubiee setup --repair.

Note: uv tool upgrade scubiee refreshes dependencies but may not bump the scubiee version — use --force with an explicit version when release notes say to.

Alternative — pip:

pip install -U scubiee
scubiee setup

npm (optional wrapper — installs Python package + runs setup):

npm install -g scubiee

Then scubiee init <repo> (or ctx init) for each codebase, and reload MCP in Cursor (Settings → MCP → refresh).

After uv tool install scubiee, add tools to PATH once per machine:

uv tool update-shell    # restart terminal after
# or one session:  export PATH="$HOME/.local/bin:$PATH"  (Windows: see uv's hint)

scubiee setup picks CUDA (NVIDIA), DirectML (Windows AMD/Intel), MLX FP16 (Apple Silicon Metal), CoreML (Intel Mac), or CPU. On a MacBook, uv tool install scubiee / pip install scubiee pulls FastEmbed, ONNX Runtime, and MLX — no [mlx] / [coreml] extra required. Then scubiee setup (or scubiee setup --repair after an upgrade) writes the MLX FP16 profile. Opt out: CTX_MLX=0 or scubiee setup --profile cpu.

If PyPI is behind GitHub, install the tagged release:

uv tool install "scubiee @ git+https://github.com/Usmansayed/new-context-engine.git@v0.2.6"
scubiee setup

From a git checkout (contributors): uv pip install -e ".[dml]" (or pip install -e .) then scubiee setup. Maintainers: see docs/publish-setup.md.

Use

Inside the engine process there are three managers only:

Manager Role
RuntimeManager Workspace lifecycle, publish search generation after sync, serve queries
IndexManager Merkle probe, full index, incremental sync
ResourceManager CPU/RAM admission and embed batching

A tiny watchdog sidecar (not a manager) polls /health and restarts the daemon if it crashes. Disable: CTX_WATCHDOG=0.

Install-and-forget check (isolated port/home):

.\.venv\Scripts\python.exe -u scripts\sim_install_forget.py

Use

In Cursor: call MCP tools after reload.

CLI (optional):

ctx index .
ctx search "login validate"
ctx sync .
ctx status .

Or: python -m pipeline index .

Default pre-embed compression is mix with a 512-char cap (locked). Opt out: CTX_COMPRESS=off.

Resource management

Indexing and embedding run at the calibrated batch. The resource manager only pauses if free RAM is near empty (default under 256 MB). CPU spikes and Windows “RAM % used” (file cache) do not stop work.

ctx resources              # live pressure + hardware
ctx resources --refresh    # re-detect CPU/RAM/GPU/libs
ctx init                   # also writes hardware.json + picks fastest ORT backend

Disable entirely: CTX_RM_DISABLE=1. Emergency floor: CTX_RM_MIN_FREE_RAM_MB.

Cursor MCP

After install, MCP tools talk to the local Context Engine service (CTX_ENGINE_URL, default http://127.0.0.1:8765). The MCP process auto-starts that service if needed.

Tools: search_code, locate_capability, grep_code, file_outline, status, sync_index, set_repo, register_project.

Dashboard (optional): http://127.0.0.1:8765/dashboard

Advanced (usually unnecessary):

ctx engine status
ctx engine stop
ctx engine run .                   # foreground service

ctx engine start also starts the watchdog sidecar. Logs: ~/.context-engine/watchdog.log.

Registration modes (dashboard or CLI):

Mode Trigger
Automatic (default) IDE/MCP open registers the project once, then incremental indexing
MCP / CLI No auto-init; first tool call returns a consent prompt; use register_project (optional always_allow) or ctx register 
ctx settings --mode automatic
ctx settings --mode mcp_cli
ctx register . --always-allow --fast
ctx serve .   # open http://127.0.0.1:8765/dashboard

On open (automatic): resolves a stable project id, indexes if needed (CTX_AUTO_INDEX=1), then keeps the index fresh every 5 minutes (changed files only — graph patch + embed together).

Project data

Location Role
<repo>/.context-engine/id.json Tiny identity (project_id). Prefer gitignore.
~/.context-engine/prefs.json Registration mode + indexing prefs
~/.context-engine/projects/<project_id>/ Chunks, graph, merkle, embed cache
~/.context-engine/registry.json Maps project_id ↔ paths, registered, always_allow
~/.context-engine/vectordb/ FAISS + TurboQuant collections

Path moved → id file recovers the store. Id file deleted → registry path recovers. Both gone → new id + reindex.

Layout

Path Role
packages/pipeline/ Index, embed, FAISS+TurboQuant, MCP, sync
packages/conductor/ Retrieval fusion (R_plan, etc.)
packages/graphify/ Bundled AST / graph
packages/enrich/, metadata/, repo_ir/ Chunk enrichment
scripts/install* Setup + MCP install
tests/ Unit / integration tests
docs/ Design notes + ship notes

See VENDOR.md and docs/compress-mix-shipped.md.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.54)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for UsmanSayed from gravatar.com UsmanSayed

Requires

Python >=3.10

Provides Extra

cpu coreml dml cuda macos mlx embed-st mcp

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

scubiee-0.2.44.tar.gz (948.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

scubiee-0.2.44-py3-none-any.whl (941.5 kB view details)

Uploaded Python 3

File details

Details for the file scubiee-0.2.44.tar.gz.

File metadata

  • Download URL: scubiee-0.2.44.tar.gz
  • Upload date:
  • Size: 948.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.13.5

File hashes

Hashes for scubiee-0.2.44.tar.gz
Algorithm Hash digest
SHA256 73af060374a83e344794304a009d2211daca400b0552073b7eb2c965ca832fbc
MD5 1c9141aa036fe0a8986146354bddf539
BLAKE2b-256 4abdb7171b1b6bd3171bd076f69f5d3bc2e9c303228fbf60c7ee93acb64b2e0d

See more details on using hashes here.

File details

Details for the file scubiee-0.2.44-py3-none-any.whl.

File metadata

  • Download URL: scubiee-0.2.44-py3-none-any.whl
  • Upload date:
  • Size: 941.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.13.5

File hashes

Hashes for scubiee-0.2.44-py3-none-any.whl
Algorithm Hash digest
SHA256 4b080748134f5652e61489c0ffee8e0547f5ed9bdd5983c6bf0745024c01b428
MD5 0a9e186a6400bcd30e0c473a232c24ae
BLAKE2b-256 1e597c1caba8d4223fd1b9d0fd5e89d4a8d9a1515e0f6ea21ecd770c5cb5e21b

See more details on using hashes here.

Release history Release notifications | RSS feed

0.2.54

2 files

0.2.53

2 files

0.2.52

2 files

0.2.51

2 files

0.2.50

2 files

0.2.49

2 files

0.2.48

2 files

0.2.47

2 files

0.2.46

2 files

0.2.45

2 files

This release

0.2.44 This release

2 files

0.2.43

2 files

0.2.42

2 files

0.2.41

2 files

0.2.40

2 files

0.2.39

2 files

0.2.38

2 files

0.2.37

2 files

0.2.36

2 files

0.2.35

2 files

0.2.34

2 files

0.2.33

2 files

0.2.32

2 files

0.2.31

2 files

0.2.30

2 files

0.2.29

2 files

0.2.28

2 files

0.2.27

2 files

0.2.26

2 files

0.2.25

2 files

0.2.24

2 files

0.2.23

2 files

0.2.22

2 files

0.2.21

2 files

0.2.20

2 files

0.2.19

2 files

0.2.18

2 files

0.2.17

2 files

0.2.16

2 files

0.2.15

2 files

0.2.14

2 files

0.2.13

2 files

0.2.12

2 files

0.2.11

2 files

0.2.10

2 files

0.2.9

2 files

0.2.7

2 files

0.2.6

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page