This repository was archived by the owner on May 31, 2026. It is now read-only.
fix: cross-project routing recipe + backfill bm_recent#6
Merged
Conversation
…workspaces Adds the missing tool entries (bm_recent has been around since 0.2.0 but the skill never documented it; bm_projects/bm_workspaces are new in this PR) and a worked recipe for the friction scenario from "Hermes Basic Memory Cloud Task Experience": discover (bm_projects) → read file → write with project_id → verify Cross-project routing gets its own section explaining project vs project_id and the workspace disambiguation flow. The "When to use" table extends to cover the new tools and the cross-project case so the agent has a single lookup index. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
After digging into basic-memory's recent workspace-routing work
(PRs #790, #795, #801, #803, #807, #808 in basicmachines-co/basic-memory),
the canonical permalink can carry up to three levels of routing —
short ('folder/note'), project-qualified ('project/folder/note'),
and workspace-qualified ('workspace/project/folder/note'). The
read/write tools accept all three shapes, and the returned permalink
from bm_write self-routes for follow-up reads when written with a
workspace-qualified project.
Two updates land in this commit:
1. New "Permalinks" section in SKILL.md documenting the three shapes
with a worked table and the round-trip property. Memory:// URLs
follow the same shapes and now get covered in the same section
(the old one-line "Memory URLs" section is folded in).
2. The "Cross-project routing" section now explains that the `project`
argument itself accepts workspace-qualified syntax
('personal/main', 'team-paul/research') — not only project_id can
disambiguate workspaces. project_id is still highlighted as the
most durable form (survives renames).
The recipe at the bottom of SKILL.md is updated to leverage the
permalink round-trip: write with workspace-qualified `project=`,
capture the returned (workspace-qualified) permalink, then read it
back with no `project` arg needed.
Updates the [0.3.0] CHANGELOG entry to mention the Permalinks section
addition.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The previous examples used '01HXYZ...' and 'uuid-1' as project_id placeholders. The actual external_id values BM emits are str(uuid.uuid4()) (see basic-memory/src/basic_memory/models/project.py:45), so the examples should look like UUIDs. Uses two distinct fake UUIDs across SKILL.md and tests so they don't look like shared state: - bf2a4c1e-d77f-4b7a-9c3e-5d8a1f0e2b6d (SKILL.md examples + one test) - e1d3a5b8-0492-4c1f-8e7d-2a4b6c8d0e2f (parametrized routing test) SKILL.md uses ellipsed forms (bf2a4c1e-d77f-...) where the literal is purely a placeholder, and the full UUID where the example is showing what bm_projects actually returns. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a "Further reading" section to SKILL.md linking the official docs with raw-markdown URLs (/raw/<path>.md) the agent can WebFetch on demand for deeper material than the skill itself contains. Mentions the Accept: text/markdown content-negotiation alternative and points at the llms.txt sitemap index for discovering pages not curated here. Curated links cover knowledge format, observations & relations, memory URLs (wildcards, title-based addressing), projects & folders, semantic search, BM's full MCP tool surface, and cloud routing. Each link has a one-line note describing when to reach for it. Tightens the "Note structure" section to call out that observation categories ([decision], [insight], [risk], …) and relation types (relates_to, implements, …) are open-ended — the BM docs explicitly embrace user-defined values. Adds a one-line note about YAML frontmatter conventions (title, type, tags, permalink) with a link to the knowledge-format reference. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
groksrc
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Brings SKILL.md in sync with the tool surface as of 0.3.0. Originally drafted as part of #5 but landed here separately after the merge. Closes the documentation half of the work prompted by "Hermes Basic Memory Cloud Task Experience" — paired with #4 (per-call routing) and #5 (`bm_projects` / `bm_workspaces`), the friction is now fully addressed.
Additions to `skill/SKILL.md`:
Also rolls the SKILL.md bullet into the `[0.3.0]` CHANGELOG entry (the section's note previously called this out as a "remaining follow-up").
Test plan
🤖 Generated with Claude Code