fix: prevent stdout pollution breaking MCP JSON protocol

[Tapiocapioca]

Summary

Hey Jesse! 👋

Gran lavoro con episodic-memory, è fantastico! Ho trovato un piccolo bug e ho già preparato il fix - magari ti può aiutare!

The Problem

The embeddings.ts module outputs messages to stdout via console.log and @xenova/transformers progress callbacks. In MCP context, stdout is reserved for JSON-RPC communication, so any non-JSON output corrupts the protocol.

Error seen in Claude Code debug logs:

MCP server "plugin:episodic-memory:episodic-memory": Connection error: Unexpected token 'L', "Loading em"... is not valid JSON
MCP server "plugin:episodic-memory:episodic-memory": Connection error: Unexpected token 'E', "Embedding "... is not valid JSON

The Fix

• Changed console.log → console.error for status messages (stderr is safe in MCP)
• Added { progress_callback: null } to silence @xenova/transformers progress output
• Configured env settings to prevent additional stdout pollution

Testing

Tested and verified working in Claude Code 2.1.2 on Windows 11.

---

Related issue: #47

🤖 Generated with Claude Code

Summary by CodeRabbit

• Refactor

  • Optimized embedding pipeline initialization and logging output.
  • Enabled support for local model execution.
  • Modified browser cache behavior for improved performance.

• Documentation

  • Added clarifying comments to configuration settings.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The embeddings module is configured to use local models, disable browser caching, suppress pipeline initialization progress output to reduce noise, and redirect logging output from stdout to stderr for improved clarity.

Changes

Cohort / File(s)	Summary
Embeddings Configuration src/embeddings.ts	Added environment configuration (allowLocalModels = true, useBrowserCache = false); suppressed pipeline progress output via progress_callback: null; switched logging from console.log to console.error; included documentation comments

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related issues

• Bug: console.log in embeddings.ts breaks MCP JSON protocol #47: This PR directly addresses the same code-level fixes (env configuration, progress callback suppression, and logging output redirection in src/embeddings.ts)

Poem

🐰 A quiet hop through configs neat,
Local models, no browser heat,
Stderr whispers, stdout's gone,
Progress silent—we march on!

🚥 Pre-merge checks | ✅ 2 | ❌ 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 (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main fix: preventing stdout pollution that breaks the MCP JSON protocol by switching logging to stderr and disabling progress output.

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

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6feaa5b and 85c8164.

📒 Files selected for processing (1)

• src/embeddings.ts

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-12-21T08:52:59.897Z

Learnt from: techjoec
Repo: obra/episodic-memory PR: 37
File: src/summarizer.ts:5-31
Timestamp: 2025-12-21T08:52:59.897Z
Learning: When using the Claude Agent SDK query() in TypeScript, ensure Options.env is merged with the current process.env. The env type is { [envVar: string]: string | undefined }. Create a merged env object (e.g., const env = { ...process.env, ...options.env };) and pass env to the subprocess so essential environment variables are preserved while allowing overrides.

Applied to files:

• src/embeddings.ts

🧬 Code graph analysis (1)

src/embeddings.ts (1)

dist/embeddings.js (1)

• embeddingPipeline (2-2)

🔇 Additional comments (4)

src/embeddings.ts (4)

1-1: LGTM: Import addition is appropriate.

Adding env to the imports is necessary for configuring the @xenova/transformers environment settings used below.

---

12-12: LGTM: Redirecting logs to stderr is correct for MCP.

Changing console.log to console.error ensures status messages go to stderr instead of stdout, preventing interference with JSON-RPC communication on stdout.

Also applies to: 18-18

---

3-6: Update the comment placement to clarify which setting suppresses progress output.

The environment settings env.allowLocalModels = true and env.useBrowserCache = false are appropriate for Node.js, but they don't directly suppress progress callbacks. The actual stdout suppression comes from progress_callback: null on line 16. Move or revise the comment on lines 3-4 to more accurately reflect what each configuration does—the env settings enable local model loading and disable browser caching, while the progress callback setting prevents logging output.

Note: console.error() writes to stderr, not stdout, so the existing logging on lines 12 and 18 will not interfere with JSON-RPC communication.

Likely an incorrect or invalid review comment.

---

15-16: LGTM: Disabling progress callback prevents stdout pollution in MCP context.

The { progress_callback: null } option correctly suppresses the @xenova/transformers library's progress output. Setting progress_callback to null disables progress notifications, preventing unwanted output to stdout which would break MCP protocol JSON-RPC communication.

---

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.}