Codex flagged /basic-memory:remember passing a UUID primaryProject as `project`
(review 4397206729) — the same routing bug already fixed in the hooks and the
share skill. Rather than fix only the flagged spot, audited every project-ref
site and made them all consistent:
- remember: route primaryProject as project_id when it's a UUID (was the flag)
- status: same for the primaryProject-scoped search_notes queries
- setup: same for the schema-seed write to primaryProject
share/SKILL.md and both hooks (session-start, pre-compact) already handle it.
That's now every place the plugin routes to a project ref — a project ref may be
a workspace-qualified name (-> project) or an external_id UUID (-> project_id),
and all six sites detect and route accordingly. Plugin validates.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
Resolves the in-scope findings from the github-actions review (its prepared commit
1283a46 couldn't push — 403) and the Codex P2 (review 4397168884):
- pre-compact.sh: route a UUID primaryProject via --project-id, not --project.
This mirrors session-start.sh; without it a UUID-configured project gets correct
session briefs but SILENT checkpoint failures at every compaction. The substantive
correctness fix. Verified end-to-end (checkpoint now lands in a UUID-keyed project).
- skills/share/SKILL.md: same UUID routing for /basic-memory:share team targets —
pass external_id UUIDs as project_id, qualified names as project. (Codex P2.)
- skills/status/SKILL.md: read outputStyle from the ROOT settings object, not the
basicMemory block — otherwise /basic-memory:status reports capture reflexes as off
for a correctly-configured user.
- docs/getting-started.md: move outputStyle out of the basicMemory block to root in
the team example (matches settings.example.json; it's a top-level Claude Code key).
- session-start.sh: split the >100-char project-routing line.
Out of scope here: the hermes/__init__.py getattr-rationale comments the bot
prepared live in the #859 consolidation code (not in this PR's diff) — flagged for
that PR. Plugin validates; hooks smoke-tested.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
The MCP server is a hard prerequisite for the plugin (its hooks and skills call
it), but the two were in separate README sections with no link between them.
- The "Claude Code plugin" install section now points to "Connect your AI client"
and states the MCP server must be connected first.
- The "Connect your AI client → Claude Code" section now points to the plugin for
the full memory bridge.
- /basic-memory:setup's prerequisite check is now concrete: verify the MCP server
via list_memory_projects, and if absent, walk the user through installing and
`claude mcp add basic-memory -- uvx basic-memory mcp` before starting the interview.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
1. SessionStart worker pool was sized 8 but submits up to 9 searches (3 primary
+ MAX_SHARED=6 shared) — the 9th queued behind a possibly-10s call and could
push the hook past Claude Code's 20s SessionStart timeout before the brief
printed. Size the pool to 3 + MAX_SHARED so nothing queues. (Introduced in
Phase 4 when the third primary query was added.)
2. captureChattyness was dead config — written by setup but read by no hook, and
its "heavy" level advertised "checkpoint without compaction," which no hook
implements. The real proactivity knob is `outputStyle`. Removed
captureChattyness entirely and folded the "how active should I be?" question
into the output-style step (the single, actually-wired toggle); the always-on
hooks run regardless. Updated setup skill, settings.example.json, and DESIGN.
Both flagged by Codex (review 4395911984); same class as the recallTimeframe
dead-config fix from the earlier self-review. Plugin validates; hook smoke-tested.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
Addresses the consolidation direction from issue #866: the Claude Code plugin
should consume the canonical skills/ set, not reinvent a parallel one. Rather
than vendoring copies into the plugin, /basic-memory:setup now offers to install
the shared memory-* skills via `npx skills add basicmachines-co/basic-memory
--path skills` (the existing SPEC-58 distribution path, same source OpenClaw
bundles). The plugin stays "hooks + Claude-Code-specific skills" and pulls the
shared toolkit on demand — skills/ remains the single source of truth, no
duplication in the repo.
Updated the setup interview + apply steps, README, getting-started, and CHANGELOG.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
Resolves the 8 self-review findings on PR #865:
session-start.sh:
- Wire recallTimeframe into a new "Recent sessions" query (--after_date) — it was
parsed but unused after the Phase 4 rewrite. The brief now surfaces recent
session checkpoints (the resume cursor), which is the one query the recency
window legitimately applies to. (#1)
- Guard secondaryProjects/teamProjects JSON types — a string value was iterated
character-by-character into bogus per-char queries. (#3)
- A configured-but-unreachable/misnamed primaryProject now emits a one-line
"couldn't read" signal instead of a silent blank brief. (#7)
pre-compact.sh:
- Filter transcript turns by the `isMeta` and `toolUseResult` flags instead of a
`text.startswith("<")` heuristic. This stops dropping legitimate user messages
that start with "<" (#4) and stops capturing tool-result/meta frames as human
turns (#8) — verified against a real transcript (25 human turns cleanly
separated from 8 meta + 288 tool-result frames).
- Title now uses second precision so rapid same-minute compactions don't collide
and silently drop/overwrite a checkpoint; removed the unused stamp/slug. (#2)
- Empty-checkpoint guard now requires at least one real user turn, not just any
turn, so an assistant-only transcript can't produce a dangling-title note. (#5)
validate_skills.py:
- parse_frontmatter now skips indented lines, capturing only top-level keys, so a
schema note's nested schema:/settings: children can't overwrite a top-level
type/entity via last-write-wins. Documented its single-line-only limitation. (#6)
All verified end-to-end; `just package-check-claude-code` and
`package-check-skills` pass; ruff clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
Adds user- and contributor-facing documentation under plugins/claude-code/docs/:
- why-combine-memory.md — the value proposition: two-memories/two-jobs, the
1+1=3 framing, the three personas (thinker / builder / operator) with concrete
use cases, and the official "use both" stance. The "why would I want this" doc.
- getting-started.md — a ~5-minute guided walkthrough: prerequisites, install,
/basic-memory:setup, a capture→checkpoint→brief loop to see it work, the team
workspace path, tuning knobs, and troubleshooting.
- architecture.md — how it works flow by flow, with mermaid diagrams: the bridge
(working memory <-> durable graph), the four surfaces, SessionStart and
PreCompact sequence flows, capture reflexes, team read/share, component map.
Linked all three from the README's new Documentation section. Marked Phase 5
docs done in DESIGN. Migration guide intentionally skipped — v0.4 is a clean
break (uninstall old, install new), noted in the CHANGELOG. Dogfood remains the
open human step.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
Implements DESIGN.md Phase 4, grounded in a real two-workspace BM Cloud account.
Recall reads across the team:
- hooks/session-start.sh rewritten to read the primary project (active tasks +
open decisions) AND each configured shared/team project (open decisions) in
parallel via ThreadPoolExecutor. Routes by workspace-qualified name or
external_id UUID (project names collide across workspaces, so bare names won't
route); per-call timeout, capped at 6 shared projects, graceful on any failure.
Adds a "From shared projects (read-only)" section + the share-vs-capture note.
Verified against the real my-team-2 workspace (OAuth routing) and local fixtures.
Deliberate team writes:
- skills/share/SKILL.md → /basic-memory:share <note>: copies a note from the
primary project into a configured teamProjects target's promoteFolder, with
shared_from attribution and a confirmation step. Preserves the note's type so
shared decisions stay findable in the team's structured recall. Pulled forward
from future-work since team usage needs a safe write path.
Safe by default: capture (PreCompact checkpoints, /remember) NEVER writes to a
shared project. The proposed teamProjects.autoWrite flag is deliberately not
shipped — documented as future rather than ship an unenforced flag.
Config: secondaryProjects (read sources) + teamProjects (share targets with
promoteFolder), both requiring qualified names/UUIDs. setup interview step 3 now
configures them via list_workspaces; status reports team read-sources + share
targets; settings.example.json documents the shape. REQUIRED_SKILLS adds share.
Discovery verified: Skills (4): remember, setup, share, status. Passes
`just package-check-claude-code` incl. `claude plugin validate . --strict`.
Updated README (Teams section), CHANGELOG, and DESIGN §6 + Phase 4 status.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
Adds the bootstrap interview from DESIGN.md Phase 3 as a prose skill, plus the
first-run nudge that points users to it.
- skills/setup/SKILL.md → /basic-memory:setup: an adaptive ~2-min interview that
maps the Claude Code project to a Basic Memory project (pick existing or create),
seeds the session/decision/task schemas into it, optionally learns the project's
placement conventions (list_directory + sampling, stored in placementConventions),
writes the basicMemory settings block, and enables the capture output style.
- hooks/session-start.sh: nudges toward /basic-memory:setup on first run (when no
basicMemory config block exists). The nudge now survives a failed/empty task
query, so a brand-new user with no project yet still sees it; it stops once setup
writes the config (config presence is the sentinel — no separate file).
- validate_claude_plugin.py: REQUIRED_SKILLS now includes setup.
Corrects the Phase 1 schema-seeding finding: writing a schema file's content via
write_note (CLI or MCP) indexes it as type: schema AND resolves via schema_validate
— the earlier "must use note_type/metadata" conclusion was confounded by the enum
YAML bug (since fixed). Verified end-to-end: all three schemas seed, index, and
resolve (entity=Session/Decision/Task); nudge verified across all config states;
discovery shows Skills (3): setup, remember, status.
Updated README, CHANGELOG, and DESIGN Phase 3 status. Passes
`just package-check-claude-code` incl. `claude plugin validate . --strict`.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
Adds the two deliberate-gesture skills from DESIGN.md Phase 2, both as prose
skills (skills are prompts) — robust to arbitrary user text and any MCP server
tool-name prefix, no bundled-script path placeholders.
- skills/remember/SKILL.md → /basic-memory:remember <text>: quick capture to the
rememberFolder (default bm-remember) with a first-line title and manual-capture
tag, via write_note. Model-invocable so "remember that…" triggers it.
- skills/status/SKILL.md → /basic-memory:status: user-only diagnostic
(disable-model-invocation) reporting active project, capture/remember folders,
output-style state, recent session checkpoints, and active-task count.
validate_claude_plugin.py now requires the shipped skill set (REQUIRED_SKILLS)
and validates each skill's name/description frontmatter. Passes
`just package-check-claude-code` incl. `claude plugin validate . --strict`.
Discovery verified end-to-end: installed from a local marketplace and confirmed
via `claude plugin details` — Skills (2): remember, status; Hooks (2):
SessionStart, PreCompact; Agents (0) — namespaced as /basic-memory:<name>.
Updated README (Commands table), CHANGELOG, and DESIGN Phase 2 status.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
Reframes the Claude Code plugin as the bridge between Claude's working
memory and Basic Memory's durable graph, per plugins/claude-code/DESIGN.md.
This is the minimal-first vertical slice with a clean break from v0.3.x.
Added:
- hooks/session-start.sh — SessionStart brief: one structured `type: task`
query against the configured (or default) project + always-on recall
prompt. Plain stdout, silent if BM is absent.
- hooks/pre-compact.sh — PreCompact checkpoint: writes a `type: session`
note before compaction (extractive). Only writes when primaryProject is
set, so it never touches an un-opted-in graph.
- output-styles/basic-memory.md — capture reflexes (search-first, typed
decision notes, cite permalinks); keep-coding-instructions: true.
- schemas/{session,decision,task}.md — picoschema seeds (validation: warn)
so plugin-written notes are findable via metadata_filters. task mirrors
the memory-tasks skill.
- settings.example.json — copyable config with sensible defaults.
Removed (clean break):
- the six bundled skills, the basic-memory-manager agent, the
PreToolUse/PostToolUse write_note hooks, the basic-memory config-note
convention, and PLUGIN.md. Equivalent workflows live in top-level skills/.
Other:
- Rewrote scripts/validate_claude_plugin.py for the new layout (hooks +
output-style + schemas; agent dropped; skills optional). Passes
`just package-check-claude-code` incl. `claude plugin validate --strict`.
- Rewrote README around the bridge story; updated CHANGELOG, marketplace
descriptions, and the AGENTS.md package-check note.
- Hooks tested end-to-end against throwaway projects (brief surfaces tasks;
checkpoint writes a queryable session note; both degrade silently).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
WIP design doc for modernizing the Claude Code plugin around the
"bridge between Claude auto-memory and Basic Memory" positioning.
- Reframes the plugin as connective tissue between Claude's working
memory and BM's durable graph (per docs/vs-built-in-memory).
- Defines the four core surfaces: SessionStart brief, PreCompact
checkpoint, output-style reflexes, deliberate skills.
- Leans on BM schemas + structured metadata search for deterministic
recall (ships session/decision/task picoschemas).
- Maps Claude Code projects to BM projects; team-workspace safety
(read-across, write-by-gesture); bootstrap interview.
- Records verified findings for 8 open questions (CC v2.1.153 /
basic-memory 0.21.5) from an investigate→adversarial-verify pass:
PreCompact 600s budget enables LLM summaries; metadata_filters
confirmed; path-scoped rules cut (don't load yet); commands are
plugin-namespaced; bootstrap via SessionStart sentinel.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
phernandez