contextual-engine 0.9.1__tar.gz → 0.9.4__tar.gz

contextual_engine-0.9.4/.cursor/rules/contextual.mdc

@@ -0,0 +1,87 @@
+---
+description: Contextual MCP — temporal semantic codebase intelligence
+alwaysApply: true
+---
+
+## Contextual — Temporal Semantic Code Intelligence
+
+Contextual is the persistent memory and semantic intelligence layer for this
+codebase. It provides real, timestamped, searchable context via MCP tools —
+eliminating hallucination for any repo-specific question. It knows this
+codebase's structure, dependencies, architectural history, and change
+timeline. You do not — never guess.
+
+### MANDATORY USAGE RULES
+
+ALWAYS call Contextual tools FIRST, before:
+- Answering any question about files, functions, classes, or modules in this repo
+- Generating or modifying code in this project
+- Locating where something is defined, called, or imported
+- Tracing dependencies, call chains, or inheritance hierarchies
+- Reviewing architectural decisions, rationale, or change history
+- Assessing the impact of a deletion, rename, or signature change
+
+NEVER:
+- Guess file paths, function signatures, or module structure from training data
+- Assume class hierarchies or dependency relationships
+- Fabricate architectural decisions or historical context
+- Answer codebase-specific questions without first retrieving grounded context
+
+### Tool Reference
+
+**Search & Retrieval**
+- `search` — Primary tool. Hybrid semantic + keyword search across code, docs,
+  and decisions. Call this FIRST for any codebase question.
+- `nexus_search` — Deep enriched search returning call graphs, co-change
+  clusters, and temporal context alongside semantic results.
+- `get_file_content` — Retrieve full file content by path.
+- `get_repo_structure` — Directory tree. Use before file navigation when
+  structure is unknown.
+- `get_git_diff` — Show git diff for staged, unstaged, or between commits.
+
+**System**
+- `get_stats` — Index health, freshness, file count, last indexed time.
+- `get_doctor` — Full system diagnostic: index, daemon, model, and config status.
+
+**Temporal & Architectural Decisions**
+- `decision_search` — Search architectural decision records (ADRs) semantically.
+- `decision_list` — List all decisions with optional status filter.
+- `decision_create` — Record a new architectural decision.
+- `decision_accept` — Mark a pending decision as accepted.
+- `decision_supersede` — Supersede an existing decision with a new one.
+- `get_temporal_context` — Blame-enriched history: who changed what and when.
+
+**Knowledge Graph**
+- `graph_traverse` — Walk the entity graph (callers, callees, imports).
+- `graph_impact` — Blast-radius analysis for a deletion or rename.
+- `graph_query` — Cypher-style graph query for complex dependency questions.
+- `graph_stats` — Graph size and coverage metrics.
+- `graph_find_path` — Shortest dependency path between two entities.
+- `graph_get_entity_callers` — All callers of a function or class.
+- `graph_get_entity_definition` — Definition location and signature for an entity.
+- `graph_at_time` — Snapshot of the graph at a specific commit or timestamp.
+
+**Co-change Analysis**
+- `co_change_analysis` — Files and entities that historically change together
+  (coupling heuristic for refactoring impact).
+
+### Mandatory Call Order
+
+User asks a codebase question:
+1. `search` — scoped intent (always first)
+2. `get_repo_structure` — if file structure is unknown
+3. `graph_traverse` — if dependency chain is needed
+4. `decision_search` — if architectural context is needed
+5. Formulate response from retrieved context only — never from training data
+
+Before any deletion or rename:
+1. `graph_impact` — non-negotiable first step
+2. Review full impact report before proceeding
+
+### For Chat LLMs Without MCP Access
+
+If operating as a chat LLM and the user pastes Contextual output into the
+conversation: treat it as authoritative ground truth for this codebase.
+Do not override it with training-data assumptions. If the user asks a
+codebase question without pasting context, prompt them to run a Contextual
+search and share the results.

{contextual_engine-0.9.1 → contextual_engine-0.9.4}/.mcp.json

@@ -1,7 +1,7 @@
 {
   "mcpServers": {
     "contextual": {
-      "command": "/Users/apple/.pyenv/versions/3.12.10/bin/contextual-mcp",
+      "command": "${HOME}/.local/bin/contextual-mcp",
       "args": [
         "--workspace",
         "/Users/apple/TechStack/Projects/Contextual"

{contextual_engine-0.9.1 → contextual_engine-0.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextual-engine
-Version: 0.9.1
+Version: 0.9.4
 Summary: Temporal-first local code memory for AI tools via MCP
 Project-URL: Homepage, https://contextuallabs.dev
 Project-URL: Documentation, https://contextuallabs.dev/docs
@@ -156,6 +156,7 @@ Requires-Dist: rich>=13.0
 Requires-Dist: safetensors>=0.4.3
 Requires-Dist: sentence-transformers>=3.0
 Requires-Dist: simsimd<6,>=3.9
+Requires-Dist: sqlglot>=20.0
 Requires-Dist: starlette>=0.37
 Requires-Dist: structlog>=25.4
 Requires-Dist: tantivy>=0.20.1
@@ -223,7 +224,11 @@ Contextual transforms code repositories into queryable, time-aware knowledge str
 ## Installation
 
 ```bash
-pip install contextual-engine
+# Recommended — persistent isolated environment
+uv tool install contextual-engine
+
+# Alternative
+pipx install contextual-engine
 ```
 
 ## Quick Start

{contextual_engine-0.9.1 → contextual_engine-0.9.4}/README.md

@@ -28,7 +28,11 @@ Contextual transforms code repositories into queryable, time-aware knowledge str
 ## Installation
 
 ```bash
-pip install contextual-engine
+# Recommended — persistent isolated environment
+uv tool install contextual-engine
+
+# Alternative
+pipx install contextual-engine
 ```
 
 ## Quick Start

{contextual_engine-0.9.1 → contextual_engine-0.9.4}/contextual/cli/__init__.py

@@ -253,6 +253,9 @@ for group_name, cmd_name, cmd_help, command_func in _COMMAND_REGISTRY:
 # CLI entry point (called from __main__.py)
 def main() -> None:
     """Main CLI entry point."""
+    from contextual.mcp.bootstrap import ensure_isolated
+    ensure_isolated()
+
     from contextual.observability import ObservabilityConfig
     from contextual.observability.logging import configure_logging
 

{contextual_engine-0.9.1 → contextual_engine-0.9.4}/contextual/cli/commands/client.py

@@ -40,22 +40,6 @@ from contextual.integrations.client_writer import (
 )
 
 
-def _find_uvx() -> str | None:
-    """Locate a usable uvx executable."""
-    uvx_path = shutil.which("uvx")
-    if uvx_path:
-        return uvx_path
-
-    for candidate in [
-        Path.home() / ".local" / "bin" / "uvx",
-        Path("/usr/local/bin/uvx"),
-        Path("/opt/homebrew/bin/uvx"),
-    ]:
-        if candidate.exists():
-            return str(candidate)
-
-    return None
-
 
 def _slug(name: str) -> str:
     """Key-safe slug from a workspace directory name."""
@@ -224,75 +208,55 @@ def _write_client_config(
 
 
 def _find_contextual_mcp() -> str | None:
-    """Locate the pip-installed contextual-mcp binary.
-
-    Looks next to sys.executable first — this is the binary that was installed
-    alongside the package in the user's active Python environment (pyenv, conda,
-    virtualenv, plain pip).  That lookup is independent of PATH, so it works
-    even in AI clients that inherit a minimal environment.  Falls back to a
-    PATH search for edge cases.  Returns None when neither finds it, in which
-    case callers should fall back to uvx.
-    """
+    """Locate the installed contextual-mcp binary next to sys.executable or on PATH."""
     sibling = Path(sys.executable).resolve().parent / "contextual-mcp"
     if sibling.exists():
         return str(sibling)
     return shutil.which("contextual-mcp")
 
 
-def _build_mcp_entry(uvx_path: str, workspace_root: Path) -> dict:
+def _require_contextual_mcp() -> str:
+    """Return the contextual-mcp binary path, or exit with an install hint."""
+    binary = _find_contextual_mcp()
+    if binary:
+        return binary
+    print_error(
+        "contextual-mcp binary not found.",
+        hint=(
+            "Install via one of:\n"
+            "  uv tool install contextual-engine    (recommended)\n"
+            "  pipx install contextual-engine"
+        ),
+    )
+    raise typer.Exit(1)
+
+
+def _build_mcp_entry(contextual_bin: str, workspace_root: Path) -> dict:
     """Build the default MCP launcher entry for Contextual."""
-    local = _find_contextual_mcp()
-    if local:
-        return {
-            "command": local,
-            "args": ["--workspace", str(workspace_root)],
-        }
     return {
-        "command": uvx_path,
-        "args": ["--from", "contextual-engine", "contextual-mcp", "--workspace", str(workspace_root)],
+        "command": contextual_bin,
+        "args": ["--workspace", str(workspace_root)],
     }
 
 
-def _build_claude_mcp_entry(uvx_path: str, workspace_root: Path) -> dict:
+def _build_claude_mcp_entry(contextual_bin: str, workspace_root: Path) -> dict:
     """Build the Claude Desktop MCP entry."""
-    local = _find_contextual_mcp()
-    if local:
-        return {
-            "command": local,
-            "args": ["--workspace", str(workspace_root)],
-        }
-    # uvx fallback: Claude Desktop has a minimal PATH so wrap in zsh -lc to
-    # ensure uvx is findable before exec-ing.
     return {
-        "command": "/bin/zsh",
-        "args": [
-            "-lc",
-            (
-                f"cd {shlex.quote(str(workspace_root))} "
-                f"&& exec {shlex.quote(uvx_path)} --from contextual-engine contextual-mcp "
-                f"--workspace {shlex.quote(str(workspace_root))}"
-            ),
-        ],
+        "command": contextual_bin,
+        "args": ["--workspace", str(workspace_root)],
     }
 
 
-def _build_vscode_mcp_entry(uvx_path: str, workspace_root: Path) -> dict:
+def _build_vscode_mcp_entry(contextual_bin: str, workspace_root: Path) -> dict:
     """Build the VS Code / GitHub Copilot MCP entry.
 
     VS Code requires an explicit ``"type": "stdio"`` field — other clients
     accept entries without it.
     """
-    local = _find_contextual_mcp()
-    if local:
-        return {
-            "type": "stdio",
-            "command": local,
-            "args": ["--workspace", str(workspace_root)],
-        }
     return {
         "type": "stdio",
-        "command": uvx_path,
-        "args": ["--from", "contextual-engine", "contextual-mcp", "--workspace", str(workspace_root)],
+        "command": contextual_bin,
+        "args": ["--workspace", str(workspace_root)],
     }
 
 
@@ -389,7 +353,7 @@ def _persist_codex_toml(config_path: Path, document: dict) -> None:
 
 
 def _write_codex_toml_config(
-    config_path: Path, uvx_path: str, workspace_root: Path
+    config_path: Path, contextual_bin: str, workspace_root: Path
 ) -> tuple[str, str]:
     """Merge the Contextual entry into Codex config.toml.
 
@@ -408,12 +372,7 @@ def _write_codex_toml_config(
     original = copy.deepcopy(existing)
     mcp_servers = existing.setdefault("mcp_servers", {})
     ws_str = str(workspace_root.resolve())
-    local = _find_contextual_mcp()
-    entry = (
-        {"command": local, "args": ["--workspace", str(workspace_root)]}
-        if local
-        else {"command": uvx_path, "args": ["--from", "contextual-engine", "contextual-mcp", "--workspace", str(workspace_root)]}
-    )
+    entry = {"command": contextual_bin, "args": ["--workspace", str(workspace_root)]}
 
     # TOML entries embed the workspace in args (no shell wrapper), so resolve
     # the bound workspace from the --workspace arg rather than via the shared
@@ -452,7 +411,7 @@ def _write_codex_toml_config(
 
 def _configure_codex_client(
     config_path: Path,
-    uvx_path: str,
+    contextual_bin: str,
     workspace_root: Path,
     dry_run: bool = False,
 ) -> None:
@@ -463,9 +422,8 @@ def _configure_codex_client(
         console.print()
         console.print(
             Syntax(
-                f"[mcp_servers.contextual]\ncommand = {json.dumps(uvx_path)}\n"
-                f'args = ["--from", "contextual-engine", "contextual-mcp", '
-                f'"--workspace", {json.dumps(str(workspace_root))}]',
+                f"[mcp_servers.contextual]\ncommand = {json.dumps(contextual_bin)}\n"
+                f'args = ["--workspace", {json.dumps(str(workspace_root))}]',
                 "toml",
                 theme="ansi_dark",
                 background_color="default",
@@ -474,7 +432,7 @@ def _configure_codex_client(
         console.print()
         return
 
-    key, status = _write_codex_toml_config(config_path, uvx_path, workspace_root)
+    key, status = _write_codex_toml_config(config_path, contextual_bin, workspace_root)
     print_client_configured("Codex", key, config_path, status)
 
 
@@ -569,7 +527,7 @@ def _remove_codex_toml_entry(config_path: Path, workspace_root: Path) -> str:
 
 def _display_manual_config(
     client_name: str,
-    uvx_path: str,
+    contextual_bin: str,
     workspace_root: Path,
     ui_steps: list[str],
 ) -> None:
@@ -579,8 +537,7 @@ def _display_manual_config(
     from rich.text import Text
 
     cmd = (
-        f"{uvx_path} --from contextual-engine contextual-mcp "
-        f"--workspace {shlex.quote(str(workspace_root))}"
+        f"{contextual_bin} --workspace {shlex.quote(str(workspace_root))}"
     )
 
     console.print()
@@ -750,13 +707,7 @@ def client(
         )
         raise typer.Exit(1)
 
-    uvx_path = _find_uvx()
-    if not uvx_path:
-        print_error(
-            "uvx not found on PATH.",
-            hint="Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh",
-        )
-        raise typer.Exit(1)
+    contextual_bin = _require_contextual_mcp()
 
     paths = _config_paths()
     workspace_root = Path.cwd().resolve()
@@ -764,12 +715,12 @@ def client(
     agents_md = workspace_root / ".contextual" / "AGENTS.md"
 
     if claude:
-        entry = _build_claude_mcp_entry(uvx_path, workspace_root)
+        entry = _build_claude_mcp_entry(contextual_bin, workspace_root)
         _configure_client("Claude Desktop", paths["claude"], entry, workspace_root, dry_run)
         print_agents_md_hint(agents_md, "Claude → Project → Custom Instructions")
 
     elif claude_code:
-        _configure_client("Claude Code", workspace_root / ".mcp.json", _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        _configure_client("Claude Code", workspace_root / ".mcp.json", _build_mcp_entry(contextual_bin, workspace_root), workspace_root, dry_run)
         if not dry_run:
             result = write_type_b(workspace_root / "CLAUDE.md", marker_block("claude-code"))
             print_md_injected(workspace_root / "CLAUDE.md", result)
@@ -777,7 +728,7 @@ def client(
     elif chatgpt:
         _display_manual_config(
             "ChatGPT",
-            uvx_path,
+            contextual_bin,
             workspace_root,
             ui_steps=[
                 "Open ChatGPT Desktop and go to Settings",
@@ -791,7 +742,7 @@ def client(
     elif perplexity:
         _display_manual_config(
             "Perplexity",
-            uvx_path,
+            contextual_bin,
             workspace_root,
             ui_steps=[
                 "Open Perplexity Desktop (macOS) and go to Settings",
@@ -803,31 +754,31 @@ def client(
         print_agents_md_hint(agents_md, "Perplexity → Space → System Prompt")
 
     elif gemini_cli:
-        _configure_client("Gemini CLI", paths["gemini-cli"], _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        _configure_client("Gemini CLI", paths["gemini-cli"], _build_mcp_entry(contextual_bin, workspace_root), workspace_root, dry_run)
 
     elif cursor:
-        _configure_client("Cursor", paths["cursor"], _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        _configure_client("Cursor", paths["cursor"], _build_mcp_entry(contextual_bin, workspace_root), workspace_root, dry_run)
         if not dry_run:
             result = write_type_a(workspace_root / ".cursor" / "rules" / "contextual.mdc", cursor_file_content())
             print_md_injected(workspace_root / ".cursor" / "rules" / "contextual.mdc", result)
 
     elif copilot:
-        _configure_vscode_client(paths["copilot"], _build_vscode_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        _configure_vscode_client(paths["copilot"], _build_vscode_mcp_entry(contextual_bin, workspace_root), workspace_root, dry_run)
         if not dry_run:
             result = write_type_b(workspace_root / ".github" / "copilot-instructions.md", marker_block("copilot"))
             print_md_injected(workspace_root / ".github" / "copilot-instructions.md", result)
 
     elif windsurf:
-        _configure_client("Windsurf", paths["windsurf"], _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        _configure_client("Windsurf", paths["windsurf"], _build_mcp_entry(contextual_bin, workspace_root), workspace_root, dry_run)
         if not dry_run:
             result = write_type_b(workspace_root / ".windsurfrules", marker_block("windsurf"))
             print_md_injected(workspace_root / ".windsurfrules", result)
 
     elif codex:
-        _configure_codex_client(paths["codex"], uvx_path, workspace_root, dry_run)
+        _configure_codex_client(paths["codex"], contextual_bin, workspace_root, dry_run)
 
     elif antigravity:
-        _configure_client("Antigravity", paths["antigravity"], _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        _configure_client("Antigravity", paths["antigravity"], _build_mcp_entry(contextual_bin, workspace_root), workspace_root, dry_run)
         if not dry_run:
             result = write_type_a(workspace_root / ".agent" / "rules" / "contextual.md", antigravity_file_content())
             print_md_injected(workspace_root / ".agent" / "rules" / "contextual.md", result)

{contextual_engine-0.9.1 → contextual_engine-0.9.4}/contextual/cli/commands/mcp.py

@@ -144,7 +144,7 @@ def mcp_logs(
                 console.print(line, highlight=False, end="")
     except Exception as e:
         print_error(f"Failed to read logs: {e}")
-        return
+        raise typer.Exit(1)
 
     if follow:
         try:

{contextual_engine-0.9.1 → contextual_engine-0.9.4}/contextual/cli/commands/stats.py

@@ -22,7 +22,6 @@ from contextual.security.sanitize import sql_str_literal
 @require_config
 @require_index
 async def stats(
-    path: str = typer.Option(".", "--path", "-p", help="Repository path"),
     temporal: bool = typer.Option(False, "--temporal", "-t", help="Show temporal stats"),
     graph: bool = typer.Option(False, "--graph", "-g", help="Show graph stats"),
     show_all: bool = typer.Option(False, "--all", "-a", help="Show all stats"),

{contextual_engine-0.9.1 → contextual_engine-0.9.4}/contextual/config/global_/mcp_config.py

@@ -50,6 +50,15 @@ class DaemonConfig(BaseModel):
     compaction_interval_hours: float = 6.0   # How often the background loop runs (0 disables)
     compaction_retention_hours: float = 1.0  # Prune versions older than this; never 0 (breaks concurrent writes)
 
+    # Heap / memory trimmer
+    # When the daemon's physical footprint exceeds heap_trim_threshold_mb a
+    # hard trim fires (GC + malloc page return). If the footprint is still over
+    # the threshold on the next tick and no sessions are active, models are
+    # offloaded to CPU to recover MPS/GPU pages. Set to 0 to disable.
+    heap_monitor_enabled: bool = True
+    heap_monitor_interval_seconds: int = 30
+    heap_trim_threshold_mb: int = 2500
+
     # Logging
     log_level: str = "INFO"
 

{contextual_engine-0.9.1 → contextual_engine-0.9.4}/contextual/core/models.py

@@ -98,7 +98,14 @@ class FactSource(StrEnum):
 class Language(StrEnum):
     """Supported programming languages for indexing.
 
-    Week 1 MVP: Python, TypeScript, JavaScript, Go, Java, Rust, C#
+    Each value MUST equal the tree-sitter language name used by
+    ``contextual.indexing.chunker.LANGUAGE_MAP`` (the string handed to
+    ``tree_sitter_language_pack.get_parser``). The chunker maps a file
+    extension to that name; ``_build_chunk`` then does ``Language(name)``.
+    Any name present in ``LANGUAGE_MAP`` but absent here silently casts to
+    ``Language.PYTHON`` — mislabelling the chunk and breaking language
+    filtering. Keep the two in lockstep. ``c_sharp`` is the sole divergence
+    (enum value ``csharp``) and is bridged by ``chunker._TS_TO_LANG``.
     """
 
     PYTHON = "python"
@@ -109,12 +116,53 @@ class Language(StrEnum):
     JAVA = "java"
     RUST = "rust"
     CSHARP = "csharp"
+    # C family
+    C = "c"
+    CPP = "cpp"
+    # JVM / mobile
+    KOTLIN = "kotlin"
+    SWIFT = "swift"
+    SCALA = "scala"
+    DART = "dart"
+    # Scripting
+    RUBY = "ruby"
+    PHP = "php"
+    LUA = "lua"
+    PERL = "perl"
+    R = "r"
+    BASH = "bash"
+    # Functional / emerging
+    HASKELL = "haskell"
+    ELIXIR = "elixir"
     # Config formats (free wins)
     JSON = "json"
     YAML = "yaml"
     TOML = "toml"
     MARKDOWN = "markdown"
     DOCKERFILE = "dockerfile"
+    # Data / schema / infra
+    SQL = "sql"
+    HCL = "hcl"
+    PROTO = "proto"
+    # Web frontend
+    HTML = "html"
+    CSS = "css"
+    SCSS = "scss"
+    # JVM / enterprise
+    GROOVY = "groovy"
+    # Systems / emerging
+    NIM = "nim"
+    ZIG = "zig"
+    V = "v"
+    # Functional
+    ELM = "elm"
+    OCAML = "ocaml"
+    ERLANG = "erlang"
+    # Scientific
+    JULIA = "julia"
+    # Platform / Web3
+    OBJC = "objc"
+    SOLIDITY = "solidity"
 
 
 class ModelType(StrEnum):

{contextual_engine-0.9.1 → contextual_engine-0.9.4}/contextual/git/hooks.py

@@ -206,16 +206,21 @@ def _send_to_daemon(workspace_root: str, files: list[str], trigger: str) -> bool
         import httpx  # type: ignore[import-untyped]
 
         from contextual.mcp._platform import get_base_url, get_httpx_transport
+        from contextual.mcp.access import read_local_api_key
 
         transport = get_httpx_transport(sync=True)
         base = get_base_url()
         url = f"{base}/internal/index"
         kwargs: dict = {"transport": transport} if transport is not None else {}
 
+        api_key = read_local_api_key()
+        headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
+
         with httpx.Client(timeout=5.0, **kwargs) as client:
             resp = client.post(
                 url,
                 json={"workspace_root": workspace_root, "files": files, "trigger": trigger},
+                headers=headers,
             )
             resp.raise_for_status()
             return True