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 an environment option to disable automatic local fallback when the remote agent memory server is unavailable.

• Behavior Changes / Bug Fixes

  • When local fallback is disabled, previously silent fallbacks now return errors instead of using local storage; tool-call and tool-list fallback behavior is refused.
  • Health/probe failure messaging now reflects whether local fallback is enabled.

• Tests

  • Added coverage for the new configuration, including unreachable server behavior, rejecting proxied tool-call failures, and handling unexpected remote tool-list responses (including forced-proxy scenarios).

[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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c92c56d1-4aed-4b8c-be39-9d0ce44ec537

📥 Commits

Reviewing files that changed from the base of the PR and between ebc5bad and d5bca24.

📒 Files selected for processing (3)

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

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

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

---

📝 Walkthrough

Walkthrough

Adds AGENTMEMORY_DISABLE_LOCAL_FALLBACK and a helper to read it. When enabled, MCP proxy and standalone handlers surface proxy errors instead of silently falling back to local InMemoryKV.

Changes

Disable Local Fallback on Proxy Unavailability

Layer / File(s)	Summary
Configuration and proxy-level fallback enforcement src/mcp/rest-proxy.ts	Exports disableLocalFallback(), updates livez probe messaging, and makes resolveHandle() throw instead of creating or caching a local handle when fallback is disabled.
Tool call and tool list fallback prevention src/mcp/standalone.ts	Updates handleToolCall() and handleToolsList() to invalidate handles, rethrow proxy failures, reject unexpected remote responses, and block local fallback when configured.
Fallback behavior validation test/mcp-standalone-proxy.test.ts	Tests disabled-fallback proxy and probe failures, confirms fallback remains available when unset, and verifies tool-list rejection for unexpected remote responses.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant MCPClient
  participant standaloneHandlers
  participant restProxy
  participant RemoteServer
  participant InMemoryKV

  MCPClient->>standaloneHandlers: request tool call or tool list
  standaloneHandlers->>restProxy: resolve or invoke remote operation
  restProxy->>RemoteServer: probe or proxy request
  RemoteServer-->>restProxy: error or unexpected response
  restProxy-->>standaloneHandlers: throw proxy error
  standaloneHandlers-->>MCPClient: reject request
  standaloneHandlers--xInMemoryKV: do not use local fallback

Loading

🚥 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 clearly summarizes the main change: an opt-in flag that disables local fallback so outages fail loudly.
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.

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

[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

[MarvinFS]

Gentle ping on this one too. Still merges cleanly against current main, and it is opt-in / off by default. Setting AGENTMEMORY_DISABLE_LOCAL_FALLBACK=1 makes the client throw on a server outage instead of silently writing to the local standalone store, so a down or misconfigured daemon surfaces as a loud error rather than a quiet split-brain where saves land in a local file nobody is watching. No behavior change unless the flag is set. Glad to tweak anything if it would help.