Skip to content
This repository was archived by the owner on May 31, 2026. It is now read-only.

feat: bm_projects and bm_workspaces as agent tools#5

Merged
groksrc merged 3 commits into
mainfrom
feat/bm-projects-workspaces-tools
May 12, 2026
Merged

feat: bm_projects and bm_workspaces as agent tools#5
groksrc merged 3 commits into
mainfrom
feat/bm-projects-workspaces-tools

Conversation

@groksrc

@groksrc groksrc commented May 12, 2026

Copy link
Copy Markdown
Member

Summary

Adds two new agent-facing tools that wrap BM's `list_memory_projects` and `list_workspaces`. The discovery logic was previously available only as `/bm-project` / `/bm-workspace` slash commands — useful for humans, invisible to the agent. Together with the `project_id` routing landed in #4, these unblock the workflow Drew's friction note flagged:

`bm_projects()` → pick by name + workspace → `bm_write(... project_id=)`

instead of silently operating against the active Hermes memory project.

`bm_projects` returns JSON with name + `external_id` (UUID) per project — the UUID is exactly what `project_id` on the read/write tools expects. `bm_workspaces` returns workspaces with name, type, role, and default flag.

Design notes

  • A new `_GLOBAL_TOOLS` frozenset marks both tools as discovery-only. The post-construction routing loop on `TOOL_SCHEMAS` skips them when adding `project` / `project_id` properties (the BM tools don't accept those), and `_translate_args` skips its routing block for them. Forward-compatible: future discovery tools can opt in by adding their name.
  • Both tools always request `output_format=json` — the agent needs to parse identifiers reliably, and JSON is more robust than text-mode pretty-printed output.
  • Slash commands `/bm-project` and `/bm-workspace` are unchanged — they still call the MCP tools directly via the actor. No human-facing behavior change.
  • `system_prompt_block` lists the two new tools and points the agent to `bm_projects` as the source of UUIDs for cross-project routing.

Test plan

  • Unit suite passes (`uv run --with pytest pytest`) — 239 passed, 12 skipped (integration, gated).
  • New tests cover: bm_projects translates to list_memory_projects with output_format=json and no project args; bm_workspaces same for list_workspaces; project/project_id are stripped from outputs even when callers pass them.
  • Existing schema-count tests updated to expect 10 tools (was 8).
  • `test_every_tool_schema_advertises_project_routing` now asserts global tools DON'T advertise routing — locks in the asymmetry.
  • Smoke-test on a live Hermes session: call `bm_projects` and verify the agent gets back a JSON array with usable `external_id` values; then call `bm_write(... project_id=)` and confirm the note lands in the right project on the right workspace. (Manual.)

🤖 Generated with Claude Code

groksrc and others added 3 commits May 12, 2026 14:19
Promote the discovery logic previously available only as /bm-project
and /bm-workspace slash commands to agent-facing tools. Adds two
entries to _HERMES_TO_BM (→ list_memory_projects, list_workspaces)
and corresponding TOOL_SCHEMAS entries.

These are global discovery tools — they list across all projects and
workspaces, so they don't take routing args. A new _GLOBAL_TOOLS
frozenset gates the per-tool routing logic in both directions: the
post-construction loop on TOOL_SCHEMAS skips them when adding the
routing properties, and _translate_args skips the routing block for
them. Both tools request output_format=json since the agent needs to
parse identifiers (UUIDs, workspace slugs) out of the response.

system_prompt_block now lists the two new tools so the agent reaches
for them when the user names a project that isn't the configured one.

Together with the project_id routing landed in #4, these unblock the
flow Drew's friction note flagged: the agent can now bm_projects() →
pick by name+workspace → bm_write(... project_id=<uuid>) instead of
silently operating against the active Hermes memory project.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This PR ships alongside the project_id routing changes in the same
0.3.0 release rather than its own minor bump. Merge the two entries
into a single 0.3.0 section.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
After evaluating bm_import: no new capability over read_file + bm_write
(now that #4 added project_id routing). Adding it would burn a tool
slot for what's already a clean two-call composition. Documenting the
read → write pattern in SKILL.md is the better fix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@groksrc

groksrc commented May 12, 2026

Copy link
Copy Markdown
Member Author

Quick design update: dropped the planned bm_import follow-up after evaluating the cost/benefit.

The original friction note proposed a tool with shape {path, project, workspace, folder, title}. After landing per-call project routing (#4) and bm_projects / bm_workspaces discovery (this PR), every piece of that signature decomposes into existing primitives: path → agent reads the file via Hermes's filesystem tools; project/workspace → handled by project_id on bm_write; folder and title → already on bm_write. No new capability — just a wrapper that bundles two existing calls.

Costs of adding it anyway: extra tool slot (context budget on every turn), an asymmetric "do-multiple-things" tool in an otherwise compositional surface, no native BM CLI equivalent to fall back to, and built-in policy decisions (title inference, frontmatter handling) the agent currently makes explicitly.

The remaining follow-up — a SKILL.md update documenting the discovery → route → write → verify pattern with a worked example matching the friction note's scenario — should close out this thread of work. If we later see the agent reliably getting the read-then-write pattern wrong even with skill docs in place, we can revisit.

@groksrc groksrc merged commit d4c7e48 into main May 12, 2026
5 checks passed
@groksrc

groksrc commented May 12, 2026

Copy link
Copy Markdown
Member Author

Folded the SKILL.md update (task #13) into this PR — the skill documents the new tools, so they ship together. Adds entries for bm_recent (previously undocumented since 0.2.0), bm_projects, bm_workspaces, a "Cross-project routing" section explaining project vs project_id precedence, and a worked recipe for "save this markdown file to my personal main project" matching the original friction note. Latest commit: b0c1c27.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant