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>
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>
Paul Hernandez