Skip to content
fzymgc-house Cluster Docs

Send engram's memory corpus to Google's paid Gemini embedder (gemini-embedding-2), accepting a limited-retention, not-ZDR posture

Date: 2026-07-10 Status: Accepted — supersedes hl-57x5 Deciders: Sean Brandt

Context

Section titled “Context”

engram’s embedder currently runs Qwen3-Embedding-8B (4096-dim) via OpenRouter under a multi-provider Zero-Data-Retention (ZDR) contract (per hl-57x5), writing to the current memory_v3 Qdrant collection (from the 2026-07-02 tags-in-vector reindex; hl-57x5 itself established memory_v2). OpenRouter’s ZDR guarantee means the durable personal-memory corpus is not retained by any embedding upstream.

Milestone v1.2 migrates engram’s embedder direct to Google Gemini (gemini-embedding-2), not via OpenRouter. Going “direct to Google” changes the data-retention posture: the Google embedding endpoints do not carry OpenRouter’s ZDR contract. Because engram embeds a durable store of the operator’s personal memories, that corpus would transit and be handled by Google under Google’s own retention terms. This forces a data-residency decision before any real corpus content leaves the cluster for Google.

This is deliberately a governance and documentation gate only — no Google credential, no agentgateway backend, and no route are introduced here. Those are built in later milestone phases; this ADR authorizes and records the crossing so the tradeoff is on the record, not silent.

The prior cloud-embedding design (docs/engineering/specs/2026-06-13-engram-cloud-embedding-migration-design.md) evaluated and rejected gemini-embedding-001 on cost and retrieval grounds and locked the OpenRouter-ZDR posture. This ADR reverses that posture consciously.

Decision

Section titled “Decision”

Send engram’s durable memory corpus to Google’s paid Gemini Developer API — host generativelanguage.googleapis.com, API-key / Bearer authentication, billing-enabled; never the free / AI-Studio tier — for model id gemini-embedding-2.

Accepted retention terms, stated verbatim so the tradeoff is on the record:

  • Google does not train on paid-tier content.
  • Google retains paid-tier content for a limited abuse / legal window.
  • This is explicitly NOT contractual ZDR. It is a conscious reversal of the prior OpenRouter-ZDR posture (hl-57x5 and the 2026-06-13 cloud-embedding design).

The downstream API key is a Vault-sourced credential plumbed in a later phase (Phase 20); it is referenced here only generically. This ADR ships no credential, backend, or route.

Rationale

Section titled “Rationale”
  • gemini-embedding-2 over the previously rejected gemini-embedding-001. hl-57x5 and the 2026-06-13 design rejected gemini-embedding-001 on cost (≈15× Qwen3-8B) and retrieval (−3.17 points vs Qwen). The newer gemini-embedding-2 is GA and carries an 8192-token input window that directly accommodates the large records this milestone re-summarizes (the gemini-embedding-001 era 2048-token limit would have forced chunking of exactly those records). The move to Gemini is a standing user directive for milestone v1.2; this ADR justifies choosing Gemini now rather than restating the old rejection.
  • Paid tier removes the primary irreversible risk. The one catastrophic, irreversible outcome for a durable personal-memory store is an upstream training on its content. The paid Developer API does not train on submitted content, which removes that risk. What remains is a bounded, time-limited retention window — a materially smaller and reversible exposure.
  • Bounded tradeoff, consciously accepted. Accepting a limited-retention window in place of OpenRouter multi-provider ZDR is a deliberate, bounded tradeoff for the simplest direct-to-Google path, not an oversight. Recording it here is the point of the gate.

Alternatives Considered

Section titled “Alternatives Considered”
  • Vertex AI (true ZDR via an enterprise DPA) — considered and NOT chosen. Vertex AI can provide contractual ZDR through a Data Processing Addendum, but it adds a GCP project plus service-account / OAuth overhead for no meaningful benefit in a homelab once the paid tier has already removed the training risk. The residual limited-retention window does not justify that operational weight.
  • Free / AI-Studio tier — rejected. The free tier trains on submitted content. For a durable store of the operator’s personal memories that is catastrophic and irreversible; it must never be used.
  • Stay on Qwen3-Embedding-8B via OpenRouter ZDR — superseded. This is the hl-57x5 posture; it is reversed by the directive to move engram’s embedder direct to Google Gemini for this milestone.

Consequences

Section titled “Consequences”

Positive:

  • The data-residency tradeoff is on the record and signed off, not silent — the reversal of the prior OpenRouter-ZDR posture is a documented, attributable decision.
  • Simplest direct-to-Google path: API-key auth against the paid Developer API, no GCP project, no service account.
  • Training on the personal-memory corpus — the one irreversible risk — is off the table.

Negative:

  • A limited-retention window is accepted; this is NOT ZDR. The durable personal-memory corpus will transit and be retained by Google, for a bounded period, under this posture.
  • A later phase (Phase 20) must plumb the Vault-sourced paid API key before any content is actually sent.

Neutral:

  • This change ships no credential, backend, or route, and lands first in milestone git history — before any Google-facing artifact exists in the repo.

Sign-off: decision, date (2026-07-10), and deciders (Sean Brandt) are recorded above. Human approval of the pull request that lands this ADR is the sign-off for the data-residency decision.