code-context-engine 0.4.21__py3-none-any.whl → 0.4.22__py3-none-any.whl

{code_context_engine-0.4.21.dist-info → code_context_engine-0.4.22.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-engine
-Version: 0.4.21
+Version: 0.4.22
 Summary: Save 94% on Claude Code tokens. Index your codebase locally, AI agents search instead of reading files. Reduce Claude API costs, save tokens on Cursor, VS Code, Gemini CLI. Free, open source MCP server.
 Author-email: Fazle Elahee <felahee@gmail.com>, Raj <rajkumar.sakti@gmail.com>
 License-Expression: MIT
@@ -115,15 +115,17 @@ Dynamic: license-file
 
 ---
 
-## Quick start (3 lines)
+## Quick start
 
 ```bash
-uv tool install code-context-engine
+uv tool install "code-context-engine[local]"    # or: pipx install "code-context-engine[local]"
 cd /path/to/your/project
-cce init                              # or: cce init --agent all
+cce init                                        # or: cce init --agent all
 ```
 
-That's it. Your AI coding agent now searches your index instead of reading entire files. No config needed.
+That's it. Your AI coding agent now searches your index instead of reading entire files.
+
+> **Already have Ollama?** You can skip `[local]` and use `uv tool install code-context-engine` instead. CCE auto-detects Ollama at localhost:11434 and uses `nomic-embed-text`.
 
 ---
 
@@ -143,16 +145,18 @@ Tested on all three platforms in CI (macOS, Linux, Windows × Python 3.11/3.12/3
 
 ## Install and see savings in 60 seconds
 
-```bash
-uv tool install code-context-engine   # or: pipx install code-context-engine
-cd /path/to/your/project
-cce init                              # index, install hooks, register MCP server
-```
+You need an embedding backend to index code. Pick one:
 
-**Embedding backends:** CCE auto-detects the best available backend. If you have Ollama running, it uses `nomic-embed-text` with zero extra dependencies. For offline/local embedding without Ollama, install the `[local]` extra:
+| Option | Install command | Size | Requires |
+|--------|----------------|------|----------|
+| **Local (recommended)** | `uv tool install "code-context-engine[local]"` | +60 MB | Nothing else |
+| **Ollama** | `uv tool install code-context-engine` | Core only | Ollama running + `nomic-embed-text` pulled |
+
+Then:
 
 ```bash
-uv tool install "code-context-engine[local]"   # includes fastembed + ONNX Runtime
+cd /path/to/your/project
+cce init                              # index, install hooks, register MCP server
 ```
 
 Restart your editor. Done. Every question now hits the index instead of re-reading files.
@@ -500,16 +504,18 @@ No. Quality stays the same or slightly improves.
 
 CCE replaces "dump the entire file" with "search for the relevant function." The model still gets the code it needs (0.90 Recall@10 in benchmarks). Less irrelevant context means less noise competing for attention, which can improve the model's focus on your actual question.
 
-### How do I increase output token savings?
+### How does output token savings work?
+
+CCE writes output compression rules directly into your agent's instruction files (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, etc.) during `cce init`. These rules apply to the **entire session**, not just CCE tool responses, so every reply from the agent follows them.
 
-Set the output compression level in your project config (`cce.yaml`):
+Set the level in `cce.yaml`:
 
 ```yaml
 compression:
   output: max       # off | lite | standard | max
 ```
 
-Or change it at runtime via the MCP tool:
+Then re-run `cce init` to update instruction files. Or change at runtime:
 
 ```
 set_output_level output_level=max
@@ -522,7 +528,7 @@ set_output_level output_level=max
 | `standard` | ~70% | Drops articles, fragments, short synonyms + diff-only for code |
 | `max` | ~80% | Telegraphic style + diff-only for code |
 
-Default is `standard`. All levels include **code output rules** that instruct the model to show only changed lines (not full file rewrites), which is where most output tokens go in coding sessions. The `max` level produces very terse prose (similar to "caveman mode"). Code blocks, paths, and commands are never compressed regardless of level.
+Default is `standard`. All levels include **code output rules** that tell the model to show only changed lines (not full file rewrites), which is where most output tokens go in coding sessions. The `max` level produces very terse prose (similar to "caveman mode"). Code blocks, paths, and commands are never compressed regardless of level.
 
 ### Where do the savings come from?
 

{code_context_engine-0.4.21.dist-info → code_context_engine-0.4.22.dist-info}/RECORD

@@ -1,9 +1,9 @@
-code_context_engine-0.4.21.dist-info/licenses/LICENSE,sha256=vLbw0GGCVJSIRppMus7Oq0PyMDhDXz-dfvz2rPpWtjQ,1069
+code_context_engine-0.4.22.dist-info/licenses/LICENSE,sha256=vLbw0GGCVJSIRppMus7Oq0PyMDhDXz-dfvz2rPpWtjQ,1069
 context_engine/__init__.py,sha256=qThGxB7xfZi5M9jDpUno0MKBp7KKrEOdH1hG4wHMuLc,193
-context_engine/cli.py,sha256=e0lpFLY03-3pymdNm-nLirS3jNZu-rk-jAa-6vb4Hlw,129165
+context_engine/cli.py,sha256=iZbxwA0O4zFD_WRVgPnh1WdhsmZpu6Me-9lJTeT28DE,130226
 context_engine/cli_style.py,sha256=a3l3Smq1gIN2asbNalFUz0i_5x7Tmkp_wEhyGMoo8a4,2460
 context_engine/config.py,sha256=UGbVuc8_wTMflzGh80AotMZXZHzzUpLI3QjMnCxTzRo,8370
-context_engine/editors.py,sha256=Dicljtj7gPnXJ2wLSMqQzRZwTEq_XtUpRa1xfABOvKk,23411
+context_engine/editors.py,sha256=k9jrqzU5gvYkR5kMu3VcVKHdjxEODZNmxBIEhQUOszE,23986
 context_engine/event_bus.py,sha256=7Jgw_2YvGQFrnYewXk6T6FJcvRHz0LVEMDgZym9YBCE,760
 context_engine/models.py,sha256=XBbM0CUqNDQ5MOp6F3STST2qLqy2Zk0m050ZtWdXkrk,2048
 context_engine/pricing.py,sha256=aT1bsQuZXPlCdTgtwesJLwlKc2tzh8rxL67sZlMbz4E,4684
@@ -14,7 +14,7 @@ context_engine/utils.py,sha256=rytymcEY0tjG4uknJU3DXKz1_ZGjUjJRV3PhkjXoC8A,3192
 context_engine/compression/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 context_engine/compression/compressor.py,sha256=JlNxZeM6-tXISWVOGiJAcLoixqAxwfEGcYtE0dj8FPw,6680
 context_engine/compression/ollama_client.py,sha256=MKF1gii2BXMU-wxBRPyMCjo8t72v3dZ06Kv2JNfILgQ,1265
-context_engine/compression/output_rules.py,sha256=BK9mOL5o7muM1Ozj800WsltRMHjvkU4UhBy8zsIsDEw,4327
+context_engine/compression/output_rules.py,sha256=kpLZ6r6Ng6PyAvA22wed5ecm8YTxHwwKI57PgsnX6ls,6655
 context_engine/compression/prompts.py,sha256=jZnpqhr77uI9R3S0vm3Dj17JYy03AXq24E6HQTPXy-A,711
 context_engine/compression/quality.py,sha256=F6fyxDdWjq-Hgtw4xFIaE4BqPoJw1W1EQSn3RXDgdHc,1676
 context_engine/dashboard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -22,7 +22,7 @@ context_engine/dashboard/_page.py,sha256=2LOz6GxVFHdNyd6iGV-u6sbwCnTrw2p_cVUY-Ly
 context_engine/dashboard/server.py,sha256=N-QVaDCUL1h70QUgKrIy6QhQIedasf0KYHcV5LACZ0U,17437
 context_engine/indexer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 context_engine/indexer/chunker.py,sha256=f0n7gJughdHP1fmMd1sbHAxLmVlCnIq6scHOeGFmBS8,6503
-context_engine/indexer/embedder.py,sha256=QSrep2Si6RgddikJMyBlO-K2p58yc2VgANKEsv5rf3g,20646
+context_engine/indexer/embedder.py,sha256=xznLoW8A9KfDRZWO2MYzCk6o_Kj5YLIMuQ2J-MIbo3g,22717
 context_engine/indexer/embedding_cache.py,sha256=yp7zvjjbhDei1tEczdo25GB_a5SJt3XfO4TVGujjSA0,6454
 context_engine/indexer/git_hooks.py,sha256=GjncsmFu2TZx_3TNQNSBSp15uDwOJ3AtUJxuePQCP24,3258
 context_engine/indexer/git_indexer.py,sha256=3IbAHYKa-XzpEX4zUfdvU0EHj-qjyn8muK6yPuxy9kw,4154
@@ -38,7 +38,7 @@ context_engine/integration/mcp_server.py,sha256=hIvap8fnpbeAOjJ0oy0GZdgjnUln6b-D
 context_engine/integration/session_capture.py,sha256=azc0I2PoQQ-0gsmTFy254na_Ez3ADHJ5IdOKU5oFIEU,12440
 context_engine/memory/__init__.py,sha256=-mzH2HLbjF6mlyzlt0IZoezDPLHBTJmIXFlsn8cjeQA,299
 context_engine/memory/compressor.py,sha256=TiHxFHRPS3TQxo2_YnnXv8QaQXwxehmH2iwe-azuxpw,15763
-context_engine/memory/db.py,sha256=x0NaR5aKcOcqrl-GKCFIW7DPuwQ1pYreqDc0dpg9O14,34579
+context_engine/memory/db.py,sha256=C700MhsdzT8NhpTz_8q-XV4kO6i-Rp4h4GTRoDa8OC4,34936
 context_engine/memory/decision_extractor.py,sha256=tAFcKVaX5Y1qax71MAR03eq6uyCBIfiEDlbsgiodHUw,3508
 context_engine/memory/extractive.py,sha256=VJFBG8P6Wku0OaKBQmOr3eTk5XRS2ed3q-TYb432GLc,3227
 context_engine/memory/grammar.py,sha256=1yrMky1MlmT9m4-_XW3Rq8ZAEE6fBp4miFiWNEcH8ao,16776
@@ -56,9 +56,9 @@ context_engine/storage/fts_store.py,sha256=GzsF-xUPInqovcK72ULgpYAtMAymx4BRrYmps
 context_engine/storage/graph_store.py,sha256=EAJaDK1OzSabm6HY4h7ZdZcykzlqtdFosNTypW5VNpc,8991
 context_engine/storage/local_backend.py,sha256=5MVoAn6Jkiltho-9BjClisLkyXMkSZZc2Z_h3N7Vfcg,4200
 context_engine/storage/remote_backend.py,sha256=6AwEI9YQnmP1w0a7S0ei3YrU2h3z7wbrwv34k7g5YOU,5483
-context_engine/storage/vector_store.py,sha256=FOp1fqneIQ4LQQh3f6sfZcn2jswj2SoEazW5BySGBVw,15025
-code_context_engine-0.4.21.dist-info/METADATA,sha256=2yz6upwhp6KQ764H6psthsFxcqX0_efZbDs8A2Gv03I,25316
-code_context_engine-0.4.21.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-code_context_engine-0.4.21.dist-info/entry_points.txt,sha256=DQuRWUuVFM7nPcXtDmJzlem7QA0IboD_4N8AnTtDD9Q,144
-code_context_engine-0.4.21.dist-info/top_level.txt,sha256=X1-RUqb61WXBjy3JjsW2oXwfvqk2ydXKDNidxmw4CZ4,15
-code_context_engine-0.4.21.dist-info/RECORD,,
+context_engine/storage/vector_store.py,sha256=GyXSTlcKpByjr2C9JUF_cUCvMbGAc1UVV8Apx5X82kw,15772
+code_context_engine-0.4.22.dist-info/METADATA,sha256=UUastWJFLBpuSBE0fr-bWL857Jp06tyCq_5V1bj00CI,25756
+code_context_engine-0.4.22.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+code_context_engine-0.4.22.dist-info/entry_points.txt,sha256=DQuRWUuVFM7nPcXtDmJzlem7QA0IboD_4N8AnTtDD9Q,144
+code_context_engine-0.4.22.dist-info/top_level.txt,sha256=X1-RUqb61WXBjy3JjsW2oXwfvqk2ydXKDNidxmw4CZ4,15
+code_context_engine-0.4.22.dist-info/RECORD,,

context_engine/cli.py

@@ -182,12 +182,12 @@ _CCE_CLAUDE_MD_MARKER = "## Context Engine (CCE)"
 # Version stamp embedded as an HTML comment so it doesn't render in the final
 # Markdown but lets `_ensure_claude_md` detect when the installed block is
 # stale and needs replacing. Bump whenever _CCE_CLAUDE_MD_BLOCK changes.
-_CCE_CLAUDE_MD_VERSION = "3"
+_CCE_CLAUDE_MD_VERSION = "4"
 _CCE_CLAUDE_MD_VERSION_TAG = f"<!-- cce-block-version: {_CCE_CLAUDE_MD_VERSION} -->"
 _CCE_CLAUDE_MD_VERSION_PREFIX = "<!-- cce-block-version: "
 _CCE_CLAUDE_MD_END_MARKER = "<!-- /cce-block -->"
 
-_CCE_CLAUDE_MD_BLOCK = f"""\
+_CCE_CLAUDE_MD_BLOCK_TEMPLATE = f"""\
 {_CCE_CLAUDE_MD_VERSION_TAG}
 ## Context Engine (CCE)
 
@@ -268,18 +268,22 @@ the goal is durable signal, not an event log.
 Both are read-only and cheap. Prefer them over re-running tool calls or
 asking the user to re-paste context.
 
-## Output Style
-
-Be concise. Lead with the answer or action, not reasoning. Skip filler words,
-preamble, and phrases like "I'll help you with that" or "Certainly!". Prefer
-fragments over full sentences in explanations. No trailing summaries of what
-you just did. One sentence if it fits.
-
-Code blocks, file paths, commands, and error messages are always written in full.
+{{output_style}}
 {_CCE_CLAUDE_MD_END_MARKER}
 """
 
 
+def _build_claude_md_block(output_level: str = "standard") -> str:
+    """Generate the CLAUDE.md CCE block with the configured output style."""
+    from context_engine.compression.output_rules import get_instruction_output_block
+    block = get_instruction_output_block(output_level)
+    return _CCE_CLAUDE_MD_BLOCK_TEMPLATE.replace("{output_style}", block)
+
+
+# Default block for backward compat
+_CCE_CLAUDE_MD_BLOCK = _build_claude_md_block("standard")
+
+
 def _resolve_cce_cmd() -> str:
     """Find the globally installed cce binary path."""
     from context_engine.utils import resolve_cce_binary
@@ -623,6 +627,22 @@ def _preflight_check(config) -> None:
     one was picked, and surfaces Ollama status for the separate compression
     path so users know what compression level they will get.
     """
+    # --- SQLite extension support ---
+    import sqlite3 as _sqlite3
+    _test_conn = _sqlite3.connect(":memory:")
+    if not hasattr(_test_conn, "enable_load_extension"):
+        _test_conn.close()
+        raise click.ClickException(
+            "Your Python was compiled without SQLite extension support "
+            "(enable_load_extension is missing).\n"
+            "This is common with python.org installers on macOS.\n\n"
+            "Fix: reinstall CCE under a Python that has extension support:\n\n"
+            "  brew install python3\n"
+            "  uv tool install --python /opt/homebrew/bin/python3 "
+            "--force code-context-engine\n"
+        )
+    _test_conn.close()
+
     # --- Embedding backend ---
     click.echo(_dim("  Detecting embedding backend") + "...", nl=False)
     from context_engine.config import resolve_ollama_url
@@ -646,13 +666,15 @@ def _preflight_check(config) -> None:
                 fg="green",
             )
         )
-    except Exception as exc:
+    except Exception:
         click.echo("")
-        _warn(f"No embedding backend available: {exc}")
-        _warn(
-            "Install fastembed (`pip install code-context-engine[local]`) "
-            f"or start an Ollama server at {ollama_url} and pull "
-            f"{ollama_model}."
+        raise click.ClickException(
+            "No embedding backend available.\n\n"
+            "Fix (pick one):\n"
+            "  1. Install local embeddings:\n"
+            "     uv tool install 'code-context-engine[local]'\n\n"
+            f"  2. Start Ollama and pull the embedding model:\n"
+            f"     ollama pull {ollama_model}\n"
         )
 
     # --- Ollama for LLM compression (independent of the embedding path) ---
@@ -678,7 +700,7 @@ def _preflight_check(config) -> None:
         click.echo(_dim("  Tip: ollama pull phi3:mini for LLM summarization"))
 
 
-def _ensure_claude_md(project_dir: Path) -> None:
+def _ensure_claude_md(project_dir: Path, output_level: str = "standard") -> None:
     """Add or upgrade the CCE instructions block in CLAUDE.md.
 
     Three states the file can be in:
@@ -693,9 +715,10 @@ def _ensure_claude_md(project_dir: Path) -> None:
     """
     from context_engine.utils import atomic_write_text
 
+    block = _build_claude_md_block(output_level)
     claude_md = project_dir / "CLAUDE.md"
     if not claude_md.exists():
-        atomic_write_text(claude_md, _CCE_CLAUDE_MD_BLOCK)
+        atomic_write_text(claude_md, block)
         _ok("CLAUDE.md created with CCE instructions")
         return
 
@@ -710,13 +733,13 @@ def _ensure_claude_md(project_dir: Path) -> None:
     # survives the upgrade.
     old_block = _extract_existing_cce_block(existing)
     if old_block is not None:
-        new_content = existing.replace(old_block, _CCE_CLAUDE_MD_BLOCK.rstrip(), 1)
+        new_content = existing.replace(old_block, block.rstrip(), 1)
         atomic_write_text(claude_md, new_content)
         _ok("CLAUDE.md upgraded to current CCE instructions")
         return
 
     # No CCE block detected — append.
-    new_content = existing.rstrip() + "\n\n" + _CCE_CLAUDE_MD_BLOCK
+    new_content = existing.rstrip() + "\n\n" + block
     atomic_write_text(claude_md, new_content)
     _ok("CLAUDE.md updated with CCE instructions")
 
@@ -905,14 +928,15 @@ def init(ctx: click.Context, agent: str) -> None:
         for file_key, info in INSTRUCTION_FILES.items():
             if any((project_dir / marker).exists() for marker in info["detect"]):
                 instruction_targets.add(file_key)
+    output_level = getattr(config, "output_compression", "standard")
     for file_key in sorted(instruction_targets):
         info = INSTRUCTION_FILES[file_key]
-        if write_instruction_file(project_dir, file_key):
+        if write_instruction_file(project_dir, file_key, output_level=output_level):
             _ok(f"CCE instructions added to {info['name']}")
 
     # 5. CLAUDE.md + session hook + memory lifecycle hooks
     if "claude" in editor_targets:
-        _ensure_claude_md(project_dir)
+        _ensure_claude_md(project_dir, output_level=output_level)
         _ensure_session_hook(project_dir)
         _install_memory_hooks(project_dir)
         _check_memory_capture_reachable(config, project_dir)

context_engine/compression/output_rules.py

@@ -90,3 +90,57 @@ def get_level_description(level: str) -> str:
         "max": "Telegraphic style with abbreviations and symbols. Diff-only for code. ~80% savings.",
     }
     return descriptions.get(level, "Unknown level")
+
+
+# ── Instruction-file blocks ──────────────────────────────────────────
+# These go into CLAUDE.md, AGENTS.md, .cursorrules, etc. so they apply
+# to the entire session, not just CCE tool responses.
+
+_INSTRUCTION_OUTPUT_STYLES = {
+    "lite": """\
+### Output style
+
+Respond concisely. Remove filler words (just, really, basically, actually,
+simply), hedging (I think, it seems, perhaps), and pleasantries (Sure!,
+Happy to help, Great question). No trailing summaries. Keep full grammar.
+
+When suggesting code changes, show only the changed lines with 3 lines of
+context. Never rewrite entire files. For new files, show the full file.
+For edits, show only what changes.""",
+
+    "standard": """\
+### Output style
+
+Respond in compressed style. Drop articles (a, an, the) in prose. Use
+sentence fragments over full sentences. Use short synonyms (fix not resolve,
+check not investigate). Pattern: [thing] [action] [reason]. [next step].
+No filler, hedging, pleasantries, trailing summaries, or restating what
+the user said. One sentence if one sentence is enough.
+
+When suggesting code changes, show only the changed lines with 3 lines of
+context. Never rewrite entire files. Multiple changes in one file: show each
+change separately. Never echo back unchanged code the user already has.
+
+Code blocks, file paths, commands, error messages: always written in full.
+Security warnings and destructive action confirmations: use full clarity.""",
+
+    "max": """\
+### Output style
+
+Respond in telegraphic style. Drop articles, pronouns, conjunctions where
+meaning survives. Abbreviate common terms: DB, auth, config, fn, dep, impl,
+req, resp, init. Use arrows for causality: X → Y. Use symbols: + (add),
+- (remove), ~ (change), ! (warning). Max 1-2 sentences per explanation.
+Pattern: [thing] → [action]. [reason].
+
+When suggesting code changes, show only changed lines. Never rewrite files.
+Never echo back unchanged code.
+
+Code blocks, paths, commands, errors: always full.
+Security warnings and destructive actions: full clarity, drop compression.""",
+}
+
+
+def get_instruction_output_block(level: str) -> str:
+    """Return the output style block for instruction files, or empty if off."""
+    return _INSTRUCTION_OUTPUT_STYLES.get(level, "")

context_engine/editors.py

@@ -92,7 +92,7 @@ EDITORS: dict[str, dict] = {
 # ── Instruction file definitions ──────────────────────────────────────
 
 # Editor-agnostic CCE instructions (no "Claude Code" references)
-_CCE_INSTRUCTIONS = """\
+_CCE_INSTRUCTIONS_BASE = """\
 ## Context Engine (CCE)
 
 This project uses Code Context Engine for intelligent code retrieval and
@@ -122,6 +122,19 @@ Call `record_decision(decision="...", reason="...")` after making choices.
 Call `record_code_area(file_path="...", description="...")` after meaningful work.
 """
 
+
+def _build_instructions(output_level: str = "standard") -> str:
+    """Build CCE instructions with the configured output style."""
+    from context_engine.compression.output_rules import get_instruction_output_block
+    block = get_instruction_output_block(output_level)
+    if block:
+        return _CCE_INSTRUCTIONS_BASE + "\n" + block + "\n"
+    return _CCE_INSTRUCTIONS_BASE
+
+
+# Default instructions (standard output compression)
+_CCE_INSTRUCTIONS = _build_instructions("standard")
+
 INSTRUCTION_FILES: dict[str, dict] = {
     "agents": {
         "name": "AGENTS.md",
@@ -568,21 +581,24 @@ def _remove_toml(config_path: Path, display_path: str, *, section: str) -> str |
         return None
 
 
-def write_instruction_file(project_dir: Path, file_key: str) -> bool:
+def write_instruction_file(
+    project_dir: Path, file_key: str, output_level: str = "standard",
+) -> bool:
     """Write CCE instructions to an editor's instruction file. Returns True if written."""
     info = INSTRUCTION_FILES[file_key]
     path = project_dir / info["path"]
     marker = "## Context Engine (CCE)"
     path.parent.mkdir(parents=True, exist_ok=True)
+    instructions = _build_instructions(output_level)
 
     if path.exists():
         content = path.read_text()
         if marker in content:
             return False  # already has CCE block
         # Append
-        path.write_text(content.rstrip() + "\n\n" + _CCE_INSTRUCTIONS)
+        path.write_text(content.rstrip() + "\n\n" + instructions)
     else:
-        path.write_text(_CCE_INSTRUCTIONS)
+        path.write_text(instructions)
     return True
 
 

context_engine/indexer/embedder.py

@@ -319,16 +319,66 @@ class OllamaBackend:
             for _ in resp.iter_lines():
                 pass
 
+    # nomic-embed-text has an 8192-token context. Dense-tokenizing content
+    # (YAML with ${{ }}, Python separator comments) can hit ~1 char/token,
+    # so 3000 chars is a safe ceiling that works for all content types.
+    _MAX_EMBED_CHARS = 3000
+
     def _embed_batch(self, texts: list[str]) -> list[list[float]]:
         import httpx
-        resp = httpx.post(
-            f"{self.base_url}/api/embed",
-            json={"model": self.model_name, "input": texts},
-            timeout=self._timeout,
-        )
-        resp.raise_for_status()
-        data = resp.json()
-        return data.get("embeddings", [])
+        # Truncate oversized texts and skip empty ones
+        safe_texts = []
+        original_indices = []
+        for i, t in enumerate(texts):
+            if not t or not t.strip():
+                continue
+            safe_texts.append(t[:self._MAX_EMBED_CHARS])
+            original_indices.append(i)
+
+        if not safe_texts:
+            return [[] for _ in texts]
+
+        try:
+            resp = httpx.post(
+                f"{self.base_url}/api/embed",
+                json={"model": self.model_name, "input": safe_texts},
+                timeout=self._timeout,
+            )
+            resp.raise_for_status()
+            embeddings = resp.json().get("embeddings", [])
+        except httpx.HTTPStatusError as exc:
+            if exc.response.status_code != 400:
+                raise
+            # Batch failed (possibly one text still too large after truncation).
+            # Fall back to one-at-a-time with halving retry.
+            log.warning("Ollama batch embed failed, retrying one-at-a-time")
+            embeddings = []
+            for text in safe_texts:
+                vec = self._embed_single_with_retry(text)
+                embeddings.append(vec)
+
+        # Map embeddings back to original positions (empty texts get empty vecs)
+        result: list[list[float]] = [[] for _ in texts]
+        for idx, emb in zip(original_indices, embeddings):
+            result[idx] = emb
+        return result
+
+    def _embed_single_with_retry(self, text: str) -> list[float]:
+        """Embed a single text, halving on context-length errors."""
+        import httpx
+        while text:
+            resp = httpx.post(
+                f"{self.base_url}/api/embed",
+                json={"model": self.model_name, "input": [text]},
+                timeout=self._timeout,
+            )
+            if resp.status_code == 400 and "context length" in resp.text:
+                text = text[:len(text) // 2]
+                continue
+            resp.raise_for_status()
+            vecs = resp.json().get("embeddings", [[]])
+            return vecs[0] if vecs else []
+        return []
 
     def embed_texts(self, texts: list[str], batch_size: int = 64) -> list[list[float]]:
         out: list[list[float]] = []

context_engine/memory/db.py

@@ -281,6 +281,14 @@ def _try_load_vec(conn: sqlite3.Connection) -> bool:
         sqlite_vec.load(conn)
         conn.enable_load_extension(False)
         return True
+    except AttributeError:
+        log.warning(
+            "sqlite-vec load failed; semantic recall disabled. "
+            "Python was compiled without SQLite extension support. "
+            "Reinstall CCE with Homebrew Python: "
+            "uv tool install --python /opt/homebrew/bin/python3 --force code-context-engine"
+        )
+        return False
     except Exception as exc:
         log.warning("sqlite-vec load failed; semantic recall disabled: %s", exc)
         return False

context_engine/storage/vector_store.py

@@ -46,9 +46,23 @@ class VectorStore:
     def _connect(self) -> sqlite3.Connection:
         import sqlite_vec
         conn = sqlite3.connect(self._db_file, check_same_thread=False)
-        conn.enable_load_extension(True)
-        sqlite_vec.load(conn)
-        conn.enable_load_extension(False)
+        try:
+            conn.enable_load_extension(True)
+            sqlite_vec.load(conn)
+            conn.enable_load_extension(False)
+        except AttributeError:
+            raise RuntimeError(
+                "Your Python was compiled without SQLite extension support "
+                "(enable_load_extension is missing). This is common with "
+                "python.org installers on macOS.\n\n"
+                "Fix: reinstall CCE under a Python that has extension support:\n"
+                "  uv tool install --python $(brew --prefix python3)/bin/python3 "
+                "--force code-context-engine\n\n"
+                "Or use Homebrew Python directly:\n"
+                "  brew install python3\n"
+                "  uv tool install --python /opt/homebrew/bin/python3 "
+                "--force code-context-engine"
+            ) from None
         conn.execute("PRAGMA journal_mode=WAL")
         conn.execute("PRAGMA synchronous=NORMAL")
         return conn