feat(plugins): fall back to user-level ~/.claude settings for Claude Code hook config by samuellawerentz · Pull Request #924 · basicmachines-co/basic-memory

samuellawerentz · 2026-06-09T19:31:12Z

Problem

The Claude Code plugin's SessionStart and PreCompact hooks read the basicMemory block only from <cwd>/.claude/settings.json. Every project therefore needs its own config block (or a bm-setup run) before the brief resolves a pinned project — and the PreCompact checkpoint is a silent no-op everywhere until then. Users with a single primary knowledge graph end up repeating the same block in every repo.

Change

load_settings in both hooks now merges the user-level ~/.claude/settings.json and settings.local.json as the base, with the project's .claude files overriding per key — the same layering Claude Code itself uses for settings:

user settings.json → user settings.local.json → project settings.json → project settings.local.json

One user-level basicMemory block covers every project; a project that pins its own primaryProject still wins. When cwd is the home directory the user level is read once, not twice.

Also documents the user-level option in the plugin README.

Testing

bash -n on both hooks.
Manually invoked session-start.sh with a payload cwd of a repo with no .claude/settings.json: brief resolves the project from the user-level block (previously: "default project" + setup nudge).
Same with a project-level block present: project value wins.
pre-compact.sh resolves primaryProject from the user level the same way (previously exited silently).

🤖 Generated with Claude Code

Reviewed SHA: 868d2094c77aae23d1de92c72be3708ea8c3b293
Verdict: needs_human
Status: failure - BM Bossbot review did not finish

Summary:
BM Bossbot intentionally did not run Codex because this PR was not opened by an owner, member, or collaborator.

Blocking findings:

BM Bossbot does not run for outside contributors: This PR author association is NONE. BM Bossbot only runs for OWNER, MEMBER, and COLLABORATOR pull requests, so this PR requires a maintainer path outside the automatic merge gate.

Non-blocking findings:

None

CLAassistant · 2026-06-09T19:31:19Z

All committers have signed the CLA.

phernandez · 2026-06-09T21:48:09Z

thanks @samuellawerentz. I had not gotten around to adding the user level settings. Thats much needed.

Do you mind signing off on your commits? and signing the cla? We need that before we can merge this.

In your local branch, run: git rebase HEAD~1 --signoff

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dc6fc776f6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 868d2094c7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a853652c4b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

samuellawerentz · 2026-06-10T03:32:45Z

Sure, I'll get these fixed and signed as well. This is a good plugin and a good tool that I use, which has solved my memory problems across the different harnesses. Thank you.

phernandez · 2026-06-10T04:26:01Z

Labeling needs-review: there are unresolved review threads on the hook fallback behavior that need a decision before this merges (merge precedence between project and user-level settings, and the skill doc updates). No action needed from the author yet — maintainers will follow up on the threads.

phernandez · 2026-06-10T19:33:02Z

@samuellawerentz Thanks for the contribution — the user-level settings fallback is a direction we're interested in, and your follow-up commits addressing the review were appreciated.

One mechanical blocker before we can take this further: the DCO check requires every commit to carry a Signed-off-by trailer, and the first commit on the branch (f94ae316) doesn't have one. The easiest fix signs everything and tidies the merge commits away in one go — from your local clone of the branch:

git fetch origin main
git rebase origin/main --signoff
git push --force-with-lease origin global-settings-fallback

(If your fork's remote is named differently, swap origin accordingly in the push. --signoff adds the trailer to each replayed commit using your configured git identity, which certifies the Developer Certificate of Origin.)

Once DCO is green we'll pick the review threads back up. Thanks again!

Copilot

Pull request overview

This PR updates the Claude Code plugin hooks to support user-level ~/.claude/settings.json as a baseline basicMemory configuration, with project .claude/settings.json / .claude/settings.local.json overriding it, so users don’t need to repeat the same config block per repository.

Changes:

Implement layered settings resolution in session-start.sh and pre-compact.sh (user-level base → nearest project settings overrides).
Update plugin README and skill instructions to document the new precedence and behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
plugins/claude-code/hooks/session-start.sh	Load `basicMemory` config from user-level settings, then override with nearest project `.claude` settings.
plugins/claude-code/hooks/pre-compact.sh	Same layered settings resolution as SessionStart, enabling PreCompact to work with user-level config.
plugins/claude-code/README.md	Document user-level `basicMemory` option and precedence rules.
plugins/claude-code/skills/bm-status/SKILL.md	Update skill instructions to reflect the hooks’ new config precedence.
plugins/claude-code/skills/bm-share/SKILL.md	Update config-resolution instructions to match hook precedence.
plugins/claude-code/skills/bm-remember/SKILL.md	Update config-resolution instructions to match hook precedence.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…nfig The SessionStart and PreCompact hooks read basicMemory config only from <cwd>/.claude/settings.json, so every project needs its own block (or a bm-setup run) before briefs resolve a pinned project and checkpoints write at all. Users with one primary knowledge graph end up repeating the same config in every repo. Make load_settings in both hooks merge user-level ~/.claude/settings.json and settings.local.json as the base, with the project's .claude files overriding per key — same layering Claude Code itself uses for settings. A single user-level basicMemory block now covers every project, while any project can still pin its own mapping, which wins. Documented in the plugin README. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Samuel Lawrentz <samuel.lawerence@plivo.com>

- User-level pass reads only ~/.claude/settings.json (no user-level settings.local.json — it isn't a real Claude Code source), so a stale global local file can't silently reroute the brief/checkpoint. - Resolve project settings from the nearest .claude dir at or above cwd, so a repo-root mapping wins when Claude starts in a subdirectory. - bm-remember / bm-share / bm-status skills now read the same precedence (user-level base, project overrides), matching the README claim that one user-level block covers every command. - README: drop user-level settings.local.json from the precedence note and document the ancestor-walk behaviour. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Samuel Lawrentz <samuel.lawerence@plivo.com>

- Drop redundant except FileNotFoundError in _read_block (subclass of Exception, already caught). - Drop redundant os.path.abspath in load_settings; _project_dir already returns an absolute path. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Samuel Lawrentz <samuel.lawerence@plivo.com>

…settings file Signed-off-by: Samuel Lawrentz <samuel.lawerence@plivo.com>

samuellawerentz · 2026-07-10T18:13:46Z

Thanks @phernandez! Done:

CLA signed
Rebased onto latest main with --signoff — all commits now carry DCO sign-off
Codex review points addressed (user-level pass reads only ~/.claude/settings.json, ancestor walk for the project .claude, skills aligned to the same precedence) and threads resolved
README wording fixed per the Copilot note

phernandez · 2026-07-10T20:42:31Z

Thanks @samuellawerentz! appreciate it. I'll take a look at this real soon

chatgpt-codex-connector Bot reviewed Jun 9, 2026

View reviewed changes

Comment thread plugins/claude-code/README.md Outdated

chatgpt-codex-connector Bot reviewed Jun 10, 2026

View reviewed changes

Comment thread plugins/claude-code/hooks/session-start.sh Outdated

chatgpt-codex-connector Bot reviewed Jun 10, 2026

View reviewed changes

Comment thread plugins/claude-code/hooks/session-start.sh Outdated

phernandez added the needs-review Maintainer decision needed before merge label Jun 10, 2026

phernandez added dco needed The contributor needs to submit a DCO and removed needs-review Maintainer decision needed before merge labels Jun 10, 2026

phernandez requested a review from Copilot June 13, 2026 21:57

Copilot started reviewing on behalf of phernandez June 13, 2026 21:57 View session

Copilot AI reviewed Jun 13, 2026

View reviewed changes

Comment thread plugins/claude-code/README.md Outdated

samuellawerentz and others added 4 commits July 10, 2026 23:41

docs(plugins): clarify hooks resolve nearest ancestor with a .claude …

551e124

…settings file Signed-off-by: Samuel Lawrentz <samuel.lawerence@plivo.com>

samuellawerentz force-pushed the global-settings-fallback branch from ae84591 to 551e124 Compare July 10, 2026 18:12

Uh oh!

Conversation

samuellawerentz commented Jun 9, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Change

Testing

Uh oh!

CLAassistant commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

phernandez commented Jun 9, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

samuellawerentz commented Jun 10, 2026

Uh oh!

phernandez commented Jun 10, 2026

Uh oh!

phernandez commented Jun 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

samuellawerentz commented Jul 10, 2026

Uh oh!

phernandez commented Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

samuellawerentz commented Jun 9, 2026 •

edited by github-actions Bot

Loading

CLAassistant commented Jun 9, 2026 •

edited

Loading