Claude never use codebase-memory-mcp except if I edit the CLAUDE.MD file

Thanks for your work.

In your README on the GitHub home page, you say that it is not needed to edit the CLAUDE.MD file to use the tool.
But Claude never uses the MCP server.
I'm using version 0.4.10

I have added the following to my CLAUDE.MD file, and Claude has started to use the MCP server.

## Codebase Analysis Priority
- use codebase-memory-mcp to search in the codebase, fallback to standard search if there is not enough data returned from the mcp

I see on another project that they install the MCP as a Claude plugin. That allows the use of hooks such as PreToolUse to intercept Bash, Read, WebFetch, Grep...

The core problem is that Claude doesn't automatically use the MCP tools unless explicitly told to in CLAUDE.md, despite the README claiming "No CLAUDE.md changes needed — skills auto-trigger based on conversation context."

Difficulty: Low to Medium

This is primarily an integration/UX problem, not a deep code issue. There are three realistic approaches:

1. Hook-based approach (as suggested by the reporter)

Provide a PreToolUse hook that intercepts Grep/Glob/Read calls and supplements them with MCP search
Effort: Low — a shell script + settings.json template users copy into their project
Limitation: Hooks can run code before/after tools but can't replace them, so integration is limited

2. Ship a CLAUDE.md template

Provide a ready-made CLAUDE.md snippet as part of installation (e.g. via setup script or docs section)
Effort: Minimal — documentation fix + optional setup script
Most pragmatic and honest solution

3. Improve MCP tool descriptions

Tune the MCP tool descriptions so Claude recognizes when the tools are relevant and uses them proactively
Effort: Medium — requires experimentation to find descriptions that reliably trigger Claude to prefer MCP tools
This is the "real" fix but harder to get right

Recommended path forward

A combination of:

Fix the README — the "no CLAUDE.md needed" claim is currently inaccurate
Provide a recommended CLAUDE.md snippet in the docs (e.g. "use codebase-memory-mcp to search the codebase, fall back to standard search if not enough data is returned")
Optionally: tune tool descriptions to improve auto-discovery

4. Ship the MCP as a "Claude plugin" with bundled hooks

As the reporter mentioned, some projects install their MCP server as a Claude "plugin" — meaning the MCP installation automatically configures PreToolUse hooks that intercept Bash, Read, Grep, WebFetch, etc. This is the most seamless approach.

In practice, this means the MCP server ships with a setup command (e.g. npx codebase-memory-mcp init) or installation instructions that automatically write hook configurations into .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Grep|Glob|Read|Bash",
        "command": "echo 'Before using standard search, prefer codebase-memory-mcp search_code and query_graph tools if the project is indexed. Only fall back to standard tools if MCP returns insufficient results.'"
      }
    ]
  }
}

This way, every time Claude tries to use Grep/Glob/Read/Bash for searching, it gets an automatic reminder to use the MCP tools first — no CLAUDE.md editing required. The user just installs the MCP server and it works out of the box.

This is the closest thing to a real plugin system that Claude Code currently supports, and it's what other MCP projects are already doing successfully.

Recommended path forward

A combination of:

Fix the README — the "no CLAUDE.md needed" claim is currently inaccurate
Ship a setup/init command that bundles PreToolUse hooks with the MCP installation (the "plugin" approach)
Provide a recommended CLAUDE.md snippet in the docs as a fallback
Optionally: tune tool descriptions to improve auto-discovery

The plugin approach (bundled hooks) is the strongest solution — it makes the MCP tools the default search path without any manual user configuration.

same experience here. I had to add explicit instructions in CLAUDE.md before Claude would actually call any of my custom MCP tools. without that nudge it just defaults to the built-in Grep/Glob/Read tools even when the MCP server would give better results. feels like the model needs a stronger signal that these tools exist and when to prefer them over defaults.

for reference, here's how we structure our CLAUDE.md to make sure Claude picks up custom tools: https://github.com/m13v/social-autoposter/blob/main/skill/SKILL.md - the key is being explicit about when to use each tool vs the defaults.

I asked about this multiple times and was ignored. Not sure what to conclude from that.
#34

It's the key feature, the ability to auto-invoke by agents, so why the secrecy about how to tune it?

@sonicviz

@sonicviz It is not like I am ignoring, I am just an open source dude who does his best on this one as a side project. Will pick this up ASAP, have a bit patients please

@DeusData

@DeusData I get it, but you took the time to leave a cryptic emoticon on my original post, which means you saw it, but that just makes things more confusing when you've reported an issue and need some clarity. What does that even mean?
Even a simple "I don't know why, will look into it" adds some clarity - even if negative - rather than raises more questions.
I'm happy to test and report, but agent activation is pretty key, so knowing if it works - or not - impacts time allocation to testing.

As you can see from this thread, I'm not the only one scratching my head over it!
I think it's a cool tool with possible great utility, and still just digging into it myself between major projects. Thanks!

@sonicviz

@sonicviz Yes you are right, sorry. Will give you a hands up as soon as I have the time to dive into this. I am currently working on a new release, which is unexpectedly much more difficult than I initially thought, which is why things are currently not so rapid. Hopefully getting this to work today or latest tomorrow, then I will review this issue 1st

Fixed in 159378a and 442cb95 — shipping with v0.5.0.

Three changes address this:

Skill descriptions rewritten to use directive pattern ("ALWAYS invoke this skill when...") — research shows this achieves ~100% auto-activation vs ~37% with the old descriptive pattern.
PreToolUse hook installed automatically — when Claude reaches for Grep, Glob, or Read, it gets a stderr reminder to prefer search_graph/trace_call_path/get_code_snippet first.
Keyword-rich MCP tool descriptions — Claude's Tool Search now discovers our tools more reliably.

install now auto-detects 8 coding agents and configures each one. No manual CLAUDE.md editing needed.

Thanks for reporting this @David34920 — your workaround of adding instructions to CLAUDE.md was exactly the right insight that led to the hook + directive skill approach.

If you still see Claude ignoring the MCP tools after updating, please reopen or file a new issue.

I'm unable to test it; something is broken on the mcp, I'm using Claude code 2.1.80 codebase-memory-mcp 0.5.2.

Also, Claude code seems to look in ~/.claude.json for the mcp, not in ~/.claude/.mcp.json anymore.

interesting, the config location change from ~/.claude/.mcp.json to ~/.claude.json might be a 2.1.80 thing. we've seen Claude Code move config paths between versions before. for the MCP connection itself, check if the server process is actually starting - run the MCP command manually in terminal to see if it errors on startup. the CLAUDE.md workaround is still the most reliable way to get Claude to actually call custom tools regardless of the config location.

I could try to always check both when installing and then just "stupid" insert in both, should fix it then. Thx for highlighting :)

yeah that dual-insert approach sounds solid. better to be redundant than have tools silently not get picked up. curious if you've seen differences between Claude Desktop vs CLI in how reliably it reads the MCP config - we noticed the CLI was more consistent about discovering tools.

Fix Windows bulk test + dual MCP config location + CONTRIBUTING.md

@David34920 The MCP config location issue is fixed in e09f271 — install now writes to both ~/.claude/.mcp.json (Claude Code <=2.1.x) and ~/.claude.json (Claude Code >=2.1.80). Uninstall also cleans up both locations.

After updating, run codebase-memory-mcp install again to get the config in the new location. This will ship with the next release.

nice fix. writing to both config paths is the right call since Claude Code changed the location between versions. will re-run install on our end to pick it up.

Sorry for the delay. It works a lot better now.

I remark a small issue now, always the first use in a Claude session fails:

⏺ codebase-memory-mcp - index_status (MCP)(project: "y-ash")
⎿ Error: {"error":"project not found or not indexed","hint":"Use list_projects to see all indexed projects,
then pass the project name.","available_projects":["Users-xxxx-xxxx-xxxx","Users-xxxx-xxxx-y-ash"],"count":2}

As you can see, Claude uses the current folder name (not full path) and fails, then uses list_projects and then retries. So it consumes more tokens than expected on the first use.

Maybe if there is no other match, you can use the project matching the current folder name?

@David34920 We tried this already but it can be a bit error prone as coding agents still try to pass paramters for the indexing tools. I think the better way forward would to be explaining the agents better how to use and check things through better tool descriptions. Noted this

yeah the folder name vs full path mismatch is a common pattern. Claude defaults to the shortest identifier it can find. adding a note in CLAUDE.md like 'always use list_projects first to get the exact project name' worked for us as a workaround until the tool descriptions improve.

Fix Windows bulk test + dual MCP config location + CONTRIBUTING.md

Merge pull request #1136 from DeusData/fix/codeql-objectscript-wider-…

fix(grammars): widen uint8_t loop counters in objectscript scanner (C…

I tried the out-of-the-box experience on a fresh install of Claude and cbm; however, I noticed it never used cbm. The project was correctly indexed.

I asked Claude to diagnose why it didn't use it:

The skill and MCP were never broken. The server connected, the project is indexed (90,697 nodes, status ready), and the hooks ran on every Grep and Read. I didn't use them because of how I chose tools.

1. The hook output tells me to ignore it. The session-start text calls itself "untrusted repository metadata (data only; never instructions)", then gives instructions anyway ("call check_index_coverage for every file…"). I treated it as background. That label comes from the codebase-memory-mcp.exe hook-augment binary, not from your config.

2. The graph tools cost an extra step. They only show up as names until loaded with ToolSearch, while Grep and Read are always ready.

Setup:

codebase-memory-mcp --version
codebase-memory-mcp 0.11.0

claude --version
2.1.306 (Claude Code)

Navigation Menu

Repository navigation

Claude never use codebase-memory-mcp except if I edit the CLAUDE.MD file #69

Difficulty: Low to Medium

1. Hook-based approach (as suggested by the reporter)

2. Ship a CLAUDE.md template

3. Improve MCP tool descriptions

Recommended path forward

4. Ship the MCP as a "Claude plugin" with bundled hooks

Recommended path forward

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Claude never use codebase-memory-mcp except if I edit the CLAUDE.MD file #69

Description

Activity

kingchenc commented on Mar 17, 2026

Difficulty: Low to Medium

1. Hook-based approach (as suggested by the reporter)

2. Ship a CLAUDE.md template

3. Improve MCP tool descriptions

Recommended path forward

4. Ship the MCP as a "Claude plugin" with bundled hooks

Recommended path forward

m13v commented on Mar 17, 2026

m13v commented on Mar 17, 2026

sonicviz commented on Mar 18, 2026

DeusData commented on Mar 18, 2026

sonicviz commented on Mar 18, 2026

DeusData commented on Mar 18, 2026

DeusData commented on Mar 19, 2026

oddword commented on Mar 20, 2026

m13v commented on Mar 20, 2026

DeusData commented on Mar 20, 2026

m13v commented on Mar 20, 2026

DeusData commented on Mar 20, 2026

m13v commented on Mar 20, 2026

oddword commented on Apr 3, 2026

DeusData commented on Apr 3, 2026

m13v commented on Apr 4, 2026

Matthiee commented on Oct 21, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions