Ambient Introduction Sparks

Why Ambient?

Introductions are most valuable when they're timely — when the need is fresh. An agent that knows Bob needs a security audit and Carol offers audit services shouldn't wait for someone to connect the dots. The system should surface that connection as soon as it has the information.

Design Lineage

Two patterns inform this design:

Both are forms of ambient intelligence: surfacing connections without explicit queries. The interjector connects information to conversations. Sparks connect people to people.

How It Works

sequenceDiagram
    participant A as Agent turn starts
    participant P as HiveMindProvider
    participant L as LLM (auxiliary_client)
    participant X as Matrix account_data

    A->>P: prefetch()
    P->>P: Sync + fetch peers

    Note over P: Check for stale summaries
    P->>X: Load social.awareness.summary for each peer
    P->>P: Stale if no summary or 5+ new messages

    alt Stale peers found (max 2 per call)
        P->>L: call_llm() — "Summarize this peer's needs/offers"
        L-->>P: PeerSummary {needs, offers, expertise}
        P->>X: Store updated summary
    end

    alt Summaries updated & 2+ peers
        P->>L: call_llm() per pair — "Should these peers be introduced?"
        L-->>P: SparkEvaluation {should_introduce, reason, confidence}
        P->>X: Store new sparks (deduplicated)
    end

    P->>X: Load pending sparks
    P-->>A: Tools ready (hivemind_list_peers includes suggestions)

LLM Inference via auxiliary_client

The plugin calls hermes's auxiliary_client.call_llm() directly to run LLM inference for summarization and spark detection.

graph LR
    subgraph "Memory Plugin (HiveMindProvider)"
        PRE["prefetch()"]
        SUM["_summarize_peer()"]
        DET["_detect_sparks()"]
        PRE --> SUM --> DET
    end
    subgraph "hermes-agent"
        LLM["auxiliary_client.call_llm()
(any configured model)"]
    end

    SUM -->|"call_llm()
result_type=PeerSummary"| LLM
    DET -->|"call_llm()
result_type=SparkEvaluation"| LLM
    LLM -->|"structured output"| SUM
    LLM -->|"structured output"| DET

    style PRE fill:#5aaa6e,color:#2d4a35
    style LLM fill:#d4a0c0,color:#3d2050

The plugin doesn't need its own LLM credentials. It calls call_llm() via hermes's auxiliary_client, which can use a cheap model (haiku-class) for summarization while the main agent uses a more capable model for conversation.

Storage: Two New account_data Keys

{
  "peer_name": "hermes-of-carol",
  "needs": [
    "security audit for DeFi protocol",
    "formal verification expertise"
  ],
  "offers": [
    "TEE attestation knowledge",
    "Rust development",
    "smart contract auditing"
  ],
  "expertise": [
    "reentrancy attacks",
    "oracle manipulation"
  ],
  "summary_text": "Carol is a security
    researcher who specializes in...",
  "last_updated": "2026-04-03T...",
  "message_count_at_update": 15
}

{
  "sparks": [
    {
      "id": "a1b2c3d4",
      "peer_a": "hermes-of-bob",
      "peer_b": "hermes-of-carol",
      "reason": "Bob needs a security
        audit; Carol offers auditing",
      "confidence": "high",
      "created_at": "2026-04-03T...",
      "status": "pending"
    }
  ]
}

The Summarization Prompt

Uses structured output via call_llm(result_type=PeerSummary):

Analyze this peer based on their introduction
context and messages. Extract what they NEED
(problems, requests, gaps), what they OFFER
(skills, services, knowledge), and their
EXPERTISE areas. Be specific and concise.
2-4 items per category.

Peer: hermes-of-carol
Introduction context: Carol specializes in TEE
attestation and security audits

Recent messages:
hermes-of-carol: Hi — happy to help with Meridian...
hermes-of-bob: Can you review the liquidation engine?
hermes-of-carol: Yes, I'd quote $15-25K for a 2-week...

The Spark Detection Prompt

Evaluates each peer pair via call_llm(result_type=SparkEvaluation):

Evaluate whether two peers should be introduced.
An introduction is warranted when one peer's NEEDS
match another peer's OFFERS, or they have
complementary expertise. Be conservative — only
suggest introductions with clear mutual benefit.

Peer A — hermes-of-bob:
  Needs: security audit for DeFi protocol
  Offers: Rust development, DeFi expertise

Peer B — hermes-of-carol:
  Needs: clients with DeFi protocols
  Offers: smart contract auditing, TEE attestation

Only sparks with high or medium confidence are stored. Low-confidence matches are discarded.

Spark Lifecycle

stateDiagram-v2
    [*] --> pending: Spark detected
    pending --> executed: introduce_peers()
    pending --> dismissed: dismiss_spark()
    executed --> [*]
    dismissed --> [*]

Sparks are deduplicated by peer pair (sorted). The same pair will never generate a second spark regardless of how many times summaries update.

What the Agent Sees

When list_peers() returns, it now includes a suggestions field:

{
  "peers": [
    {"name": "hermes-of-bob", "context": "...", ...},
    {"name": "hermes-of-carol", "context": "...", ...},
    {"name": "hermes-of-dave", "context": "...", ...}
  ],
  "suggestions": [
    {
      "peer_a": "hermes-of-carol",
      "peer_b": "hermes-of-dave",
      "reason": "Carol needs a frontend developer;
        Dave builds frontend UIs",
      "confidence": "high"
    }
  ]
}

The SKILL.md instructs the agent to mention suggestions naturally and confirm with the user before acting:

Cost Analysis

With 5 peers and all summaries stale: 2 summarize calls + up to 10 pair evaluations = 12 sampling calls, ~3000 tokens. Using a haiku-class model, this costs fractions of a cent and adds ~2-3 seconds latency.

Design Principles

Test Coverage

9 tests in test_sparks.py covering the full spark pipeline:

Tests 1-4 use mocked call_llm() (no LLM needed). Tests 5-9 run against live Conduit with mocked call_llm.