feat(mcp): add AGENTMEMORY_DISABLE_LOCAL_FALLBACK to fail loud on outage

[MarvinFS]

By default the standalone shim silently switches to the local InMemoryKV / ~/.agentmemory/standalone.json store when the configured server is unreachable or a proxy call fails. For deployments that treat a remote agentmemory server as the single source of truth, that masks an outage and lets writes diverge into a local store the operator never sees.

This adds an opt-in AGENTMEMORY_DISABLE_LOCAL_FALLBACK flag (off by default — existing behaviour is unchanged). When set, every silent-fallback path throws instead:

• probe-failure handle resolution (resolveHandle)
• the proxy-call-failure catch in handleToolCall
• the tools/list unexpected-shape and proxy-failure paths

AGENTMEMORY_FORCE_PROXY only skips the startup probe; a mid-session proxy failure still fell back. This closes that gap for callers that opt in.

Tests

Four cases in test/mcp-standalone-proxy.test.ts: proxy-failure throw (asserting no local write), the probe-failure throw, tools/list throw on unexpected remote shape, and a regression guard that the unset flag still falls back.

Summary by CodeRabbit

• New Features

  • Added environment option to disable automatic local fallback when the remote agent memory server is unavailable.

• Behavior Changes / Bug Fixes

  • When local fallback is disabled, failures now surface as errors instead of silently falling back to local storage; tool-list and tool-call fallbacks are refused.
  • Health probe messages now indicate whether local fallback is disabled.

• Tests

  • Added tests covering the new configuration and failure behaviors.

[vercel]

@MarvinFS 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]

PR changed again? Review this PR in Change Stack to compare snapshots and stay oriented.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5a998fac-6398-421c-b912-488ab1bb39d6

📥 Commits

Reviewing files that changed from the base of the PR and between 47701e3 and 8e0aef6.

📒 Files selected for processing (1)

• src/mcp/rest-proxy.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/mcp/rest-proxy.ts

---

📝 Walkthrough

Walkthrough

This PR introduces environment-variable-controlled disabling of local fallback behavior in the MCP proxy layer. When AGENTMEMORY_DISABLE_LOCAL_FALLBACK=1 is set, the system throws errors on proxy unavailability instead of silently degrading to local in-memory storage.

Changes

Disable Local Fallback on Proxy Unavailability

Layer / File(s)	Summary
Configuration and proxy-level fallback enforcement src/mcp/rest-proxy.ts	Exports disableLocalFallback() helper that reads the environment variable and updates resolveHandle() to throw when fallback is disabled, rather than returning a cached local handle.
Tool call proxy error handling with fallback prevention src/mcp/standalone.ts	Imports and uses disableLocalFallback() in handleToolCall() to invalidate the handle on proxy errors, rethrow those errors when fallback is disabled, and refuse local handling when the feature is enabled.
Tool list proxy error handling with fallback prevention src/mcp/standalone.ts	Updates handleToolsList() to validate remote response shape and conditionally throw on proxy errors or unexpected responses when fallback is disabled; adds a guard blocking local tool-list fallback when the configuration is enabled.
Test coverage for disable local fallback feature test/mcp-standalone-proxy.test.ts	Adds four test cases validating proxy failure behavior when AGENTMEMORY_DISABLE_LOCAL_FALLBACK=1 is set, including tool call errors, server probe failures, tool list response validation, and regression checks that local fallback still works when unset.

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly Related Issues

• #695: Directly addresses the feature request to implement strict "no local fallback" mode via disableLocalFallback() and AGENTMEMORY_DISABLE_LOCAL_FALLBACK environment variable control, with proxy and standalone behavior changes to surface outages as errors.

Poem

🐰 When servers sleep and networks fail,
No graceful fall to backup's tale.
With flags set high, we raise our voice—
Errors loud, a conscious choice!
Fallback disabled, errors flow free,
That's the way it ought to be. 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% 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 accurately summarizes the main change: introducing AGENTMEMORY_DISABLE_LOCAL_FALLBACK environment flag to make failures explicit instead of silently falling back to local storage.
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

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/mcp/rest-proxy.ts`:
- Around line 174-178: The probe() path logs “falling back to local InMemoryKV”
even when disableLocalFallback() is true, which is misleading; update the
probe() implementation (the probe function and its failure handling) to check
disableLocalFallback() before emitting any “falling back” message and instead
log a clear error/throw when local fallback is disabled (matching the existing
throw branch that uses disableLocalFallback()); essentially, gate the fallback
log behind !disableLocalFallback() (or replace it with a different log/throw) so
the message is only emitted when an actual local fallback will occur.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0a11120d-fb9f-44ee-81e3-8da77b109c9a

📥 Commits

Reviewing files that changed from the base of the PR and between a323fb0 and 47701e3.

📒 Files selected for processing (3)

• src/mcp/rest-proxy.ts
• src/mcp/standalone.ts
• test/mcp-standalone-proxy.test.ts