Skip to content

perf(cli): keep the MCP tool stack out of the SessionStart brief - #2113

Merged
phernandez merged 1 commit into
mainfrom
perf/2101-session-start-imports
Nov 15, 2026
Merged

phernandez merged 1 commit into
mainfrom
perf/2101-session-start-imports

Conversation

@phernandez

Copy link
Copy Markdown
Member

Follow-up to #2101 and #2109.

Problem

#2109 makes the hook environment compile bytecode, but the reporter's compiled SessionStart still took 14–18 s. Their profile showed import basic_memory.mcp.tools at 9.3 s. The brief only runs a few filtered searches, yet it loaded every tool, FastMCP's server and the MCP server.

Two things pulled that in:

  • The brief called the bm_search tool.
  • The HTTP helpers every typed client uses (call_get, call_query, ...) lived in mcp/tools/utils.py. Importing any of them ran tools/__init__.py, which registers every tool. So even the plain SearchClient loaded the whole tool stack.

Change

  • mcp/tools/utils.py moves to mcp/api_calls.py, outside the tools package. Every reference uses the new path; there is no alias.
  • The brief's search is now _search_notes in cli/commands/hook.py. It resolves the project with get_project_client and sends the same SearchQuery that bm_search sends for those arguments (note types, frontmatter filters, since, note rows only), through SearchClient. _query keeps the timeout and treats any failure as no data, as before.

Results

On macOS with bytecode compiled, bm hook session-start against my real config:

main this branch
import time 2.24 s 1.75 s
basic_memory.mcp.tools, basic_memory.mcp.server, fastmcp.server loaded yes no
brief output identical

Without bytecode the import cost is several times larger, so the saving on the reporter's machine should be several seconds. What still loads is needed: the local API app (~380 ms, local projects only), the database layer, and fastmcp.exceptions (~275 ms), because the helpers raise ToolError.

Tests

  • test_brief_search_matches_bm_search_for_the_same_filters: on a real project, the brief's search and bm_search return the same notes for the same filters.
  • test_brief_search_reads_an_unknown_project_as_no_data
  • test_session_start_never_imports_the_mcp_tool_stack: runs the brief's search in a subprocess with a temporary home and asserts the tool stack and MCP server never load. It fails on main's hook code.
  • just fast-check passes. just fast-test: 1242 passed.
  • Existing hook tests that patched basic_memory.mcp.tools.bm_search now patch hook._search_notes, which takes the same keyword arguments.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CMYVL1rjJwNnrvxniz1dDD

The brief ran its searches through the bm_search tool, and every typed client
reached its HTTP helpers through mcp/tools/utils.py. Either path executed
tools/__init__.py, which loads every tool, FastMCP's server and the MCP server.
The reporter of #2101 measured that import at 9.3 s of a SessionStart.

The HTTP helpers move to mcp/api_calls.py, outside the tools package. The brief
searches through SearchClient with the same SearchQuery bm_search sends for its
arguments. On macOS with compiled bytecode, SessionStart import time drops from
2.24 s to 1.75 s and the brief is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CMYVL1rjJwNnrvxniz1dDD
Signed-off-by: phernandez <paul@basicmachines.co>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-13T01:41:12.403405Z ef32d76 PR opened
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@phernandez
phernandez merged commit c3bf1e2 into main Nov 15, 2026
51 checks passed
@phernandez
phernandez deleted the perf/2101-session-start-imports branch November 15, 2026 23:41
groksrc added a commit that referenced this pull request Nov 18, 2026
…indows (#2129)

## Summary

Fixes the one test from #2121 that fails on every Windows run of `main`.
The product code is fine. The test expected a content-neutral rename,
but the test config made indexing rewrite the file during the rename.
This PR also makes pull requests run the test file on Windows, so this
kind of failure shows up before merge.

## What failed


`tests/indexing/test_storage_change_journal.py::test_storage_rename_leaves_one_moved_row`
fails on the Windows SQLite unit shard of `main`, most recently in run
[44118870413](https://github.com/basicmachines-co/basic-memory/actions/runs/44118870413)
at `b4b2c226`:

```
>       [moved] = await journal_after(session_maker, test_project, created.partition_position)
E       ValueError: too many values to unpack (expected 1)
```

## Why

- The shared test config sets `update_permalinks_on_move=True`
(`tests/conftest.py:308`). When the rename is indexed, that rewrites the
moved note's `permalink` frontmatter.
- `write_file_atomic` writes text with the platform's newline
(`src/basic_memory/file_utils.py:138-146`), so on Windows the rewrite is
stored with CRLF line endings. That behaviour is deliberate.
- The stored checksum then differs from the planned checksum. The
`moved` row stays unsettled, and the same index run promotes the stored
bytes as a new version, which journals an `updated` row. This is the
designed recovery path from #2121, not a bug.
- So on Windows the test saw two rows after the rename (`moved`,
`updated`) where it expected one.

## What changed

- **The test.** `test_storage_rename_leaves_one_moved_row` now turns
`update_permalinks_on_move` off, so the rename really leaves the file's
bytes unchanged. It also asserts that the `moved` row carries the note's
existing `db_version` and `db_checksum`, which pins down "unchanged
content". The rewrite path is already covered by
`test_scan_move_keeps_a_rewritten_note_row_unsettled_when_storage_holds_other_bytes`
and `..._when_its_write_fails` in
`tests/indexing/test_project_index_maintenance.py`.
- **CI.** `test.yml` runs the full Windows unit suite only on `main`.
This PR adds `tests/indexing/test_storage_change_journal.py` to the
`test-windows-platform` job's file list, so pull requests run it on
Windows.

No product code changes.

## Verification

All local runs on macOS, from `origin/main` at `b4b2c226`:

- **Reproduced the Windows failure before the fix.** I used a scratch
pytest plugin, kept outside the repo, that makes `write_file_atomic`
write CRLF the way Windows does. The old test failed with `ValueError:
too many values to unpack (expected 1, got 2)`.
- **After the fix, with CRLF forced:**
`tests/indexing/test_storage_change_journal.py`, `4 passed`.
- **After the fix, native:** SQLite `4 passed`; PostgreSQL
(`BASIC_MEMORY_TEST_POSTGRES=1`, testcontainers) `4 passed`.
- `ruff check`, `ruff format --check` and `ty check` pass on the changed
test. `test.yml` still parses as YAML.
- The Windows job on this PR is the proof on real Windows.

## Out of scope


`tests/mcp/test_hook_brief_search.py::test_session_start_never_imports_the_mcp_tool_stack`
also fails on some Windows runs of `main`. It comes from #2113 and is
not touched here.

Ticket: BMEM-116 (Drew's board).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Signed-off-by: Drew Cain <groksrc@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant