feat(mcp): ship the manual in the package and serve it as resources - #1389
Conversation
Second slice of #610, grown out of the #952 manual: - src/basic_memory/man/man3/: the 23 section-3 pages (one per MCP tool) pulled from the `manual` project and made canonical in the package, as portable notes -- frontmatter intact minus the cloud-assigned permalink. Every install now ships the same pages: local, cloud, offline. - basic_memory.man: the page model, a lenient page-reference parser, and man(1)-style resolution. Parse, don't validate: search-notes(3), search-notes.3, 3/search-notes, man3/search-notes, search_notes and percent-encoded forms all name the same page; the section is optional and the lowest wins, as in man. - MCP resources: memory://man is the index (apropos) and memory://man/{ref*} answers any spelling of a page. Every page is also registered as a concrete resource so clients that browse resources/list see each one with its summary. Unknown pages raise a ResourceError that points at the index. Server instructions send agents to a tool's page before first use. - bm man <topic> prints a page as Markdown (any spelling; a first argument that is not a subcommand is a topic, like man), bm man list is apropos, bm man install is unchanged. - Tests pin the section-3 corpus against the tool registry: the one tool without a page (basic_memory_diagnostics) and the three pages without a local tool (canvas, cloud_info, release_notes) are named explicitly, so a new tool or a retired page shows up as a test change. Supersedes the flat generated reference from #1380/#1385 (#404); the registry generator for SYNOPSIS/PARAMETERS is the next slice. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp Signed-off-by: phernandez <paul@basicmachines.co>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f28f6ea23e
ℹ️ 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".
…tool schema Codex review of #1389 caught pages whose SYNOPSIS no longer matched the shipped tool: delete-project(3) omitted the destructive delete_notes flag and promised file retention unconditionally; list-directory(3) claimed there was no structured output while output_format, sort, page, and page_size exist. A scan found the same drift in edit-note(3) (replace_subsections, metadata) and write-note(3) (workspace). All four pages now document the current parameters, and a test asserts that every section-3 SYNOPSIS names exactly the parameters in the live tool schema, so the next added parameter fails CI instead of waiting for a reader. The server instruction no longer promises a page for every tool (basic_memory_diagnostics has none yet); it points at the index. The verified: stamps are unchanged -- the examples on those pages ran on 0.21.6 and were not re-run here; the SYNOPSIS is now checked by test. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp Signed-off-by: phernandez <paul@basicmachines.co>
…tool schema Codex review of #1389 caught pages whose SYNOPSIS no longer matched the shipped tool: delete-project(3) omitted the destructive delete_notes flag and promised file retention unconditionally; list-directory(3) claimed there was no structured output while output_format, sort, page, and page_size exist. A scan found the same drift in edit-note(3) (replace_subsections, metadata) and write-note(3) (workspace). All four pages now document the current parameters, and a test asserts that every section-3 SYNOPSIS names exactly the parameters in the live tool schema, so the next added parameter fails CI instead of waiting for a reader. The server instruction no longer promises a page for every tool (basic_memory_diagnostics has none yet); it points at the index. The verified: stamps are unchanged -- the examples on those pages ran on 0.21.6 and were not re-run here; the SYNOPSIS is now checked by test. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp Signed-off-by: phernandez <paul@basicmachines.co>
7e47e80 to
2d8b1c9
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2d8b1c9e04
ℹ️ 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".
…mode The page told readers to omit project for cross-project discovery. In the normal case a session's active project or the configured default resolves first, so omitting project returns that project's activity and discovery only runs when nothing resolves. Document the resolution order, fix the parameter line, and add a gotcha with the ways to survey every project. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp Signed-off-by: phernandez <paul@basicmachines.co>
ecc4536 to
4db7044
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4db7044990
ℹ️ 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".
…read_content fidelity Codex review of #1389, third pass: - canvas(3) and release-notes(3) documented tools removed in #1111 and #1145 that exist on neither the local nor the hosted server; dropped. - cloud-info(3) documents a tool that only the hosted server registers; the page now says so in its summary and description, and the memory://man index marks any page whose tool this server does not register, computed from the live registry, so the same corpus stays honest on both servers. - read-content(3) promised raw bytes for everything. Text is byte-exact; images are resized and re-encoded as JPEG; other binaries are returned base64 up to 350,000 bytes and error above. The page now says which. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp Signed-off-by: phernandez <paul@basicmachines.co>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b6c380b6b7
ℹ️ 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".
write_note stores the title in frontmatter and derives the permalink from it; the body is saved as given, so a note whose content has no heading ends up with no H1. The page now says so and tells callers to include the heading themselves. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp Signed-off-by: phernandez <paul@basicmachines.co>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2911605f37
ℹ️ 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".
… relations Codex review of #1389, fifth pass: - cloud-info(3) and read-content(3) still linked to release-notes(3) and canvas(3) after those pages were dropped. Removed, and a test now asserts every [[name(3)]] link in the bundle lands on a bundled page. - delete-note(3) said relations to a deleted note become permanently unresolved. Since #1344 the target id is cleared and the link text kept, and the forward-reference pass relinks when a note with that name is written again. The page now describes that recovery and keeps the archive-over-delete pattern for the right reason. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp Signed-off-by: phernandez <paul@basicmachines.co>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a0f2b978ac
ℹ️ 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".
Codex review of #1389, sixth pass: - find_page now accepts the tool name as an alias for the page name, so memory://man/search(3) and memory://man/fetch(3) reach chatgpt-search(3) and chatgpt-fetch(3) as the server instruction promises. An exact page name still wins over an alias. - chatgpt-search(3) and chatgpt-fetch(3) state that the tools answer only OpenAI clients; everyone else gets 'Unsupported MCP client'. - delete-note(3), move-note(3), and write-note(3) examples showed a structured response without asking for it; they now pass output_format="json" so the shown shape is what a copy returns. - move-note(3) qualifies permalink preservation: it is the default, and update_permalinks_on_move=True (or a note with no permalink) rewrites the permalink from the destination path. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp Signed-off-by: phernandez <paul@basicmachines.co>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cb30369348
ℹ️ 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".
Codex review of #1389, seventh pass, generalized: eleven GOTCHAS entries across nine pages described defects as 'fixed in #N, pending release', 'on main, unreleased', or 'verified fixed at HEAD'. Those fixes (#908, #971, #981, cloud#1173) are in this tree, and the pages now ship with the tree, so each entry told readers about a bug they do not have. Removed, and a test asserts no bundled page carries such a stamp again. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp Signed-off-by: phernandez <paul@basicmachines.co>
Codex review of #1389, seventh pass, generalized: eleven GOTCHAS entries across nine pages described defects as 'fixed in #N, pending release', 'on main, unreleased', or 'verified fixed at HEAD'. Those fixes (#908, #971, #981, cloud#1173) are in this tree, and the pages now ship with the tree, so each entry told readers about a bug they do not have. Removed, and a test asserts no bundled page carries such a stamp again. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp Signed-off-by: phernandez <paul@basicmachines.co>
5023821 to
c8fc6aa
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c8fc6aaa47
ℹ️ 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".
…project resolve_project_parameter promotes the session's cached active project over the configured default, so omitting project after touching another project writes there, not to the default. The page said the opposite. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp Signed-off-by: phernandez <paul@basicmachines.co>
1 participant
Second slice of #610, built on the #952 manual. Closes #404.
What
The manual's section 3 — one Unix-style page per MCP tool,
write-note(3),search-notes(3), … — now ships in the package and is served over MCP.src/basic_memory/man/man3/— the 21 section-3 pages, pulled from the cloudmanualproject and made canonical here as portable notes (frontmatter intact minus the cloud-assignedpermalink). Every install ships the same pages: local, cloud, offline. Verified in a built wheel.basic_memory.man— page model, a lenient page-reference parser, and man(1)-style resolution. Parse, don't validate: all of these name the same page —search-notes(3)·search-notes.3·search-notes-3·3/search-notes·man3/search-notes·search_notes·search-notes%283%29·man3/search-notes(3).md— the section is optional and the lowest wins, as in
man.memory://manis the index (apropos),memory://man/{ref*}answers any spelling of a page. Every page is also registered as a concrete resource, so clients that browseresources/list(Claude Desktop's picker, Cursor's@) see each page with its summary. Unknown pages raise aResourceErrorpointing at the index. The server instructions now send agents tomemory://man/<tool>(3)before first use of a tool.bm man <topic>prints a page as Markdown (any spelling; a first argument that isn't a subcommand is a topic, likeman),bm man listis apropos,bm man installis unchanged.Why this shape
We had two per-tool references in flight: the hand-verified manual (cloud-only) and a flat generated
docs/mcp-tools.md(#1380/#1385). The manual is the system of record, but it wasn't in the repo — a GitHub visitor or a local-first install had no per-tool reference at all. Bundling section 3 fixes that without a second generator, and resources make the pages reachable from any MCP client with zero projects configured. Both URI shapes are accepted because an agent's first guess is whichever form its training weighted; the parser meets it there.Tests
tests/test_man_pages.py,tests/mcp/test_man_resources.py,tests/cli/test_man_command.py— 47 tests. One pins the section-3 corpus against the tool registry with the gaps named explicitly (basic_memory_diagnosticshas no page;cloud_infois hosted-only), and one asserts every SYNOPSIS names exactly the parameters in the live tool schema — so a new tool, a new parameter, or a retired page surfaces as a test change rather than silently drifting. The index marks pages whose tool this server does not register.Not in this PR (next slices)
mcp.list_tools()(aliases included) with a drift test; the good idea from docs(mcp): add downloadable MCP tool reference artifact #1380, attached to the manual instead of a parallel file.bm man install --project <name>— copy the pages into a project as notes soSEE ALSObecomes relations.verified: 0.21.6; a few cite bugs since fixed (feat(core): add observation category filter to search #908, Workspace project index never refreshes on miss — out-of-band/teammate-created projects invisible and unroutable by project_id in running sessions #956→fix(mcp): close out the #952 manual verification findings #981). Review already correcteddelete-project,list-directory,edit-note,write-note,recent-activity,read-content, and droppedcanvas(3)/release-notes(3)(tools retired in refactor(mcp): remove canvas tool and resource write endpoints #1111/feat(mcp): first-connect onboarding — instructions, empty-state guidance, getting_started prompt #1145).basic_memory_cloudimportsbasic_memory.mcp.promptsbut not.resources; one import line needed there for the hosted server to exposememory://man.basic-memory-diagnostics(3)page.Verification
ruff check/ruff format --checkclean on changed files;ty check src tests test-intclean;pyrightclean on the new modulesuv build --wheelincludes all pages underbasic_memory/man/man3/bm manstays inskip_init_commands, so reading a page never touches the database🤖 Generated with Claude Code
https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp