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

Why

The Claude Code plugin's SessionStart and PreCompact hooks previously read the basicMemory block only from <cwd>/.claude/settings.json. Users with one primary knowledge graph therefore had to repeat the same configuration in every repository, and PreCompact silently skipped checkpoints until each repository was configured.

What Changed

Use user-level ~/.claude/settings.json as the base basicMemory configuration.
Apply the nearest ancestor project's .claude/settings.json, then .claude/settings.local.json, as per-key overrides.
Keep settings.local.json project-scoped; a user-level ~/.claude/settings.local.json is deliberately ignored.
Align the plugin README and the bm-remember, bm-share, and bm-status skills with the same precedence.
Add executable regression tests for both lifecycle hooks.

Implementation Details

The hooks walk from the payload working directory to the nearest ancestor containing a Claude settings file. This keeps a repository-root mapping effective when Claude starts in a subdirectory, while still allowing a single user-level default. If the walk reaches the home directory, the user settings are read only once.

The existing advisory-hook contract is unchanged: malformed or unreadable settings do not block SessionStart or PreCompact.

Testing

Contributor verification:

bash -n on both hooks.
Manual SessionStart verification with global-only and project-override configurations.
Manual PreCompact verification using the user-level project.

Maintainer verification on current main:

uv run pytest -q tests/test_claude_plugin_hooks.py — 3 passed.
bash -n plugins/claude-code/hooks/session-start.sh plugins/claude-code/hooks/pre-compact.sh — passed.
uv run ty check tests/test_claude_plugin_hooks.py — passed.
just fast-check — passed; only the existing Python 3.14 asyncio deprecation diagnostics were reported.
just package-check — passed, including strict Claude plugin validation and all consolidated package tests.

Risks / Follow-ups

Settings resolution controls project routing, so the regression suite executes the real hook scripts with isolated HOME/project trees and a fake Basic Memory CLI. It covers global fallback, ignoring user-level settings.local.json, nearest-ancestor discovery, per-key project/local overrides, and the final PreCompact write target. No known follow-up remains.

🤖 Generated with Claude Code

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.

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

…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>

Signed-off-by: phernandez <paul@basicmachines.co>

phernandez · 2026-07-15T02:29:55Z

@codex review

phernandez · 2026-07-15T02:32:27Z

recheck

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ed1de8d81d

ℹ️ 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".

phernandez · 2026-07-15T02:41:04Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ed1de8d81d

ℹ️ 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".

phernandez · 2026-07-15T02:46:45Z

@codex

chatgpt-codex-connector · 2026-07-15T02:51:03Z

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: ed1de8d81d

ℹ️ 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 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 label Jun 10, 2026

phernandez added dco needed The contributor needs to submit a DCO and removed needs-review 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 force-pushed the global-settings-fallback branch from ae84591 to 551e124 Compare July 10, 2026 18:12

phernandez removed the dco needed The contributor needs to submit a DCO label Jul 15, 2026

samuellawerentz and others added 5 commits July 14, 2026 21:26

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

d28d731

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

test(plugins): cover Claude hook settings precedence

ed1de8d

Signed-off-by: phernandez <paul@basicmachines.co>

phernandez force-pushed the global-settings-fallback branch from 551e124 to ed1de8d Compare July 15, 2026 02:29

chatgpt-codex-connector Bot reviewed Jul 15, 2026

View reviewed changes

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

chatgpt-codex-connector Bot reviewed Jul 15, 2026

View reviewed changes

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

phernandez merged commit 5398cf3 into basicmachines-co:main Jul 15, 2026
11 checks passed

phernandez mentioned this pull request Jul 15, 2026

fix(plugins): make Claude hook tests portable on Windows #1055

Merged

Uh oh!

Conversation

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

Uh oh!

Why

What Changed

Implementation Details

Testing

Risks / Follow-ups

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!

phernandez commented Jul 15, 2026

Uh oh!

phernandez commented Jul 15, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

phernandez commented Jul 15, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

phernandez commented Jul 15, 2026

Uh oh!

chatgpt-codex-connector Bot commented Jul 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

samuellawerentz commented Jun 9, 2026 •

edited by phernandez

Loading

CLAassistant commented Jun 9, 2026 •

edited

Loading