Conversation
Adds ADR 0001 documenting the diagnosis and fix for the duplicate
'agent-memory' MCP registration that appeared as '✗ Failed to connect'
alongside the working plugin entry.
Root cause was host-side, not repo-side: this repo's .mcp.json doubles
as the plugin manifest (referenced by .claude-plugin/plugin.json) and
also gets auto-detected as a project-scope MCP when Claude's cwd is
this repo. Project scope can't resolve ${CLAUDE_PLUGIN_ROOT}, so the
project-scope launch failed every session. The host-side fix is to
drop enabledMcpjsonServers / enableAllProjectMcpServers from
.claude/settings.local.json so Claude only loads the plugin entry.
The repo's .mcp.json stays in place — codex review correctly flagged
that deleting it would silently break every fresh plugin install
because the plugin manifest depends on it.
Also adds an AGENTS.md note warning future maintainers not to re-enable
project-scope MCP auto-load in this repo.
Working-branch: fix/agent-memory-mcp-single-source-of-truth
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
agent-memoryMCP registration that appeared as✗ Failed to connectalongside the working plugin entry.AGENTS.mdwarning so future contributors don't re-enable project-scope MCP auto-load in this repo and re-trigger the failure.Root cause (summary; full detail in the ADR)
This repo's
.mcp.jsondoubles as the plugin manifest (referenced by.claude-plugin/plugin.json) and gets auto-detected as a project-scope MCP whenever Claude's cwd is this repo. Project scope doesn't setCLAUDE_PLUGIN_ROOT, so the project-scope launch failed every session while the plugin-scope launch worked fine.The host-side fix (dropping
enabledMcpjsonServersandenableAllProjectMcpServersfrom this project's.claude/settings.local.json) makes Claude only load the plugin entry..mcp.jsonstays in place because the plugin manifest depends on it — codex review correctly flagged that deleting it would silently break every fresh plugin install.Test plan
scripts/run_mcp.shreturns a healthyinitialize+tools/list(server v1.26.0, 12 tools).claude mcp list | grep agent-memoryshows exactly one connected line (plugin:agent-memory:agent-memory ✓ Connected) and no diagnostic warning.docs/adr/0001-claude-mcp-single-source-of-truth.md§Verification on a freshly restarted Claude session.Related
docs/adr/0001-claude-mcp-single-source-of-truth.md