Sponsored by SearchApi

/exports`. - `health()` - server status, including the local research runtime. | Need | Tool | |---|---| | Search only previously stored research and project memory | `project_memory_search` | | Find new information on the web | `search` | | Compare new web results with stored project knowledge | `search` with `project_id` | | Run several new web queries | `search_parallel` | ## Replayable research collection `google-surf-collect` runs a versioned JSON specification through one persistent MCP session. A specification can mix live `search` jobs with local-only `project_memory_search` jobs. Live jobs can extract bodies in the same call, while local jobs reuse indexed project knowledge without opening Google. ```bash npx google-surf-collect examples/research-collection.example.json ``` From a source checkout: ```bash npm run build npm run research:collect -- examples/research-collection.example.json ``` A project workflow can also record durable sessions and plans, rebuild approved code roots, search the resulting local knowledge, and export its graph: ```bash npm run research:collect -- examples/project-memory-workflow.example.json ``` `project_memory` collection jobs allow `record`, `rebuild`, and `export`. Destructive `forget` operations are not accepted by the collection schema. Project-level `project_id` is inherited by every job unless an all-project export is requested. The output is append-only JSONL. Its manifest records the normalized specification hash, package version, Git commit, Node runtime, platform, project setup, and server health. Every search, record, rebuild, and export result records the stable job id, exact tool arguments, attempt, timestamps, elapsed time, response, and error state. Successful jobs are skipped on resume; failed jobs are retried. A changed specification requires a new output file. Set `project_name` with `project_id` when the runner should create a missing project; existing projects are reused. Set `retrieval_mode` to `live` when prior project RAG state must not affect live result ranking. Results are still captured under `project_id`. Use `hybrid` when the collection intentionally ranks new web evidence together with stored project knowledge. API keys and environment variable values are never written to the collection log. This makes the collection procedure and returned snapshot replayable and auditable. Live web results can still change with time, locale, network route, and upstream ranking. ## Graph hybrid RAG with ontology and lineage ```mermaid flowchart TB subgraph SOURCES["1. Search and research"] direction LR LIVE["Live web
Google browser • SearchApi fallback"] PAPER["Pages and papers
extract • Scholar metadata"] PROJECT_INPUT["Code and project records
local roots • GitHub • host-provided session/plan"] end INGEST["2. Deterministic capture
normalize • deduplicate • content hash
repository source gate • Tree-sitter"] subgraph KNOWLEDGE_BASE["3. SurrealDB knowledge base"] direction LR CONTENT["Content and code index
exact • BM25 • HNSW vector
documents • chunks • symbols"] PROV["Data lineage and provenance
source → evidence → assertion
valid time • recorded time • correction"] ONTOLOGY["Versioned ontology
core/project term revisions
entity type • relation • alias • merge/split"] MEMORY["Project memory
session intent • plan revisions
experiments • decisions"] end subgraph INTELLIGENCE["4. Graph intelligence"] direction LR SCHEMA["Cross-project schema linking
type and relation alignment
stable identifier → identity bridge"] SIDECAR["Typed graph sidecar
PageRank • Louvain • query-time PPR"] end FUSION["5. Hybrid retrieval
live • exact • BM25 • vector • graph
deterministic RRF • shared reranker • fresh-web floor"] RESULTS["Results + provenance
short storage receipt"] LIVE --> INGEST PAPER --> INGEST PROJECT_INPUT --> INGEST INGEST --> CONTENT INGEST --> PROV INGEST --> ONTOLOGY INGEST --> MEMORY ONTOLOGY --> SCHEMA CONTENT --> SIDECAR PROV --> SIDECAR MEMORY --> SIDECAR SCHEMA --> SIDECAR LIVE --> FUSION CONTENT --> FUSION SIDECAR --> FUSION FUSION --> RESULTS RESULTS -. "automatic search/extract capture" .-> INGEST classDef inputStyle fill:#eef6ff,stroke:#2563eb,color:#172554 classDef processStyle fill:#fff7ed,stroke:#ea580c,color:#431407 classDef storageStyle fill:#ecfdf5,stroke:#059669,color:#052e16 classDef intelligenceStyle fill:#f5f3ff,stroke:#7c3aed,color:#2e1065 classDef outputStyle fill:#f8fafc,stroke:#475569,color:#0f172a class LIVE,PAPER,PROJECT_INPUT inputStyle class INGEST processStyle class CONTENT,PROV,ONTOLOGY,MEMORY storageStyle class SCHEMA,SIDECAR intelligenceStyle class FUSION,RESULTS outputStyle ``` ### One local knowledge base One SurrealDB instance is the authority for three distinct layers: - **Catalog:** stable identities, revisions, project membership, ontology, provenance, and temporal links. - **Payloads:** exact bodies, source snapshots, manifests, and artifact references. Identical content is stored once and can be fetched by ID and byte span. - **Derived views:** exact, BM25, vector, code, and graph indexes plus the compact current-project view. These are versioned by source hash and can be rebuilt. A single local research broker owns the embedded RocksDB connection. Multiple MCP sessions connect through authenticated local IPC, run bounded reads concurrently, and serialize writes without opening another database process. Original evidence and historical occurrences remain addressable even when bodies, embeddings, or graph structures are deduplicated. ### Durable records and incremental indexing `project_memory` writes project profiles, plans, experiments, attempts, measurements, artifacts, documents, decisions, and sessions as typed records. A stable asset ID receives revisions; an uncertain retry with the same idempotency key returns the committed revision with `idempotent_replay=true` and `applied_this_request=false`. `body_path` streams bodies up to 256 MiB, artifact manifests are paginated instead of sliced, and `get`/`get_batch` return exact typed or legacy records through bounded body spans. Compact write receipts report accepted bytes, references, revision, and the exact readback handle without echoing the submitted body. `sync` accepts registered roots or explicit changed and removed paths. Unchanged roots and parent identities remain intact, a no-op does not rewrite derived indexes, and a one-file change publishes only the affected generation. Code, retrieval, and graph publication run under one durable job ID. `job_wait` uses a revision cursor, `job_cancel` stops at a safe stage boundary, and unfinished jobs resume after process restart. Under the worker soft-memory limit, foreground requests finish first; rebuildable index jobs checkpoint at a durable stage boundary and resume in the replacement worker without cancelling the committed record. ### Ontology and cross-project links The versioned ontology preserves entity type and relation changes as revisions. Schema linking aligns project-specific types and relations with the shared schema. Entity linking connects the same paper, repository, or entity only when verifiable identifiers such as a DOI, repository URL, or explicit alias match. Ambiguous candidates are not linked automatically. ### Data and research lineage - **Source lineage:** `source → document → chunk → evidence → assertion` - **Code lineage:** `repository → directory → file → symbol → import/call` - **Research lineage:** `session → intent → plan revision → experiment → decision` This preserves the evidence behind claims and decisions while retaining corrected or superseded history. ### Graph retrieval Graphology builds a typed graph projection from SurrealDB and computes PageRank, connected components, and Louvain communities. At retrieval time, related nodes seed PPR-based multi-hop search. Live web, exact, BM25, vector, and graph candidates are combined through deterministic RRF and one shared reranker. Local multi-query retrieval batches query embeddings, keeps exact, BM25, and vector lanes independent through RRF, expands the graph once, hydrates selected chunks once, and reranks once. Graph-only all-project searches use a lightweight memory-node index and verified identity aliases to select at most four graph scopes instead of constructing every project graph at query time. If query embedding fails or returns no vector, local search returns its lexical/graph ranking without retrying the model in reranking. Timing fields are non-overlapping wall-clock partitions: `embedding_ms` plus `retrieval_ms` reaches the end of retrieval, and `rerank_ms` covers the remaining response work. Retrieval may overlap embedding, so `retrieval_ms` is not standalone database execution time. A supplied `response_deadline_ms` starts after broker admission; the transport watchdog retains its five-minute queue/IPC allowance in addition to that deadline. Native queries that outlive a partial response retain their broker read slot until they settle. #### Research retrieval check The 60-query regression fixture compares the lexical baseline with the complete local RAG path. To separate retrieval changes from HNSW approximation, the check pins one embedding thread and uses exhaustive vector scoring. The table reports the median of three fresh-process runs: | 60 controlled queries | Recall@10 | nDCG@10 | MRR@10 | |---|---:|---:|---:| | Lexical baseline | 0.3333 | 0.3333 | 0.3333 | | Exact + BM25 + Vector + Graph RRF | **0.9833** | **0.8194** | **0.7668** | | + shared reranker | **0.9833** | **0.8194** | **0.7668** | All retrieved targets passed exact provenance readback. The conservative reranker preserved the fused order on this fixture; this check does not claim production search quality or a reranker gain. `npm run research:vector-backends -- --rows 5000` compares physical representations with deterministic test vectors. The sample below excludes E5 model loading and should be rerun on the target machine: | Backend | Input rows | Stored vectors | Insert | Query p95 | Recall | |---|---:|---:|---:|---:|---:| | HNSW | 5,000 | 5,000 | 1292.1 ms | 10.77 ms | 1.000 | | Compact | 5,000 | 1,250 | 357.1 ms | 3.96 ms | 1.000 | | Exhaustive | 5,000 | 5,000 | 1197.1 ms | 289.79 ms | 1.000 | The default remains HNSW for full-chunk semantic coverage. Compact indexes one representative chunk per source; it used less memory and matched aggregate recall in this short-record fixture, but can miss rare details near the tail of long sources. #### Broker and durability check | Latest 100-query local soak | Result | |---|---:| | Browser broker launches | 0 | | Active database owner restarts | 0 | | Query RSS delta | +10.9 MiB | | Peak observed research worker RSS | 375.5 MiB | | Idle drain and transparent reopen | Passed | | No-op sync / one-file incremental sync | Passed / Passed | `npm run research:reopen-probe` also verifies byte-exact body paging, a paginated 225-reference artifact manifest, and a pending rebuild that resumes after process restart and becomes searchable. The soak runs with the vector model disabled to isolate broker, database, and query lifecycle memory; vector backends are measured separately above. ### Project isolation and knowledge reuse `project_id` selects where new results are stored. `include_project_ids` expands the read scope without changing the write target. Original records remain isolated by project, while verified schema and entity links allow papers, code, and experiment results to be reused across selected projects. ### Interactive graph and export Use `project_memory(action="export", export_format="html", export_view="graph")`. The returned standalone HTML opens locally without a server and contains three coordinated views. Use `project_id` for one project, `include_project_ids` for a selected combined graph, or `all_projects=true` for every project. - **PKM** groups the integrated project graph by community and sizes nodes by PageRank. - **Lineage** separates source and code lineage from session, intent, plan, experiment, and decision lineage while keeping both flows aligned by stage. - **Ontology** shows core types and relations, aligned shared schema, and typed instances. A verified identity layer appears only when stable identifiers or explicit aliases prove a cross-project match.

Data and research lineage

Ontology and shared schema

Search, type filters, one to three hop local focus, pan, zoom, and the provenance inspector work inside the file. Large graphs use a deterministic semantic projection that balances node type, PageRank, degree, and community coverage. The viewer reports source and displayed counts, replaces internal IDs with local aliases, disambiguates repeated labels, and does not embed source IDs, local paths, node bodies, plan text, or evidence quotes. The project menu switches between every project embedded in the export and an integrated `All projects` view. Use `all_projects=true` when exporting to include every named project in the local database, or use `project_id` and `include_project_ids` for a bounded set. Clicking empty canvas space clears local node focus. PNG exports the current canvas, while JSON exports the current tab, project, type filters, and local focus using only the anonymized viewer payload. The standalone file has a nonce-bound script CSP, makes no network connections, and permits source links only for stripped public HTTP or HTTPS URLs. #### Neo4j export Use `project_memory(action="export", export_format="neo4j", export_view="graph")`. The returned directory contains `nodes.csv`, `relationships.csv`, `constraints.cypher`, `load.cypher`, `manifest.json`, and `README.txt`. PageRank, community, ontology, lineage, project IDs, source IDs, and evidence IDs are preserved. Node bodies, plan text, and evidence quotes are not exported. For a new or empty local database, run the Neo4j offline importer from the export directory: ```powershell neo4j-admin database import full --nodes=nodes.csv --relationships=relationships.csv neo4j ``` For an existing local database, copy both CSV files to the Neo4j import directory, then run: ```powershell cypher-shell -f constraints.cypher cypher-shell -f load.cypher ``` The offline importer creates typed node labels and relationship types. The online loader uses `SurfNode` and `SURF_RELATION`, retaining the original kinds and relationship types as properties. `neo4j-admin database import full` is intended for a new or empty database; use `LOAD CSV` for an existing database. See the official [Neo4j import](https://neo4j.com/docs/operations-manual/current/import/) and [LOAD CSV](https://neo4j.com/docs/cypher-manual/current/clauses/load-csv/) documentation. Bolt is a connection protocol, not an export file format, so this command does not connect to or modify a Neo4j server. ### Storage scope and security Research mode is enabled by default. `search`, `search_parallel`, `scholar_search`, and `extract` results are captured automatically. Session intent, plans, experiments, and decisions are stored only when the MCP host sends them through `project_memory`; versioning, ontology mapping, and lineage linking then run automatically. Retrieval mode is server configuration, not a per-call argument. Image retrieval, image embeddings, and visual reranking are not part of research memory. OCR is used only to recover searchable text from scanned PDF pages. Credential and private-key files are excluded from body indexing. HTML exports omit source IDs, local paths, node bodies, plan text, and evidence quotes. The viewer initiates no network requests and opens stripped public HTTP or HTTPS source links only after user action. Project and assertion deletion require a count preview and confirmation token. They create reversible tombstones and preserve evidence and correction history. Fact correction takes only `target_id`, `replacement`, and `reason`; the prior assertion remains as bitemporal history. Plan revisions are append-only. Experiments are bound to the active revision and must be finished explicitly as `success`, `failed`, or `inconclusive`. Logs are not used to infer an outcome. Receipts list stored categories only: ```text Project: Graph memory | Session: temporal graph research | Stored: paper 1 (Graphiti), repo 1 (getzep), search summaries 3 | Status: ready ``` Set `SURF_RESEARCH=false` to keep the database and sidecar closed and omit `project_memory_search` and `project_memory`. Obsidian and Notion sync are not included and will remain project-level opt-in when added. ### Local operations CLI These commands use the same authenticated research broker as MCP sessions. They do not open another embedded database owner or browser: ```powershell npx google-surf-mcp doctor --json npx google-surf-mcp daemon start --background --no-window npx google-surf-mcp memory get --project PROJECT --record RECORD --json npx google-surf-mcp memory sync --project PROJECT --manifest changes.json --json npx google-surf-mcp memory current --project PROJECT --json npx google-surf-mcp job wait --project PROJECT --id JOB --after-revision 0 --json npx google-surf-mcp job cancel --project PROJECT --id JOB --reason "operator request" --json npx google-surf-mcp daemon drain --json ``` `doctor` is passive: it reports process identity, versions, capabilities, queue counters, memory counters, cache bytes, current lifecycle state, foreground/background ownership, checkpoint-drain state, and the exact blockers preventing worker recycling without opening the database, vector model, or graph. The broker drains after meaningful work is idle even if an MCP client remains connected; active requests and commits postpone the drain, while rebuildable background jobs checkpoint at safe stage boundaries under memory pressure. The next request reconnects transparently. ## Env vars | var | default | notes | |---|---|---| | `SEARCH_API` | unset | SearchApi API key. Required only when either provider setting is `searchapi` or `fallback`. Sent as a bearer token and never placed in the request URL. | | `SEARCHAPI_API_KEY` | unset | Alias for `SEARCH_API`. | | `SURF_SEARCH_PROVIDER` | `browser` | Provider for `search` and `search_parallel`: `browser`, `searchapi`, or `fallback`. | | `SURF_SCHOLAR_PROVIDER` | `browser` | Provider for `scholar_search`: `browser`, `searchapi`, or `fallback`. | | `SURF_BROWSER_ENGINE` | `auto` | Browser engine: `auto`, `native`, or `playwright`. Native Chrome performs the request before read-only CDP attachment. | | `CHROME_PATH` | auto-detected | absolute path to Chrome binary | | `SURF_PROFILE_ROOT` | `~/.google-surf-mcp` | where the warm profile lives | | `SURF_RESEARCH` | `true` | enables local project memory, capture, indexing, `project_memory_search`, and `project_memory`; set `false` for search and extraction only | | `SURF_RETRIEVAL_MODE` | `hybrid` | research search route: `live` or `hybrid`; used only when `SURF_RESEARCH=true` | | `SURF_RESEARCH_ROOT` | `/research` | embedded SurrealDB data directory | | `SURF_RESEARCH_DB_ENDPOINT` | unset | optional remote SurrealDB endpoint; requires `wss`/`https`, except `ws`/`http` is allowed for localhost | | `SURF_RESEARCH_DB_NAMESPACE` | `google_surf` | SurrealDB namespace used by the research catalog | | `SURF_RESEARCH_DB_DATABASE` | `research` | SurrealDB database used by the research catalog | | `SURF_RESEARCH_DB_TOKEN` | unset | bearer token for a remote research database; alternatively set `SURF_RESEARCH_DB_USERNAME` and `SURF_RESEARCH_DB_PASSWORD` | | `SURF_RESEARCH_VECTOR_MODEL` | `Xenova/multilingual-e5-small` | local 384-dimensional model used by HNSW vector retrieval and final reranking. The default model revision is pinned; `off` disables the vector lane. | | `SURF_RESEARCH_VECTOR_LOW_MEMORY` | `true` | disables the ONNX CPU memory arena and memory pattern; set `false` to trade higher peak memory for faster initial indexing | | `SURF_RESEARCH_VECTOR_THREADS` | `4` | ONNX intra-op thread count, clamped to 1-16 | | `SURF_RESEARCH_VECTOR_BACKEND` | `hnsw` | vector representation: `hnsw`, content-deduplicated `compact`, or bounded `exhaustive` | | `SURF_RESEARCH_REPO_AUTO` | `true` | automatically sparse-index at most one small, relevant GitHub repository per search call | | `SURF_RESEARCH_REPO_AUTO_MAX_MB` | `20` | maximum searchable source-text size for automatic GitHub indexing; assets are excluded | | `SURF_RESEARCH_REPO_AUTO_MAX_FILES` | `2000` | maximum searchable source file count for automatic GitHub indexing | | `SURF_RESEARCH_BROKER_IDLE_MS` | `60000` | drain delay after the last meaningful work, even when clients remain connected; active requests and background jobs postpone drain | | `SURF_RESEARCH_READ_CONCURRENCY` | `4` | maximum concurrent broker reads; identical in-flight reads share one operation | | `SURF_RESEARCH_QUERY_TIMEOUT_MS` | `120000` | timeout per embedded SurrealDB query, clamped to 1-600 seconds; a timed-out retrieval lane is reported as partial while other lanes still return | | `SURF_RESEARCH_GRAPH_CACHE_MAX_MB` | `64` | byte budget for in-process graph projections and analysis artifacts | | `SURF_RESEARCH_WORKER_SOFT_MEMORY_MB` | `2048` | RSS threshold that requests an immediate idle drain after active work completes | | `SURF_RERANK_TRIGGER_CHARS` | `1500` | shell-output interception threshold (inclusive); sensitive output is sanitized even below this threshold | | `SURF_RERANK_MAX_CHARS` | adaptive: 1500–3000 | optional explicit shell-summary limit, including values above 3000; default is `min(3000, ceil(1500 + 750*log2(max(1,n))))` for distinct query-matching records/blocks, not repeated output volume | | `GITHUB_TOKEN` | unset | optional GitHub token that raises API limits for repository inspection | | `SURF_RESEARCH_CODE_WORKERS` | auto, max 4 | Tree-sitter worker count for initial code structure indexing | | `SURF_LOCALE` | `en-US` | browser locale | | `SURF_TZ` | system tz | e.g. `America/New_York` | | `SURF_HEADLESS` | `true` | Controls Playwright extraction, compatibility, and recovery paths. Native search keeps a normal system Chrome window hidden and shows it only for CAPTCHA recovery. | | `SURF_REMOTE_DEBUG` | `false` | set `true` on a headless server with remote DevTools. CAPTCHA path emits the DevTools port and throws instead of spawning a window; attach `chrome://inspect` from a local machine over SSH port-forward to solve. | | `SURF_CAPTCHA_TIMEOUT_MS` | `180000` | lifetime of the background human-recovery window. MCP calls return immediately and do not wait for this timeout. | | `SURF_IDLE_CLOSE_MS` | `30000` | idle ms before closing the sequential ctx and pool. `0` disables idle auto-close. Lower = faster cleanup, higher = warmer cache for spaced-out calls. | | `SURF_ALLOW_PRIVATE` | `false` | set `true` to allow `extract` to fetch private/loopback addresses (`localhost`, `127.0.0.1`, `10.x`, `192.168.x`, `169.254.x`, etc). Default blocks them as an SSRF guard. | | `SURF_EXTRACT_MAX_CHARS` | `50000` | full extraction limit (200-50000); abstract defaults to 1500 and per-call `max_chars` overrides both | | `SURF_EXTRACT_OCR` | `false` | OCR scanned/image PDFs via Tesseract (slower; off by default) | | `SURF_CLOUD_MODE` | `false` | headless/serverless mode: TLS bypass + `--no-sandbox` + `--disable-dev-shm-usage` + worker pool disabled + fail-fast on CAPTCHA | | `SURF_CASCADE_DISABLED` | `false` | pin a single stealth mode (chosen by `SURF_USE_STEALTH`) instead of the 3-tier auto-cascade | | `SURF_USE_STEALTH` | `true` | initial stealth tier; only consulted when `SURF_CASCADE_DISABLED=true` | | `SURF_HUMANLIKE_MODE` | `background` | `off` / `background` (fire-and-forget after returning results) / `inline` (await before returning, slower) | | `SURF_RATE_LIMIT_PER_MIN` | `10` | internal cap on Google-facing requests per minute | | `SURF_CACHE_TTL_SEARCH_MS` | `86400000` | search cache TTL (24h); `0` disables caching | | `SURF_CACHE_MAX_ENTRIES` | `1000` | LRU cap per cache namespace | | `SURF_CACHE_ROOT` | `/cache` | cache directory | | `SURF_INSECURE_TLS` | `=SURF_CLOUD_MODE` | `--ignore-certificate-errors` (auto-on in cloud mode) | | `SURF_NO_SANDBOX` | `=SURF_CLOUD_MODE` | `--no-sandbox` (auto-on in cloud mode) | | `SURF_TELEMETRY` | `false` | set `true` to enable jsonl event logging (search outcomes, cache hits/misses, tool errors, parser staleness) under `{SURF_TELEMETRY_ROOT}`. Designed as the input feed for the self-healing pipeline. Off by default. | | `SURF_TELEMETRY_ROOT` | `/telemetry` | directory for jsonl telemetry files. UTC-dated one file per day (`YYYY-MM-DD.jsonl`). | | `SURF_SELF_HEALING` | `true` | per-strategy outcome tracking + persisted reordering. Healing must win by 3 outcomes before reorder kicks in, so single-call flapping is impossible. Set `false` to pin the default strategy order. | | `SURF_SELF_HEALING_FILE` | `/.heal/strategy-order.json` | persistence path for healing state. Atomic tmp+rename writes; debounced 5s. | | `SURF_LLM_HEAL` | `false` | opt-in for LLM-assisted selector repair in the workflow-only `repairWithLLM` helper. Off by default, so no third-party LLM request fires. | | `SURF_LLM_PROVIDER` | `anthropic` | LLM repair provider: `anthropic` or `orcarouter`. | | `SURF_LLM_MODEL` | provider default | model for LLM-assisted repair. Defaults to `claude-sonnet-4-6` for Anthropic and `orcarouter/auto` for OrcaRouter. | | `ANTHROPIC_API_KEY` | unset | Anthropic key used only when LLM repair is enabled with the Anthropic provider. | | `ORCAROUTER_API_KEY` | unset | OrcaRouter key used only when LLM repair is enabled with the OrcaRouter provider. | | `ORCA_KEY` | unset | Alias for `ORCAROUTER_API_KEY`. | ### OrcaRouter ```env SURF_LLM_HEAL=true SURF_LLM_PROVIDER=orcarouter ORCAROUTER_API_KEY=... SURF_LLM_MODEL=orcarouter/auto ``` ## Troubleshooting - Native search keeps the current session open and shows Chrome when a CAPTCHA appears. Solve it in that window and retry; the next call verifies the page, restores the hidden window guard, and continues with the same session. SearchApi fallback remains available through `SURF_SEARCH_PROVIDER=fallback` and `SURF_SCHOLAR_PROVIDER=fallback`. - Playwright CAPTCHA recovery has 4 modes (picked automatically from env): - default (local desktop): OS notification fires, headed Chrome opens, and the call returns; solve it and retry - `SURF_HEADLESS=false`: headed Chrome opens without a notification; solve it and retry - `SURF_REMOTE_DEBUG=true`: DevTools port + instructions printed, attach `chrome://inspect` locally to solve - `SURF_CLOUD_MODE=true`: fail-fast with `CAPTCHA_REQUIRED` error - **Headed Chrome opens to a plain search box instead of CAPTCHA**: just type any query in the box and press Enter. Subsequent calls work. - "Chrome not found": install Chrome or set `CHROME_PATH`. - Stale selectors: runtime per-strategy reorder (`SURF_SELF_HEALING`, deterministic) plus a manually dispatched repair workflow (`SURF_LLM_HEAL` optional, human review required, never auto-merged). - Playwright searches feel slower than expected: check `health().pool.fallback`. `true` means the worker pool is using a single context. Native search uses one authenticated local browser broker across MCP sessions. The broker keeps one hidden Chrome process with up to four reusable tabs for `search`, `search_parallel`, and `scholar_search`. Query starts are staggered. A CAPTCHA shows and preserves that session for user recovery, then the window guard is restored on the next call. A browser crash starts a new session on the next call. - SSRF: `extract` blocks `localhost`, private IPs, AWS metadata by default. Set `SURF_ALLOW_PRIVATE=true` to allow them. - Cache cleanup: `npm run cache:clear` removes search/extract and downloaded vector-model caches. It does not remove the research DB. - The local research DB is not application-encrypted. Use OS account permissions and disk encryption such as BitLocker or FileVault when the machine or backups need at-rest protection. ## Changelog See [CHANGELOG.md](./CHANGELOG.md). ## License MIT