docs(claude-code-plugin): point to nmem CLI for graph/Crystal queries - #533
Merged
Conversation
The default MCP tool set this plugin exposes is intentionally bounded (see postmortem/2026-07-10-external-mcp-tool-surface-bloat.md in the main repo) and does not include graph-relationship tools like memory_neighbors or list_crystals. A user hitting "why can't I query a Crystal's graph neighbors" had no documented path forward -- the README never mentioned the bound or an alternative. Adds a short "Beyond the default tools" section recommending the nmem CLI (nmem graph expand / nmem graph evolves), which talks to the REST backend directly and isn't subject to the MCP tool-surface bound.
Reframe as a positive capability pointer (nmem CLI can do more, see --help) rather than explaining internal MCP tool-set bounding -- that reasoning belongs in the main repo's postmortem, not user-facing docs.
State the recommendation directly rather than implying it.
Same note as the earlier Claude Code plugin commit, applied to every other plugin covering a client on the EXTERNAL_MCP_SURFACE.md recognized-host list (Codex, Codex prompts, Kimi Code, Cursor, CodeBuddy, Copilot CLI, OpenCode) -- they all share the same bounded default MCP tool set, so the same "no graph queries in the default set" gap and the same nmem CLI escape hatch applies to each. Also reorders the recommendation: MCP tools first for the per-turn loop, nmem CLI for anything beyond that -- not "prefer nmem over MCP" in general, which the first wording could be misread as. nowledge-mem-gemini-cli already had a "Direct nmem Use Is Always Allowed" section; extended it in place (commits d2984d4, a838134 on nowledge-co/nowledge-mem-gemini-cli#5) rather than adding a duplicate section, and bumped this submodule's pointer to pick it up.
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.
Background
The default MCP tool set every recognized-host plugin in this repo exposes (Grok Build/Claude Code, Codex, Kimi Code, Gemini CLI, Cursor, CodeBuddy, Copilot CLI, OpenCode -- the exact list in
nowledge-co/mem'sdocs/implementation/EXTERNAL_MCP_SURFACE.md) is intentionally bounded to a small per-turn set. It does not include graph-relationship tools (memory_neighbors,list_crystals,explore_graph, etc.).Problem
A user asked why a Crystal's graph neighbors can't be queried via MCP. The backend/REST layer fully supports it, but none of these plugins' READMEs mentioned the bounded tool set or pointed to any alternative -- so there was no documented path forward for graph/relationship queries in any of them.
Fix
Adds a short "Beyond the default tools" note to every plugin covering a recognized host, recommending the
nmemCLI for anything outside the per-turn MCP loop -- ordered explicitly as MCP tools first for the day-to-day loop,nmemCLI for gaps beyond that (not "prefer nmem over MCP" in general).nmemis already a prerequisite for every one of these plugins, so no new install step.nowledge-mem-gemini-clialready had a "DirectnmemUse Is Always Allowed" section; extended it in place instead of adding a duplicate section (nowledge-co/nowledge-mem-gemini-cli#5), and this PR bumps that nested submodule's pointer to pick it up.Tests
No need to test -- docs-only change (README additions), no code path affected.