HubSpot Connector

Armbrain's HubSpot connector is a read-only, per-client mind CRM ingest. Connect it from an active client or prospect mind with:

connectors action=connect source_type=hubspot

The tool returns an Armbrain-generated HubSpot OAuth URL. Do not send customers into HubSpot's App Marketplace Claude integration or HubSpot's direct Claude connector; that is a different product path and does not connect Armbrain's auto-ingest pipeline.

After OAuth succeeds, discovery runs on the normal connector poll cadence, defaulting to 15 minutes. The first sync starts a historical backfill, defaulting to two years of HubSpot CRM history, before settling into incremental updates.

Beta Customer Setup Script

Use this copy when walking a beta customer through setup:

1. In Armbrain, switch to the client/prospect mind that should receive HubSpot data.
   Example: switch to CLIENT

2. Ask Armbrain to create the HubSpot OAuth link:
   connectors action=connect source_type=hubspot

3. Open the returned auth_url in your browser and approve Armbrain's read-only HubSpot app.

4. Return to Armbrain and check:
   connectors action=status

Expected result: the connector moves from pending_setup to active, syncing, or backfilling. Backfill can take time on large portals; normal incremental polling runs about every 15 minutes.

Do not ask the customer for a HubSpot private app token, personal access key, developer API key, service key, client secret, or direct Claude connector install. The v1 connector is OAuth-only and read-only.

OAuth Scopes

The connector requests read scopes for the v1 CRM ingest:

• crm.objects.contacts.read
• crm.objects.companies.read
• crm.objects.deals.read
• crm.objects.owners.read
• crm.schemas.contacts.read
• crm.schemas.companies.read
• crm.schemas.deals.read

HubSpot's current notes, calls, meetings, and tasks APIs authorize read access

through the already-required crm.objects.contacts.read scope. Armbrain does

not send a separate optional_scope parameter for those activity types. If a

portal still rejects one activity endpoint, that type is skipped and recorded

in connectors action=status under hubspot_diagnostics.optional_skipped

instead of failing the core CRM connector.

It does not request sales email scopes and does not write back to HubSpot.

The HubSpot user approving OAuth must be allowed to install apps and grant the CRM read scopes above. If app installation is restricted, a HubSpot admin needs to approve the Armbrain app.

What Gets Ingested

The initial backfill reads:

• Contacts, companies, and deals modified inside the configured historical window.
• The default window is two years back from first successful sync.
• A custom ISO timestamp can be stored in connectors.config.hubspot_backfill_since before sync starts when a shorter or longer backfill is needed.

After backfill completes, each incremental sync reads:

• Contacts, companies, and deals changed since the connector watermark.
• HubSpot property definitions for contacts, companies, and deals.
• Owner records for resolving hubspot_owner_id.
• Deal associations to contacts and companies, so deal memories can include company and customer geography context.
• All property names returned by the property definition API. Required properties are pulled during search; records are then hydrated through batch reads so custom fields can be preserved when HubSpot accepts the full property set.

If full-property hydration fails for an account, the connector falls back to the required search properties and records the error in connector logs.

Activity and Note Ingestion (v2)

Once the historical CRM backfill has finished, each incremental sync also reads recent HubSpot notes, calls, meetings, and tasks (engagement objects), each associated back to their deals, contacts, and companies:

• Activity ingestion is deliberately deferred until the CRM backfill is complete, so a fresh connector's first (potentially long) historical backfill isn't competing with activity volume.
• Each poll looks back from the last successful activity sync (or 30 days on the first activity poll) and is capped at 25 records per object type, so activity ingestion cannot overwhelm memory volume the way an unbounded engagement history could.
• Empty or auto-logged boilerplate engagement records (no note body, "left voicemail", "no answer", etc.) are filtered out before they are ever queued or written as memories.
• Each activity's deal/contact/company associations are resolved the same way deal associations are, so activity memory content and provenance can reference "deal X" / "contact Y" / "company Z" by name.
• Activity ingestion runs independently of the CRM reporting store and scheduled synthesis below — it feeds memories directly and does not (yet) feed aggregate/report recomputation.

If a HubSpot API call for notes, calls, meetings, or tasks fails, that object type is skipped for the poll; it does not block contacts/companies/deals sync. See hubspot_diagnostics.optional_skipped in connectors action=status.

Scheduled Marketing Synthesis

Per-record HubSpot ingest still runs on the normal connector poll cadence, defaulting to every 15 minutes. Strategic HubSpot synthesis runs slower so memory search is not spammed:

• Default synthesis cadence is weekly.
• Set connectors.config.hubspot_synthesis_cadence to monthly for monthly recompute.
• Synthesis waits for the historical backfill to finish before publishing summaries.
• Queue source refs are stable within the cadence period, so retries do not enqueue duplicate summary work.
• Aggregate memory pointers store aggregate_connector_id, aggregate_period_key, and aggregate_scope, and memory source refs are derived from those fields so multiple HubSpot portals connected to one client mind do not overwrite each other's summaries.

Scheduled synthesis reads from the normalized HubSpot reporting store (hubspot_crm_objects and associations), scoped to the current connector. Weekly/monthly cadence controls refresh timing; the memory text is explicitly labeled as all synced HubSpot CRM history through the refresh date. It recomputes:

• Channel/source performance and closed-won revenue.
• Customer geography from deal-contact/company associations.
• Lead disqualification and lead-leak reasons, including source denominators where available.
• Closed-lost themes.
• A sensitive strategy synthesis fact that summarizes the strongest source, leaks, geography, loss themes, a notable high-value deal signal, and the next planning move to inspect.

Backfill progress is reported by connectors action=status in the hubspot_backfill object:

• status: running or complete
• since: historical window start
• started_at / completed_at
• counts: records discovered so far by object type
• state: per-object pagination state

The same status response also includes hubspot_diagnostics for each HubSpot connector:

• operational_state: active, syncing, backfilling, draining_queue, queue_backed_up, synthesis_error, stale, setup_error, auth_error, rate_limited, or error.
• last_successful_hubspot_pull, last_queue_enqueue, queue, and queue_state.
• records_pulled_by_type, last_poll_record_counts_by_type, latest_deal_seen, and aggregate_recompute_at.
• synthesis_cadence, synthesis_period_key, synthesis_recomputed_at, synthesis_count, synthesis_skipped_reason, and synthesis_last_error.
• persistent_errors for auth, rate-limit, or scope failures.

If OAuth approval returns to Armbrain but the token exchange fails, the connector remains pending_setup and status surfaces last_error plus hubspot_diagnostics.setup_error instead of silently showing no error detail.

Troubleshooting Setup

If the customer sees:

This account is not eligible to connect to Claude

they are in HubSpot's direct Claude integration flow, not the Armbrain HubSpot connector flow. Send them back to Armbrain and have them open the auth_url returned by connectors action=connect source_type=hubspot.

connectors action=connect source_type=hubspot and connectors action=status include setup_help with the correct flow, permission requirements, and the exact wrong-flow error text for support handoffs.

Memory Mapping

HubSpot records are not sent through generic text extraction. They are mapped directly to readable memories:

Memory text uses resolved labels for stages, lifecycle stages, lead statuses, source values, and owners. Raw HubSpot enum IDs should not appear in memory content.

Filtering

The provider drops internal/test contacts before queueing memories when either condition matches:

• The contact email exactly matches connectors.config.hubspot_excluded_emails or connectors.config.excluded_emails.
• The contact email domain matches the pinned client mind's company_info.domain / company_info.domains, connectors.config.hubspot_excluded_email_domains, connectors.config.hubspot_excluded_domains, or connectors.config.excluded_email_domains.

Simple property filters can be stored in connectors.config.hubspot_property_filters or connectors.config.hubspot_filters, either as a flat property map or scoped by object type:

{
  "hubspot_property_filters": {
    "deals": { "pipeline": "default" },
    "contacts": { "hs_lead_status": ["NEW", "OPEN"] }
  }
}

CRM Report Date Basis

memory defaults revenue-style reports to HubSpot closedate, which matches normal closed-won revenue reporting. The response includes the selected basis in period.date_basis, period.date_basis_label, and period.hubspot_property; detailed deal rows include both close_date and report_date.

Use date_basis=hs_lastmodifieddate when validating deals that were edited recently but may have been backdated into an earlier close-date period. Supported values are:

• closedate
• hs_closed_won_date
• date_entered_closed_won
• date_entered_current_stage
• hs_lastmodifieddate

CRM Report Trust Metadata

Every memory response includes a trust block before revenue/source conclusions. It records the synced HubSpot reporting store as the data source, whether live fallback was used, portal IDs, connector IDs, client mind/customer IDs, last successful sync, report range, date basis, configured filters, record counts, freshness status, and backfill completeness.

If HubSpot sync is stale or historical backfill is still running, the first entries in audit.caveats say so before the report conclusions. Use those warnings when answering whether the report reflects the latest HubSpot activity.

Disconnect

connectors action=disconnect connector_id=<id> revokes the stored HubSpot token best-effort, clears encrypted credentials, marks the connector inactive, and stops future polling. Existing memories are preserved.