feat(memory): add createSupermemoryClient factory

[khaliqgant]

Summary

• New createSupermemoryClient(options) factory in @agent-assistant/memory
• Wraps the official supermemory SDK (v4.21.1) with the timeout / retry / fetch wiring sage shipped in PR #198
• Worker-safe EnvSource shape (no NodeJS.ProcessEnv in public surface, no process access at the no-arg path)
• Independent of AA feat(proactive): runFollowUpBatch + decidePostingPolicy + block-counter interface #82 — different package, different surface
• 7 new tests; existing 77 memory tests still pass; build + types clean

Why

Sage shipped this factory locally at src/integrations/supermemory-client.ts in PR #198 to fix the prod SEARCH_ERROR outage. It centralises 4 call sites that previously had subtly different defaults for endpoint, timeout, retries, and fetch wiring. Moving it upstream so future AA consumers don't reimplement the same wrapper.

Surface

export type EnvSource = Readonly<Record<string, string | undefined>>;

export interface CreateSupermemoryClientOptions {
  timeoutMs?: number;        // default 8000
  maxRetries?: number;       // default 2
  env?: EnvSource;           // default: globalThis.process?.env ?? {}
  apiKeyEnvVar?: string;     // default 'SUPERMEMORY_API_KEY'
  endpointEnvVar?: string;   // default 'SUPERMEMORY_ENDPOINT'
  fetch?: typeof globalThis.fetch;
}

export function createSupermemoryClient(
  options?: CreateSupermemoryClientOptions,
): Supermemory | null;  // null when no API key

Design notes

• Defaults from sage's prod-validated PR #198. timeout: 8s is the per-call cap that fixed the 2026-05-04 SEARCH_ERROR outage; maxRetries: 2 matches the SDK default but is surfaced explicitly so callers know 5xx retries are happening.
• Per-call globalThis.fetch closure. The SDK captures fetch at construction; without the closure, vi.stubGlobal('fetch', ...) set after construction is invisible. The SDK already calls fetch.call(undefined, url, init) internally to dodge the Cloudflare Workers "Illegal invocation" foot-gun (sdk-ts/src/client.ts:594), so passing the closure is purely for test ergonomics.
• Worker-safe public surface. Same shape as AA PR feat(proactive): runFollowUpBatch + decidePostingPolicy + block-counter interface #82's readFailOpenFromEnv fix: EnvSource instead of NodeJS.ProcessEnv, no-arg path reads globalThis.process?.env ?? {} so Workers without nodejs_compat get null (no API key) instead of a process is not defined ReferenceError.
• Configurable env var names. apiKeyEnvVar / endpointEnvVar lets surfaces namespace their secrets (e.g. MY_APP_SUPERMEMORY_API_KEY). Defaults match the de-facto Supermemory conventions.
• Returns null on missing key. Callers no-op cleanly during local dev without a separate env-presence check. Sage's existing call sites already handle this branch.

Test plan

• cd packages/memory && npm test — 84/84 pass (77 existing + 7 new)
  • missing / blank API key returns null
  • present API key constructs an SDK instance
  • custom apiKeyEnvVar honored
  • fetch override threaded to SDK
  • default endpoint
  • SUPERMEMORY_ENDPOINT override
  • delete globalThis.process Worker simulation does not throw
• npm run build clean
• No NodeJS.ProcessEnv / node:process in dist/supermemory-client.d.ts public signatures (only docstring mentions explaining why)

Out of scope (follow-up)

• Version bump — handled by separate chore(release) commit per the existing convention
• Sage adoption — src/integrations/supermemory-client.ts becomes a thin re-export alias for one minor compat cycle, then deletes; staged at sage workflows/proactive-batch-runner/03-aa-memory.ts + 04-sage-adopt.ts

Sequence status

PR	Repo	Status
sage #200	sage	✅ Merged
AA #81 (boundedParallel)	agent-assistant	✅ Merged → @agent-assistant/coordination@0.4.25
AA #82 (runFollowUpBatch + policy + counter)	agent-assistant	🟡 Open (review fix landed)
This PR	agent-assistant	🟡 Open (independent of #82)
sage #4 (adoption)	sage	⏳ Blocks on AA #82 + this PR publishing

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5b01fb196a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Regenerate lockfile after adding supermemory dependency

Adding "supermemory": "^4.21.1" to packages/memory/package.json without the corresponding package-lock.json update breaks reproducible installs and can fail CI on a clean checkout. I checked the repo workflows and both .github/workflows/ci.yml and .github/workflows/publish.yml run npm ci, which requires the lockfile to match package manifests; this commit introduces a new runtime dependency but leaves the lockfile out of sync.

Useful? React with 👍 / 👎.

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7d158c23-cb8b-4bd7-aac3-5cadd8cab422

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The PR introduces a new Supermemory SDK integration to the @agent-assistant/memory package by adding a factory function that constructs authenticated Supermemory clients from environment variables and optional configuration overrides, along with comprehensive test coverage and public API exports.

Changes

Supermemory SDK Integration

Layer / File(s)	Summary
Configuration Types packages/memory/src/supermemory-client.ts	New exports: EnvSource (readonly string/undefined record), CreateSupermemoryClientOptions interface with optional timeoutMs, maxRetries, env, apiKeyEnvVar, endpointEnvVar, and fetch fields.
Core Factory packages/memory/src/supermemory-client.ts	createSupermemoryClient(options?) resolves API key and endpoint from injected or process env, returns null if API key is missing/blank, otherwise constructs and returns a Supermemory instance with configured timeout, retries, and fetch implementation.
Public API packages/memory/src/index.ts	Re-exports createSupermemoryClient function and CreateSupermemoryClientOptions, EnvSource types from the new module.
Dependency Declaration packages/memory/package.json	Runtime dependency supermemory@^4.21.1 added to support SDK instantiation.
Test Coverage packages/memory/src/supermemory-client.test.ts	Seven Vitest tests verify: null return when API key is missing/whitespace, successful client construction with valid key, custom API key env var support, fetch override forwarding, default and custom endpoint handling, and safe operation in environments without globalThis.process.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Supermemory now takes root,
with SDK clients dressed to boot,
Environment whispers, configs in flight,
Factory patterns holding tight!
Tests keep watch through day and night. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: adding a new createSupermemoryClient factory function to the memory package.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, explaining the factory's purpose, design decisions, test coverage, and implementation details.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/memory-supermemory-client

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}