fix(boot): make rebuildIndex non-blocking so viewer + later boot steps run

[efenex]

Summary

The worker boot flow in src/index.ts awaits rebuildIndex(kv) before reaching startViewerServer (and several other boot steps). rebuildIndex iterates every observation across every session and AWAITS an embedding-provider call per record. On a real corpus + a rate-limited embedding endpoint that takes hours to days, and everything that runs after it is silently delayed for the same duration.

Symptom in the wild

Operator imports a sizable jsonl corpus (in our case 320 sessions / ~500k observations), restarts agentmemory with EMBEDDING_PROVIDER pointed at any rate-limited OpenAI-compat endpoint (Novita / DeepInfra / etc., typically 100 RPM on the cheap plans), and:

• ✅ REST API on :3111 responds normally
• ❌ Viewer on :3113 is never reachable (no listening socket)
• ❌ agentmemory doctor reports viewer-unreachable
• 🌊 Log floods with vector-index add: embed failed — skipping {429: ...} from the still-running rebuild burning the embedding rate limit
• No error message — the worker stays alive serving HTTP because sdk.registerFunction calls had already completed synchronously before the rebuild hung

The "obvious" workaround of agentmemory stop && agentmemory just re-enters the same hang.

Root cause

// src/index.ts
const needsRebuild = bm25Index.size === 0;

if (needsRebuild) {
  const indexCount = await rebuildIndex(kv).catch(...);   // ← hours-to-days
  ...
}

// ...
const viewerServer = startViewerServer(viewerPort, ...);  // ← never reached

rebuildIndex(kv) (in src/functions/search.ts) per-record awaits vectorIndexAddGuarded(...) which calls the embedding provider. For a ~500k-observation corpus at 100 RPM = 5,000 minutes = 3.5 days. The viewer / auto-forget / lesson-decay / consolidation timers all sit behind it.

Fix

Detach with void + .then/.catch. The index lazily fills in over hours; search degrades gracefully (BM25 keeps working immediately, vector results fill in as the embed queue drains); the viewer + everything else in main() come up in seconds.

void rebuildIndex(kv)
  .then((indexCount) => {
    if (indexCount > 0) {
      bootLog(`Search index rebuilt: ${indexCount} entries`);
      indexPersistence.scheduleSave();
    }
  })
  .catch((err) => {
    console.warn(`[agentmemory] Failed to rebuild search index:`, err);
  });

Verification

Tested live on the affected corpus before and after:

Before: every restart left lsof -ti :3113 empty, doctor reported viewer-unreachable, log showed 429s pile up indefinitely.

After: viewer binds within ~5 seconds of starting, returns the full 188 KB HTML payload on GET /. Rebuild continues in the background; vector search results improve over the following minutes.

Test plan

No unit tests added. main() isn't unit-tested today and wiring up a fake slow rebuildIndex + asserting the post-rebuild boot lines run early would need the full worker mock harness — disproportionate to a one-line behavior change. The failure mode is dramatic enough that visual review + integration smoke covers regression risk.

Files

• src/index.ts — 18 insertions, 10 deletions (mostly the comment explaining the rationale)

Related

Surfaced while operating an agentmemory install against a 320-session bulk-imported corpus. The 429 floods that finally pointed at this had me chasing port-conflict / stale-process explanations first (see #474). The real cause is here.

Summary by CodeRabbit

• Chores
  • Improved application boot performance by optimizing search-index initialization to run in the background without blocking startup steps.

[vercel]

@efenex is attempting to deploy a commit to the rohitg00's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6c010713-b1c4-4ce1-b280-08f8ac21bfc9

📥 Commits

Reviewing files that changed from the base of the PR and between caa9f52 and ecd8024.

📒 Files selected for processing (1)

• src/index.ts

---

📝 Walkthrough

Walkthrough

The PR converts the search-index rebuild path in main() from synchronous awaited blocking to non-blocking background execution. When needsRebuild is true, the rebuild promise is initiated without blocking boot, logs and schedules persistence conditionally when the count exceeds zero, and handles errors via separate catch logic.

Changes

Search Index Non-Blocking Rebuild

Layer / File(s)	Summary
Convert search index rebuild to non-blocking background operation src/index.ts	Rebuild now executes in the background via promise chains instead of awaiting, logs success and schedules persistence only when indexCount > 0, and catches errors without aborting boot.

Sequence Diagram(s)

The change modifies internal control flow within a single function without introducing multi-component interactions or new features, so no sequence diagram is generated.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 The index rebuilds now, a gentle ghost in the night,
No longer blocking the boot with its might!
Fire-and-forget, a non-blocking delight,
Persistence awaits when the count shines bright.
Errors caught gently, all systems stay light! 🌙

🚥 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly captures the main change: making rebuildIndex non-blocking to allow viewer and subsequent boot steps to run, which matches the primary objective of the PR.
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

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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