Update README.md

add devin deep wiki badge for weekly updates

Signed-off-by: Paul Hernandez <60959+phernandez@users.noreply.github.com>

.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official Basic Memory plugins from the canonical basic-memory repository",
-    "version": "0.22.0"
+    "version": "0.22.1"
   },
   "plugins": [
     {
       "name": "basic-memory",
       "source": "./plugins/claude-code",
       "description": "The bridge between Claude's working memory and Basic Memory's durable knowledge graph \u2014 session briefings, pre-compaction checkpoints, and capture reflexes",
-      "version": "0.22.0",
+      "version": "0.22.1",
       "author": {
         "name": "Basic Machines"
       },

.claude/commands/release/release.md

@@ -28,7 +28,10 @@ You are an expert release manager for the Basic Memory project. When the user ru
 
 #### Documentation Validation
 1. **Changelog Check**
-   - CHANGELOG.md contains entry for target version
+   - CHANGELOG.md contains entry for target version **already landed on `main`**
+     (main only accepts changes via PR, so the changelog entry must go through
+     its own PR before running the release; the recipe pre-flight-checks for a
+     `## vX.Y.Z` heading)
    - Entry includes all major features and fixes
    - Breaking changes are documented
 
@@ -41,11 +44,15 @@ just release <version>
 The justfile target handles:
 - ✅ Version format validation
 - ✅ Git status and branch checks
-- ✅ Quality checks (`just check` - lint, format, type-check, tests)
+- ✅ Changelog entry check (must already be on `main`)
+- ✅ Quality checks (`just lint` + `just typecheck`)
 - ✅ Version update across all consolidated manifests via `just set-version` (Python
   package + Claude Code plugin/marketplaces + Codex plugin + Hermes + OpenClaw)
-- ✅ Automatic commit with proper message
-- ✅ Tag creation and pushing to GitHub
+- ✅ Release PR: commits the bump on a `release/vX.Y.Z` branch, opens a PR
+  (`chore(core): release vX.Y.Z`), and rebase-merges it — the `main` ruleset
+  rejects direct pushes and the repo disallows merge commits
+- ✅ Tags the rebased bump commit on `main` (found by commit subject, since
+  the rebase rewrites the SHA) and pushes the tag
 - ✅ Release workflow trigger (automatic on tag push)
 
 The GitHub Actions workflow (`.github/workflows/release.yml`) then:
@@ -89,7 +96,7 @@ After PyPI release is published, update the MCP registry:
 
 2. **Publish to MCP Registry**
    ```bash
-   cd /Users/drew/code/basic-memory
+   # from the basic-memory repo root
    mcp-publisher publish
    ```
 
@@ -109,43 +116,50 @@ After PyPI release is published, update the MCP registry:
 
 #### Website Updates
 
-**1. basicmachines.co** (`/Users/drew/code/basicmachines.co`)
-   - **Goal**: Update version number displayed on the homepage
-   - **Location**: Search for "Basic Memory v0." in the codebase to find version displays
-   - **What to update**:
-     - Hero section heading that shows "Basic Memory v{VERSION}"
-     - "What's New in v{VERSION}" section heading
-     - Feature highlights array (look for array of features with title/description)
-   - **Process**:
+**1. basicmemory.com** (sibling `basicmemory.com` repo —
+`basicmachines-co/basicmemory.com`, formerly `basicmachines.co`)
+   - **No version bump needed.** The marketing site is an Astro + React app and
+     carries **no hardcoded Basic Memory version number** anywhere in its UI
+     (`hero.tsx` and the rest of the site have no version string). The old
+     instruction to bump `src/components/sections/hero.tsx` is obsolete — that
+     file no longer holds a version. Release announcements are dated blog posts,
+     not an in-place edit.
+   - **Skip entirely for patch releases.**
+   - **Significant releases only — optional announcement post**:
      1. Pull latest from GitHub: `git pull origin main`
      2. Create release branch: `git checkout -b release/v{VERSION}`
-     3. Search codebase for current version number (e.g., "v0.16.1")
-     4. Update version numbers to new release version
-     5. Update feature highlights with 3-5 key features from this release (extract from CHANGELOG.md)
-     6. Commit changes: `git commit -m "chore: update to v{VERSION}"`
-     7. Push branch: `git push origin release/v{VERSION}`
-   - **Deploy**: Follow deployment process for basicmachines.co
+     3. Add a dated post under `src/content/blog/` modeled on an existing
+        release post (e.g. `basic-memory-v0-19-0-release.md`), summarizing 3–5
+        headline features from `CHANGELOG.md`
+     4. Commit (`git commit -s -m "..."`), push, and open a PR against
+        `basicmachines-co/basicmemory.com`
+   - **Deploy**: follow that repo's deployment process.
 
-**2. docs.basicmemory.com** (`/Users/drew/code/docs.basicmemory.com`)
-   - **Goal**: Add new release notes section to the latest-releases page
-   - **File**: `src/pages/latest-releases.mdx`
+**2. docs.basicmemory.com** (sibling `docs.basicmemory.com` repo)
+   - **Goal**: Add a What's New page for the release and bump the homepage badge
+   - **Site shape**: Nuxt/Docus content site. The changelog page
+     (`content/2.whats-new/*.changelog.md`) auto-fetches GitHub releases — no
+     manual changelog update needed. See that repo's CLAUDE.md "Version Bump
+     Checklist".
    - **What to do**:
      1. Pull latest from GitHub: `git pull origin main`
      2. Create release branch: `git checkout -b release/v{VERSION}`
-     3. Read the existing file to understand the format and structure
-     4. Read `/Users/drew/code/basic-memory/CHANGELOG.md` to get release content
-     5. Add new release section **at the top** (after MDX imports, before other releases)
-     6. Follow the existing pattern:
-        - Heading: `## [v{VERSION}](github-link) — YYYY-MM-DD`
-        - Focus statement if applicable
-        - `<Info>` block with highlights (3-5 key items)
-        - Sections for Features, Bug Fixes, Breaking Changes, etc.
-        - Link to full changelog at the end
-        - Separator `---` between releases
-     7. Commit changes: `git commit -m "docs: add v{VERSION} release notes"`
-     8. Push branch: `git push origin release/v{VERSION}`
-   - **Source content**: Extract and format sections from CHANGELOG.md for this version
-   - **Deploy**: Follow deployment process for docs.basicmemory.com
+     3. Read `CHANGELOG.md` in the `basic-memory` repo to get release content
+     4. **New minor/major release**: add `content/2.whats-new/1.v{VERSION}.md`
+        modeled on the previous version page (frontmatter title/description,
+        headline feature first, then sections, then an Upgrading note) and
+        renumber the existing what's-new pages down one slot (URLs don't
+        change — Nuxt strips the numeric prefixes)
+     5. **Patch release**: append a short note to the current version's page
+        instead of creating a new one
+     6. Update the homepage version badge in `content/index.md` (the
+        `v0.XX →` button text and its `to: /whats-new/v{VERSION}` link)
+     7. If the release adds user-facing features, update the relevant guide
+        and reference pages (`content/3.cloud/`, `content/9.reference/`)
+     8. Commit: `git commit -s -m "docs: add v{VERSION} release notes"`
+     9. Push branch and open a PR; merge after the release is tagged
+   - **Deploy**: push to main auto-deploys to development; production requires
+     manual workflow dispatch via GitHub Actions
 
 **4. Announce Release**
    - Post to Discord community if significant changes

AGENTS.md

@@ -300,7 +300,9 @@ See SPEC-16 for full context manager refactor details.
 
 ### Release Process
 
-Releases are driven by `just release` / `just beta` — never by a bare `git tag`. The recipes bump version metadata, run pre-flight checks, commit, tag, and push. GitHub Actions then publishes to PyPI and updates the Homebrew formula.
+Releases are driven by `just release` / `just beta` — never by a bare `git tag`. The recipes bump version metadata, run pre-flight checks, land the bump on `main` through a release PR, tag, and push the tag. GitHub Actions then publishes to PyPI and updates the Homebrew formula.
+
+**Main requires PRs.** The `main` ruleset rejects direct pushes ("Changes must be made through a pull request") and the repo disallows merge commits, so the recipes push a `release/vX.Y.Z` branch, open a PR titled `chore(core): release vX.Y.Z`, rebase-merge it with `gh pr merge --rebase`, then tag the rebased bump commit on `main` (located by its commit subject, since rebasing rewrites the SHA) and push the tag. The CHANGELOG entry for the version must already be on `main` — land it via a normal PR before running the recipe (it pre-flight-checks for a `## vX.Y.Z` heading).
 
 **Stable release:**
 
@@ -308,7 +310,7 @@ Releases are driven by `just release` / `just beta` — never by a bare `git tag
 just release v0.21.3
 ```
 
-The recipe runs `just lint` + `just typecheck`, then updates every release manifest through `scripts/update_versions.py`: `src/basic_memory/__init__.py`, `server.json`, the root Claude marketplace, the Claude Code plugin manifest and local marketplace, the Hermes `plugin.yaml`, and the OpenClaw `package.json`. It commits as `chore: update version to X.Y.Z for vX.Y.Z release`, creates the `vX.Y.Z` tag, and pushes both the commit and the tag to `origin/main`. After the tag lands, the `Release` workflow builds the Python package, publishes to PyPI, creates the GitHub release with auto-generated notes, publishes the OpenClaw npm package, and updates the Homebrew formula. The recipe finishes by printing the post-release tasks the workflow doesn't cover.
+The recipe runs `just lint` + `just typecheck`, then updates every release manifest through `scripts/update_versions.py`: `src/basic_memory/__init__.py`, `server.json`, the root Claude marketplace, the Claude Code plugin manifest and local marketplace, the Hermes `plugin.yaml`, and the OpenClaw `package.json`. It commits as `chore: update version to X.Y.Z for vX.Y.Z release` on a `release/vX.Y.Z` branch, lands it on `main` via a rebase-merged PR, then tags the rebased commit and pushes the tag. After the tag lands, the `Release` workflow builds the Python package, publishes to PyPI, creates the GitHub release with auto-generated notes, publishes the OpenClaw npm package, and updates the Homebrew formula. The recipe finishes by printing the post-release tasks the workflow doesn't cover.
 
 **Beta release:** `just beta v0.21.3b1` — same flow with a beta-suffixed tag. PyPI consumers install with `pip install basic-memory --pre`.
 
@@ -319,8 +321,13 @@ The recipe runs `just lint` + `just typecheck`, then updates every release manif
 **Do not tag releases by hand.** A bare `git tag vX.Y.Z` skips the in-code version bump. Package metadata is still correct (uv-dynamic-versioning derives it from the git tag) but `basic-memory --version` reports the previous release, which is what happened with v0.21.2 → v0.21.3.
 
 **Post-release tasks** the recipe surfaces but doesn't run:
-- `docs.basicmemory.com` — add notes to `src/pages/latest-releases.mdx`
-- `basicmachines.co` — bump version in `src/components/sections/hero.tsx`
+- `docs.basicmemory.com` — add a What's New page under `content/2.whats-new/` and bump the version badge in `content/index.md` (the changelog page auto-fetches GitHub releases; see that repo's CLAUDE.md version-bump checklist)
+- `basicmemory.com` — the marketing site (Astro + React, repo
+  `basicmachines-co/basicmemory.com`, formerly `basicmachines.co`) carries **no
+  hardcoded version number** in its UI, so there is nothing to bump. For a
+  significant release, optionally add a dated announcement post under
+  `src/content/blog/` (model it on an existing `basic-memory-vX-Y-Z-release.md`).
+  Skip entirely for routine patch releases.
 - MCP Registry — `mcp-publisher publish` from the repo root
 
 See `.claude/commands/release/release.md` (and `beta.md`, `release-check.md`, `changelog.md` alongside it) for the full release + post-release runbook, including the slash commands.

CHANGELOG.md

@@ -1,5 +1,49 @@
 # CHANGELOG
 
+## v0.22.1 (2026-06-12)
+
+Follow-up patch to v0.22.0. Fixes project and default-project resolution on
+fresh installs, MCP workspace routing, sync project selection, and CLI startup
+latency, plus a few MCP parity additions.
+
+### Features
+
+- Added a `workspace` parameter to `write_note` for parity with `edit_note`.
+- **#826**: Added `title` and `tags` annotations to all MCP tool decorators
+  (phase 1).
+- **#930**: `search_notes` now comma-splits `note_types`, `entity_types`, and
+  `categories`.
+- **#971**: Added the manual-pages flow — manpage seed schema, flow docs, and
+  verification fixes.
+
+### Bug Fixes
+
+- Fresh installs no longer fail when the projects table is empty: resolve now
+  points them at project setup, the first project is promoted to default when
+  the config default is missing from the database, the promoted default state
+  is returned from the project-create API, and a default can be set when none
+  is currently set. An existing database default is preserved when repairing a
+  missing config default.
+- **#949**: Sync skips projects without an absolute local path and excludes
+  orphan DB projects that are absent from config.
+- **#952 / #981**: Resolved workspace display names and tenant ids in qualified
+  project routes, closing out the manual verification findings.
+- `note_types`/`entity_types`/`categories` are normalized on the direct-call
+  path, with non-string list elements rejected.
+- Vector-search hydration keys on `(type, id)` to prevent id collisions.
+- `file_utils` requires line-anchored frontmatter fences.
+- CLI startup is faster: FastAPI and app imports are deferred out of CLI
+  startup, and rich/typer modules are preloaded before an in-place upgrade.
+- `config.json` is written atomically.
+- In-memory SQLite sessions are serialized so concurrent rollbacks cannot
+  destroy writes.
+
+### Maintenance
+
+- Release recipes route through PRs and wait for the release PR merge to land
+  before tagging; the release runbook is refreshed and stripped of
+  user-specific absolute paths.
+
 ## v0.22.0 (2026-06-11)
 
 Team-safe cloud sync. New additive `bm cloud push` and `bm cloud pull`

README.md

@@ -6,6 +6,7 @@
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 ![](https://badge.mcpx.dev?type=server 'MCP Server')
 ![](https://badge.mcpx.dev?type=dev 'MCP Dev')
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/basicmachines-co/basic-memory)
 
 ## Skip the install — try Basic Memory in the cloud
 
@@ -590,7 +591,7 @@ retention).
 | `BASIC_MEMORY_IMPORT_UPLOAD_MAX_BYTES` | `104857600` | Max uploaded import size |
 
 ```bash
-BASIC_MEMORY_LOG_LEVEL=DEBUG basic-memory sync
+BASIC_MEMORY_LOG_LEVEL=DEBUG basic-memory reindex
 tail -f ~/.basic-memory/basic-memory.log
 ```
 

docs/Docker.md

@@ -111,7 +111,7 @@ You can run Basic Memory CLI commands inside the container using `docker exec`:
 docker exec basic-memory-server basic-memory status
 
 # Sync files
-docker exec basic-memory-server basic-memory sync
+docker exec basic-memory-server basic-memory reindex
 
 # Show help
 docker exec basic-memory-server basic-memory --help
@@ -137,7 +137,7 @@ When using Docker volumes, you'll need to configure projects to point to your mo
 
 3. **Sync the new project:**
    ```bash
-   docker exec basic-memory-server basic-memory sync
+   docker exec basic-memory-server basic-memory reindex
    ```
 
 ### Example: Setting up an Obsidian Vault
@@ -157,7 +157,7 @@ docker exec basic-memory-server basic-memory project create obsidian /app/data
 docker exec basic-memory-server basic-memory project set-default obsidian
 
 # Sync to index all files
-docker exec basic-memory-server basic-memory sync
+docker exec basic-memory-server basic-memory reindex
 ```
 
 ### Environment Variables

docs/character-handling.md

@@ -184,8 +184,8 @@ finance/           (lowercase f)
 Use Basic Memory's built-in conflict detection:
 
 ```bash
-# Sync will report conflicts
-basic-memory sync
+# Index local file changes (conflicts are handled during the scan)
+basic-memory reindex
 
 # Check sync status for warnings
 basic-memory status

docs/manual-pages.md

@@ -0,0 +1,183 @@
+# Manual Pages
+
+Basic Memory's manual is written in the style of Unix man pages — and
+implemented as Basic Memory notes ([#952](https://github.com/basicmachines-co/basic-memory/issues/952)).
+Every page is a markdown note conforming to the `Manpage` schema, `SEE ALSO`
+entries are real knowledge-graph relations, and every example on every page
+was executed against a live project before the page shipped. The manual
+documents the tools; the tools verify the manual.
+
+## Where it lives
+
+The canonical manual is the **`manual` project in the Basic Memory team
+workspace** (cloud, shared). Anyone can build their own: the schema ships as
+an opt-in seed at `plugins/claude-code/schemas/manpage.md` — copy it into any
+project's folder and start writing pages against it.
+
+Layout:
+
+```
+manual/
+├── schemas/Manpage.md      # the manpage schema (type: schema)
+├── man1/                   # CLI commands        bm(1), bm-status(1), ...
+├── man3/                   # MCP tools           write-note(3), search-notes(3), ...
+├── man5/                   # file formats        bm-note(5), bm-observation(5), ...
+├── man7/                   # concepts            basic-memory(7), semantic-memory(7), ...
+├── playground/             # scratch notes for destructive examples
+└── diagrams/               # canvas visualizations of the manual graph
+```
+
+### Why "man1", "man3", "man5"?
+
+The folder names are Unix's, unchanged since 1971. The manual is divided
+into numbered **sections**, pages physically live in directories named
+after them (`/usr/share/man/man1`, `man5`, ...), and the number tells you
+what *kind* of thing is documented — not importance, not reading order:
+
+- **1** — user commands (`ls`, `grep`)
+- **2** — system calls
+- **3** — library functions / APIs (`printf(3)`)
+- **4** — devices
+- **5** — file formats and config files (`crontab(5)`, `passwd(5)`)
+- **6** — games (really)
+- **7** — miscellanea: concepts, conventions, overviews (`regex(7)`, `signal(7)`)
+- **8** — system administration
+
+That's also why man page names carry the parenthesized number —
+`crontab(1)` is the command, `crontab(5)` is the file format, same name in
+two sections. `man 5 crontab` picks the section explicitly.
+
+This manual copies that layout with the sections that have a Basic Memory
+analog:
+
+- **man1/** — `bm` CLI commands → `bm-status(1)`
+- **man3/** — MCP tools, our equivalent of the "library API" section → `write-note(3)`
+- **man5/** — file formats: note syntax, observations, relations, schemas → `bm-note(5)`
+- **man7/** — concepts → `basic-memory(7)`, `semantic-memory(7)`
+- **8** is reserved for admin/cloud operations but has no pages yet; 2, 4,
+  and 6 have no analog (no system calls, no devices, and no games — yet)
+
+When a page says `see_also [[bm-note(5)]]`, the `(5)` reads "the
+file-format page," exactly the way a Unix manual cross-references — except
+here it's a traversable relation in the graph instead of a typographic
+convention. The manual explains its own conventions in `man-pages(7)` —
+fittingly, the same page name Linux uses for this, and that almost nobody
+ever reads.
+
+## Page anatomy
+
+Pages use the classic headers where applicable: `NAME`, `SYNOPSIS`,
+`DESCRIPTION`, `PARAMETERS`, `MCP USAGE`, `CLI EQUIVALENT`, `EXAMPLES`,
+`GOTCHAS`, `SEE ALSO`. Frontmatter (validated by the schema):
+
+```yaml
+type: manpage
+section: 3                      # 1 | 3 | 5 | 7 | 8
+name: write-note                # page name without section suffix
+summary: create or overwrite a markdown note in the knowledge base
+generated: hand                 # hand | registry | typer  (regeneration ownership)
+tool: write_note                # section-3 pages: the MCP tool documented
+command: basic-memory status    # section-1 pages: the CLI command documented
+verified: 0.21.6 mcp+cli        # version + path(s) that proved the page
+```
+
+Field knowledge accumulates as observations — `[gotcha]`, `[bug]` (with issue
+links), `[pattern]` — and `SEE ALSO` entries are `see_also` relations, so the
+manual is a navigable graph, not a folder of files.
+
+## How to use it
+
+Man-style reads (any MCP client or the CLI):
+
+```bash
+# read a page
+bm tool read-note "man3/write-note-3" --project manual
+
+# apropos — find pages by section, tool, or text
+bm tool search-notes --project manual          # then filter, or via MCP:
+#   search_notes(project="manual", metadata_filters={"type": "manpage", "section": 3})
+#   search_notes(project="manual", metadata_filters={"type": "manpage", "tool": "write_note"})
+
+# traverse SEE ALSO from any page
+#   build_context(url="man3/write-note-3", project="manual")
+```
+
+A future `bm man <topic>` command is thin sugar over exactly these calls.
+
+And for the real thing — `man bm` in an actual terminal:
+
+```bash
+bm man install        # copies bundled groff pages to ~/.local/share/man
+man bm                # the overview page, rendered by man(1)
+man basic-memory      # same page via its alias
+```
+
+`bm man install` warns with a one-line `MANPATH` fix if the install root
+isn't searched by your `man`. Agents with shell access can use `man bm` as
+an offline quick reference; the full per-tool detail stays in the manual
+project's section-3 pages.
+
+## The verification discipline
+
+Two rules make the manual trustworthy:
+
+1. **Examples must have run.** An `EXAMPLES` (or `MCP USAGE` / `CLI
+   EQUIVALENT`) block contains only commands that actually executed against
+   the manual project. Destructive operations (`delete_note`, `move_note`,
+   destructive `edit_note`) run only against `playground/` notes — never
+   against pages. The `verified:` field records the version and which path
+   proved the page: `mcp` (live service), `cli` (dev checkout), or both.
+
+2. **The schema is the linter.** Validate the whole manual any time:
+
+   ```bash
+   bm tool schema-validate manpage --project manual
+   # → {"total_notes": 38, "valid_count": 38, "warning_count": 0, ...}
+   ```
+
+   `bm orphans --project manual` confirms every page is connected to the
+   graph, and `schema_diff`/`schema_infer` report drift between the schema
+   and how pages are actually written.
+
+Because verification exercises real tool calls against the live service,
+building the manual doubles as an end-to-end smoke test. The initial build
+found six bugs in one pass (#954–#959) — including the verification rule
+catching a test that asserted a bug as expected output (#958).
+
+## Adding or updating a page
+
+1. Run the commands you intend to document; keep the actual output.
+2. Write the page with `write_note`, passing frontmatter through the
+   `metadata` parameter (nested YAML in content frontmatter is unreliable on
+   some clients):
+
+   ```
+   write_note(title="my-tool(3)", directory="man3", project="manual",
+              note_type="manpage",
+              metadata={"section": 3, "name": "my-tool",
+                        "summary": "...", "generated": "hand",
+                        "tool": "my_tool", "verified": "<version> mcp"})
+   ```
+
+3. Link related pages in `SEE ALSO` with `see_also [[other-page(3)]]`.
+   Forward references to pages that don't exist yet are fine — they resolve
+   automatically when the target is written.
+4. Validate: `bm tool schema-validate manpage --project manual`.
+
+For mechanical updates to generated sections, prefer `edit_note` with
+`replace_section` / `insert_after_section` so curated content (EXAMPLES,
+GOTCHAS, SEE ALSO, observations) survives — that ownership split is what the
+`generated:` field declares.
+
+## Roadmap
+
+- **Registry generator** — section-3 SYNOPSIS/PARAMETERS generated from the
+  MCP tool registry (docstrings + pydantic schemas), section-1 from Typer
+  help; the hand-written corpus is the template spec. Regenerate-and-diff in
+  CI becomes the drift gate.
+- **`bm man <topic>`** — CLI sugar over `read_note` + metadata search.
+  (`bm man install` + a hand-written `bm.1` already ship — the first slice
+  of [#610](https://github.com/basicmachines-co/basic-memory/issues/610);
+  the generator will produce per-command pages from the same extraction.)
+- **Docs site** — the notes remain canonical for sections 5 and 7, code is
+  canonical for 1 and 3; both render to the hosted docs site.

integrations/hermes/__init__.py

@@ -38,7 +38,7 @@ from typing import Any, Callable
 from agent.memory_provider import MemoryProvider
 from tools.registry import tool_error
 
-__version__ = "0.22.0"
+__version__ = "0.22.1"
 
 logger = logging.getLogger("hermes.memory.basic-memory")
 

integrations/hermes/plugin.yaml

@@ -1,5 +1,5 @@
 name: basic-memory
-version: 0.22.0
+version: 0.22.1
 description: "Basic Memory — persistent knowledge graph backed by the basic-memory MCP server"
 pip_dependencies:
   - mcp

integrations/openclaw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basicmemory/openclaw-basic-memory",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

justfile

@@ -383,17 +383,31 @@ release version:
         echo "❌ Tag {{version}} already exists"
         exit 1
     fi
-    
+
+    # Changelog must already be on main (land it via a normal PR first)
+    if ! grep -q "^## {{version}} " CHANGELOG.md; then
+        echo "❌ CHANGELOG.md has no entry for {{version}}. Land one via PR first."
+        exit 1
+    fi
+
     # Run quality checks
     echo "🔍 Running lint  checks..."
     just lint
     just typecheck
-    
+
     # Update all package manifests to the one Basic Memory product version.
     echo "📝 Updating consolidated package versions..."
     just set-version "{{version}}"
 
-    # Commit version update
+    # Trigger: main's ruleset rejects direct pushes ("Changes must be made
+    # through a pull request").
+    # Why: the version bump must land on main before the tag is cut, so it
+    # rides a release PR that is rebase-merged (the repo disallows merge
+    # commits).
+    # Outcome: the bump commit gets a new SHA on main; the tag is created on
+    # that rebased commit, found by its commit subject.
+    COMMIT_SUBJECT="chore: update version to $VERSION_NUM for {{version}} release"
+    git checkout -b "release/{{version}}"
     git add \
         src/basic_memory/__init__.py \
         server.json \
@@ -404,23 +418,58 @@ release version:
         integrations/hermes/plugin.yaml \
         integrations/hermes/__init__.py \
         integrations/openclaw/package.json
-    git commit -s -m "chore: update version to $VERSION_NUM for {{version}} release"
-    
-    # Create and push tag
-    echo "🏷️  Creating tag {{version}}..."
-    git tag "{{version}}"
-    
-    echo "📤 Pushing to GitHub..."
-    git push origin main
+    git commit -s -m "$COMMIT_SUBJECT"
+
+    echo "📤 Opening release PR..."
+    git push -u origin "release/{{version}}"
+    gh pr create --title "chore(core): release {{version}}" \
+        --body "Version bump for {{version}}. See CHANGELOG.md for release notes."
+
+    # Trigger: the PR may not be mergeable synchronously (merge gates,
+    # required checks added later, or GitHub still computing mergeability).
+    # Why: the tag must point at the bump commit on main, so the recipe
+    # cannot tag until the merge has actually landed.
+    # Outcome: try a direct rebase-merge, fall back to queueing auto-merge,
+    # then poll main for the rebased bump commit before tagging.
+    if ! gh pr merge "release/{{version}}" --rebase --delete-branch; then
+        echo "⚠️  Direct merge did not complete (merge gates pending?). Queueing auto-merge..."
+        gh pr merge "release/{{version}}" --rebase --delete-branch --auto
+    fi
+
+    echo "⏳ Waiting for the bump commit to land on main..."
+    TAG_COMMIT=""
+    for _ in $(seq 1 60); do
+        git fetch origin main --quiet
+        TAG_COMMIT=$(git log FETCH_HEAD --fixed-strings --grep "$COMMIT_SUBJECT" --format='%H' -1)
+        [[ -n "$TAG_COMMIT" ]] && break
+        sleep 5
+    done
+    if [[ -z "$TAG_COMMIT" ]]; then
+        echo "❌ Bump commit not on main after 5 minutes (merge still pending?)."
+        echo "   Once the release PR merges, finish the release manually:"
+        echo "   git fetch origin main"
+        echo "   git tag {{version}} \$(git log FETCH_HEAD --fixed-strings --grep \"$COMMIT_SUBJECT\" --format='%H' -1)"
+        echo "   git push origin {{version}}"
+        exit 1
+    fi
+
+    git checkout main
+    git pull --ff-only origin main
+    git branch -D "release/{{version}}" 2>/dev/null || true
+
+    echo "🏷️  Creating tag {{version}} at $TAG_COMMIT..."
+    git tag "{{version}}" "$TAG_COMMIT"
     git push origin "{{version}}"
-    
+
     echo "✅ Release {{version}} created successfully!"
     echo "📦 GitHub Actions will build and publish to PyPI"
     echo "🔗 Monitor at: https://github.com/basicmachines-co/basic-memory/actions"
     echo ""
     echo "📝 REMINDER: Post-release tasks:"
-    echo "   1. docs.basicmemory.com - Add release notes to src/pages/latest-releases.mdx"
-    echo "   2. basicmachines.co - Update version in src/components/sections/hero.tsx"
+    echo "   1. docs.basicmemory.com - Add a What's New page under content/2.whats-new/"
+    echo "      and bump the badge in content/index.md (see that repo's CLAUDE.md)"
+    echo "   2. basicmemory.com - No version number in the site UI; for a significant"
+    echo "      release optionally add a post under src/content/blog/. Skip for patches."
     echo "   3. MCP Registry - Run: mcp-publisher publish"
     echo "   See: .claude/commands/release/release.md for detailed instructions"
 
@@ -467,7 +516,15 @@ beta version:
     echo "📝 Updating consolidated package versions..."
     just set-version "{{version}}"
 
-    # Commit version update
+    # Trigger: main's ruleset rejects direct pushes ("Changes must be made
+    # through a pull request").
+    # Why: the version bump must land on main before the tag is cut, so it
+    # rides a release PR that is rebase-merged (the repo disallows merge
+    # commits).
+    # Outcome: the bump commit gets a new SHA on main; the tag is created on
+    # that rebased commit, found by its commit subject.
+    COMMIT_SUBJECT="chore: update version to $VERSION_NUM for {{version}} beta release"
+    git checkout -b "release/{{version}}"
     git add \
         src/basic_memory/__init__.py \
         server.json \
@@ -478,24 +535,59 @@ beta version:
         integrations/hermes/plugin.yaml \
         integrations/hermes/__init__.py \
         integrations/openclaw/package.json
-    git commit -s -m "chore: update version to $VERSION_NUM for {{version}} beta release"
-    
-    # Create and push tag
-    echo "🏷️  Creating tag {{version}}..."
-    git tag "{{version}}"
-    
-    echo "📤 Pushing to GitHub..."
-    git push origin main
+    git commit -s -m "$COMMIT_SUBJECT"
+
+    echo "📤 Opening release PR..."
+    git push -u origin "release/{{version}}"
+    gh pr create --title "chore(core): release {{version}}" \
+        --body "Version bump for {{version}} beta."
+
+    # Trigger: the PR may not be mergeable synchronously (merge gates,
+    # required checks added later, or GitHub still computing mergeability).
+    # Why: the tag must point at the bump commit on main, so the recipe
+    # cannot tag until the merge has actually landed.
+    # Outcome: try a direct rebase-merge, fall back to queueing auto-merge,
+    # then poll main for the rebased bump commit before tagging.
+    if ! gh pr merge "release/{{version}}" --rebase --delete-branch; then
+        echo "⚠️  Direct merge did not complete (merge gates pending?). Queueing auto-merge..."
+        gh pr merge "release/{{version}}" --rebase --delete-branch --auto
+    fi
+
+    echo "⏳ Waiting for the bump commit to land on main..."
+    TAG_COMMIT=""
+    for _ in $(seq 1 60); do
+        git fetch origin main --quiet
+        TAG_COMMIT=$(git log FETCH_HEAD --fixed-strings --grep "$COMMIT_SUBJECT" --format='%H' -1)
+        [[ -n "$TAG_COMMIT" ]] && break
+        sleep 5
+    done
+    if [[ -z "$TAG_COMMIT" ]]; then
+        echo "❌ Bump commit not on main after 5 minutes (merge still pending?)."
+        echo "   Once the release PR merges, finish the release manually:"
+        echo "   git fetch origin main"
+        echo "   git tag {{version}} \$(git log FETCH_HEAD --fixed-strings --grep \"$COMMIT_SUBJECT\" --format='%H' -1)"
+        echo "   git push origin {{version}}"
+        exit 1
+    fi
+
+    git checkout main
+    git pull --ff-only origin main
+    git branch -D "release/{{version}}" 2>/dev/null || true
+
+    echo "🏷️  Creating tag {{version}} at $TAG_COMMIT..."
+    git tag "{{version}}" "$TAG_COMMIT"
     git push origin "{{version}}"
-    
+
     echo "✅ Beta release {{version}} created successfully!"
     echo "📦 GitHub Actions will build and publish to PyPI as pre-release"
     echo "🔗 Monitor at: https://github.com/basicmachines-co/basic-memory/actions"
     echo "📥 Install with: uv tool install basic-memory --pre"
     echo ""
     echo "📝 REMINDER: For stable releases, update documentation sites:"
-    echo "   1. docs.basicmemory.com - Add release notes to src/pages/latest-releases.mdx"
-    echo "   2. basicmachines.co - Update version in src/components/sections/hero.tsx"
+    echo "   1. docs.basicmemory.com - Add a What's New page under content/2.whats-new/"
+    echo "      and bump the badge in content/index.md (see that repo's CLAUDE.md)"
+    echo "   2. basicmemory.com - No version number in the site UI; for a significant"
+    echo "      release optionally add a post under src/content/blog/. Skip for patches."
     echo "   See: .claude/commands/release/release.md for detailed instructions"
 
 # List all available recipes

plugins/claude-code/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official plugins from Basic Machines for knowledge management and AI-assisted development",
-    "version": "0.22.0"
+    "version": "0.22.1"
   },
   "plugins": [
     {
       "name": "basic-memory",
       "source": "./",
       "description": "The bridge between Claude's working memory and Basic Memory's durable knowledge graph \u2014 session briefings, pre-compaction checkpoints, and capture reflexes",
-      "version": "0.22.0",
+      "version": "0.22.1",
       "author": {
         "name": "Basic Machines"
       },

plugins/claude-code/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "basic-memory",
   "description": "The bridge between Claude's working memory and Basic Memory's durable knowledge graph \u2014 session briefings, pre-compaction checkpoints, and capture reflexes",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "author": {
     "name": "Basic Machines"
   },

plugins/claude-code/schemas/manpage.md

@@ -0,0 +1,55 @@
+---
+title: Manpage
+type: schema
+entity: Manpage
+version: 1
+schema:
+  gotcha?(array): string, sharp edges and surprising behavior learned from live verification
+  example?(array): string, worked examples beyond the generated synopsis
+  pattern?(array): string, recommended idioms and usage patterns
+  bug?(array): string, known defects affecting this surface, with issue links
+  see_also?(array): Entity, related manual pages — the SEE ALSO graph
+settings:
+  validation: warn
+  frontmatter:
+    section(enum, Unix manual section number): [1, 3, 5, 7, 8]
+    name: string, page name without section suffix (e.g. write-note)
+    summary: string, one-line NAME description
+    generated?(enum, who owns the mechanical sections): [registry, typer, hand]
+    tool?: string, MCP tool this page documents (section 3 pages)
+    command?: string, CLI command this page documents (section 1 pages)
+    verified?: string, version and path that verified this page (e.g. 0.21.6 mcp+cli)
+    since?: string, version this surface first appeared
+---
+
+# Manpage
+
+A **ManpageNote** is one page of a Unix-style manual implemented as Basic
+Memory notes (issue #952): commands in section 1, MCP tools in section 3,
+file formats in section 5, concepts in section 7, admin in section 8. The
+manual becomes a knowledge graph — `SEE ALSO` entries are typed relations,
+and pages are found by structured recall:
+`search_notes(metadata_filters={"type": "manpage", "section": 3})`.
+
+This schema is an opt-in seed for documentation projects; the canonical
+manual lives in the Basic Memory team workspace `manual` project.
+
+## What makes a good ManpageNote
+
+- **NAME / SYNOPSIS / DESCRIPTION** — classic man-page structure, with
+  PARAMETERS, MCP USAGE, CLI EQUIVALENT, EXAMPLES, GOTCHAS, SEE ALSO where
+  applicable.
+- **Verified examples** — EXAMPLES contain only commands that actually ran;
+  the `verified` field records the version and path (mcp, cli, or both).
+- **generated** — declares regeneration ownership: `registry` (from the MCP
+  tool registry) and `typer` (from CLI help) pages get mechanical sections
+  rewritten; curated sections (EXAMPLES, GOTCHAS, SEE ALSO, observations)
+  are never overwritten.
+- **gotcha / bug observations** — field knowledge accumulates on pages
+  without being clobbered by regeneration; bugs link their tracking issues.
+
+## Frontmatter
+
+`type: manpage` plus `section` makes the manual queryable like `man -k`:
+by section, by `tool`, by `command`, or by missing/stale `verified` stamps.
+Validation is `warn`, never blocking.

plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "A Codex-native bridge to Basic Memory for durable engineering context, decisions, and resumable checkpoints.",
   "author": {
     "name": "Basic Machines",

server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/basicmachines-co/basic-memory.git",
     "source": "github"
   },
-  "version": "0.22.0",
+  "version": "0.22.1",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "basic-memory",
-      "version": "0.22.0",
+      "version": "0.22.1",
       "runtimeHint": "uvx",
       "runtimeArguments": [
         {

src/basic_memory/__init__.py

@@ -1,4 +1,7 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
 
 # Package version - updated by release automation
-__version__ = "0.22.0"
+__version__ = "0.22.1"
+
+# API version for FastAPI - independent of package version
+__api_version__ = "v0"

src/basic_memory/api/v2/routers/project_router.py

@@ -193,7 +193,7 @@ async def add_project(
         return ProjectStatusResponse(  # pyright: ignore [reportCallIssue]
             message=f"Project '{new_project.name}' added successfully",
             status="success",
-            default=project_data.set_default,
+            default=new_project.is_default or False,
             new_project=ProjectItem(
                 id=new_project.id,
                 external_id=new_project.external_id,
@@ -320,7 +320,20 @@ async def resolve_project_identifier(
     )
 
     if not project:
-        raise HTTPException(status_code=404, detail=f"Project not found: '{data.identifier}'")
+        detail = f"Project not found: '{data.identifier}'"
+        # Trigger: resolution missed and the projects table is empty.
+        # Why: a fresh install bootstraps config.json's default project before any
+        #      reconciliation has created database rows (the one-shot CLI never runs
+        #      the server lifespan), so the first read fails on the configured
+        #      default and the bare not-found message reads as a broken install
+        #      rather than a missing first-run step (#974 follow-up).
+        # Outcome: the error names the setup command instead.
+        if not await project_repository.find_all(limit=1, use_load_options=False):
+            detail = (
+                f"{detail}. No projects are set up yet — run "
+                "'basic-memory project add <name> <path>' to create one."
+            )
+        raise HTTPException(status_code=404, detail=detail)
 
     return ProjectResolveResponse(
         external_id=project.external_id,
@@ -559,12 +572,10 @@ async def set_default_project_by_id(
     logger.info(f"API v2 request: set_default_project_by_id for project_id={project_id}")
 
     try:
-        # Get the old default project from database
+        # Get the old default project from database. It may be absent during
+        # bootstrap/recovery (no default row yet); that is a valid state, not an
+        # error, so we only echo it back when one exists.
         default_project = await project_repository.get_default_project()
-        if not default_project:
-            raise HTTPException(  # pragma: no cover
-                status_code=404, detail="No default project is currently set"
-            )
 
         # Get the new default project by external_id
         new_default_project = await project_repository.get_by_external_id(project_id)
@@ -576,17 +587,27 @@ async def set_default_project_by_id(
         # Set as default using project name (service layer still uses names internally)
         await project_service.set_default_project(new_default_project.name)
 
-        return ProjectStatusResponse(
-            message=f"Project '{new_default_project.name}' set as default successfully",
-            status="success",
-            default=True,
-            old_project=ProjectItem(
+        # Trigger: a previous default existed
+        # Why: ProjectStatusResponse.old_project is Optional; the no-default
+        #   bootstrap case must succeed with old_project=None
+        # Outcome: response echoes the prior default only when there was one
+        old_project = (
+            ProjectItem(
                 id=default_project.id,
                 external_id=default_project.external_id,
                 name=default_project.name,
                 path=default_project.path,
                 is_default=False,
-            ),
+            )
+            if default_project
+            else None
+        )
+
+        return ProjectStatusResponse(
+            message=f"Project '{new_default_project.name}' set as default successfully",
+            status="success",
+            default=True,
+            old_project=old_project,
             new_project=ProjectItem(
                 id=new_default_project.id,
                 external_id=new_default_project.external_id,

src/basic_memory/api/v2/utils.py

@@ -147,6 +147,7 @@ async def to_graph_context(
                         from_entity_id=item.from_id,
                         from_entity_external_id=from_ext_id,
                         to_entity=to_title,
+                        to_name=item.to_name,
                         to_entity_id=item.to_id,
                         to_entity_external_id=to_ext_id,
                         created_at=item.created_at,

src/basic_memory/cli/app.py

@@ -83,8 +83,11 @@ def app_callback(
     # Skip for 'mcp' command - it has its own lifespan that handles initialization
     # Skip for API-using commands (status, sync, etc.) - they handle initialization via deps.py
     # Skip for 'reset' command - it manages its own database lifecycle
+    # Skip for 'man' - it only copies packaged files; a broken local database
+    # must not block installing the offline docs
     skip_init_commands = {
         "doctor",
+        "man",
         "mcp",
         "status",
         "sync",

src/basic_memory/cli/auto_update.py

@@ -168,6 +168,20 @@ def _manual_update_hint(source: InstallSource) -> str:
     )
 
 
+def _preload_lazy_console_modules() -> None:
+    """Import modules the post-upgrade output path defers until print time.
+
+    Trigger: an in-place upgrade is about to replace this installation on disk.
+    Why: rich and typer defer some imports until print/excepthook time; once
+    `brew upgrade` / `uv tool upgrade` removes the running version's files,
+    those imports raise ModuleNotFoundError and the final status message
+    crashes the exiting process.
+    Outcome: import the deferred modules now, while the files still exist.
+    """
+    import rich._emoji_codes  # noqa: F401
+    import typer.rich_utils  # noqa: F401
+
+
 def _save_last_checked_timestamp(config_manager: ConfigManager, checked_at: datetime) -> None:
     """Persist the timestamp for the most recent attempted update check."""
     config = config_manager.load_config()
@@ -288,6 +302,7 @@ def run_auto_update(
             else BREW_UPGRADE_TIMEOUT_SECONDS
         )
 
+        _preload_lazy_console_modules()
         install_result = _run_subprocess(
             command,
             timeout_seconds=timeout,

src/basic_memory/cli/commands/__init__.py

@@ -4,6 +4,7 @@ from . import ci, status, db, doctor, import_memory_json, mcp, import_claude_con
 from . import (
     import_claude_projects,
     import_chatgpt,
+    man,
     tool,
     project,
     format,
@@ -29,4 +30,5 @@ __all__ = [
     "schema",
     "update",
     "workspace",
+    "man",
 ]

src/basic_memory/cli/commands/ci.py

@@ -34,8 +34,10 @@ from basic_memory.ci.project_updates import (
 from basic_memory.cli.app import app
 from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.cli.commands.routing import force_routing, validate_routing_flags
-from basic_memory.mcp.tools import search_notes as mcp_search_notes
-from basic_memory.mcp.tools import write_note as mcp_write_note
+
+# MCP tool functions are imported inside the async helpers below: importing
+# basic_memory.mcp.tools loads the entire tool stack (fastmcp, mcp SDK,
+# SQLAlchemy), which would slow every CLI invocation, including --help (#886).
 
 
 console = Console()
@@ -252,6 +254,10 @@ async def seed_project_update_schemas(
     refresh: bool = False,
 ) -> list[str]:
     """Seed Auto BM schema notes without overwriting customized schemas."""
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import search_notes as mcp_search_notes
+    from basic_memory.mcp.tools import write_note as mcp_write_note
+
     seeded: list[str] = []
     routed_project = _routed_project(project=project, project_id=project_id, workspace=workspace)
     for spec in schema_seed_specs():
@@ -295,6 +301,10 @@ async def publish_project_update_note(
     note: ProjectUpdateNote,
 ) -> dict[str, Any]:
     """Search by idempotency key and then upsert the deterministic note path."""
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import search_notes as mcp_search_notes
+    from basic_memory.mcp.tools import write_note as mcp_write_note
+
     routed_project = _routed_project(
         project=config.project,
         project_id=config.project_id,

src/basic_memory/cli/commands/command_utils.py

@@ -3,12 +3,10 @@
 import asyncio
 from typing import Optional, TypeVar, Coroutine, Any
 
-from mcp.server.fastmcp.exceptions import ToolError
 import typer
 
 from rich.console import Console
 
-from basic_memory import db
 from basic_memory.config import ConfigManager
 from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.clients import ProjectClient
@@ -31,6 +29,9 @@ def run_with_cleanup(coro: Coroutine[Any, Any, T]) -> T:
     Returns:
         The result of the coroutine
     """
+    # Deferred: basic_memory.db pulls SQLAlchemy + Alembic, which must not load
+    # at CLI import time — only when a command actually runs (#886).
+    from basic_memory import db
 
     async def _with_cleanup() -> T:
         try:
@@ -53,6 +54,8 @@ async def run_sync(
         force_full: If True, force a full scan bypassing watermark optimization
         run_in_background: If True, return immediately; if False, wait for completion
     """
+    # Deferred: ToolError lives in the mcp SDK, which must not load at CLI startup (#886).
+    from mcp.server.fastmcp.exceptions import ToolError
 
     # Resolve default project so get_client() can route per-project
     project = project or ConfigManager().default_project
@@ -86,6 +89,9 @@ async def run_sync(
 
 async def get_project_info(project: str):
     """Get project information via API endpoint."""
+    # Deferred: ToolError lives in the mcp SDK, which must not load at CLI startup (#886).
+    from mcp.server.fastmcp.exceptions import ToolError
+
     try:
         async with get_client(project_name=project) as client:
             project_item = await get_active_project(client, project, None)

src/basic_memory/cli/commands/db.py

@@ -1,24 +1,27 @@
 """Database management commands."""
 
+# PEP 563 lazy annotations let signatures reference IndexProgress without importing
+# the indexing stack at module load; reset/reindex import their heavy database and
+# sync dependencies at call time so CLI startup stays fast (#886).
+from __future__ import annotations
+
 import os
 from dataclasses import dataclass
 from pathlib import Path, PurePosixPath, PureWindowsPath
+from typing import TYPE_CHECKING
 
 import psutil
 import typer
 from loguru import logger
 from rich.console import Console
 from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn, TaskProgressColumn
-from sqlalchemy.exc import OperationalError
 
-from basic_memory import db
 from basic_memory.cli.app import app
 from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.config import ConfigManager, ProjectMode
-from basic_memory.indexing import IndexProgress
-from basic_memory.repository import ProjectRepository
-from basic_memory.services.initialization import reconcile_projects_with_config
-from basic_memory.sync.sync_service import get_sync_service
+
+if TYPE_CHECKING:
+    from basic_memory.indexing import IndexProgress
 
 console = Console()
 
@@ -159,6 +162,13 @@ async def _reindex_projects(app_config):
     This ensures all database operations use the same event loop,
     and proper cleanup happens when the function completes.
     """
+    # Deferred: SQLAlchemy, repositories, and the sync stack load only when a
+    # reindex actually runs, not on every CLI start (#886).
+    from basic_memory import db
+    from basic_memory.repository import ProjectRepository
+    from basic_memory.services.initialization import reconcile_projects_with_config
+    from basic_memory.sync.sync_service import get_sync_service
+
     try:
         await reconcile_projects_with_config(app_config)
 
@@ -197,6 +207,12 @@ def reset(
     ),
 ):  # pragma: no cover
     """Reset database (drop all tables and recreate)."""
+    # Deferred: SQLAlchemy and the db module load only when a reset actually
+    # runs, not on every CLI start (#886).
+    from sqlalchemy.exc import OperationalError
+
+    from basic_memory import db
+
     console.print(
         "[yellow]Note:[/yellow] This only deletes the index database. "
         "Your markdown note files will not be affected.\n"
@@ -320,10 +336,15 @@ async def _reindex(
     project: str | None,
 ):
     """Run reindex operations."""
-    from basic_memory.repository import EntityRepository
+    # Deferred: SQLAlchemy, repositories, and the sync stack load only when a
+    # reindex actually runs, not on every CLI start (#886).
+    from basic_memory import db
+    from basic_memory.repository import EntityRepository, ProjectRepository
     from basic_memory.repository.search_repository import create_search_repository
+    from basic_memory.services.initialization import reconcile_projects_with_config
     from basic_memory.services.search_service import SearchService
     from basic_memory.services.file_service import FileService
+    from basic_memory.sync.sync_service import get_sync_service
     from basic_memory.markdown.markdown_processor import MarkdownProcessor
     from basic_memory.markdown.entity_parser import EntityParser
 

src/basic_memory/cli/commands/doctor.py

@@ -7,16 +7,12 @@ import uuid
 from pathlib import Path
 
 from loguru import logger
-from mcp.server.fastmcp.exceptions import ToolError
 from rich.console import Console
 import typer
 
 from basic_memory.cli.app import app
 from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.cli.commands.routing import force_routing, validate_routing_flags
-from basic_memory.markdown.entity_parser import EntityParser
-from basic_memory.markdown.markdown_processor import MarkdownProcessor
-from basic_memory.markdown.schemas import EntityFrontmatter, EntityMarkdown
 from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.clients import KnowledgeClient, ProjectClient, SearchClient
 from basic_memory.schemas.base import Entity
@@ -29,6 +25,12 @@ console = Console()
 
 async def run_doctor() -> None:
     """Run local consistency checks for file <-> database flows."""
+    # Deferred: the markdown parsing stack is only needed while the checks run,
+    # and importing it at module level slows every CLI invocation (#886).
+    from basic_memory.markdown.entity_parser import EntityParser
+    from basic_memory.markdown.markdown_processor import MarkdownProcessor
+    from basic_memory.markdown.schemas import EntityFrontmatter, EntityMarkdown
+
     console.print("[blue]Running Basic Memory doctor checks...[/blue]")
 
     project_name = f"doctor-{uuid.uuid4().hex[:8]}"
@@ -140,6 +142,9 @@ def doctor(
     cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
 ) -> None:
     """Run local consistency checks to verify file/database sync."""
+    # Deferred: ToolError lives in the mcp SDK, which must not load at CLI startup (#886).
+    from mcp.server.fastmcp.exceptions import ToolError
+
     try:
         validate_routing_flags(local, cloud)
         # Doctor runs local filesystem checks — always default to local routing

src/basic_memory/cli/commands/import_chatgpt.py

@@ -1,25 +1,34 @@
 """Import command for ChatGPT conversations."""
 
+# PEP 563 lazy annotations keep heavy importer types out of module import (#886).
+from __future__ import annotations
+
 import json
 from pathlib import Path
-from typing import Annotated, Tuple
+from typing import TYPE_CHECKING, Annotated, Tuple
 
 import typer
 from basic_memory.cli.app import import_app
 from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.config import ConfigManager, get_project_config
-from basic_memory.importers import ChatGPTImporter
-from basic_memory.markdown import EntityParser, MarkdownProcessor
-from basic_memory.services.file_service import FileService
 from loguru import logger
 from rich.console import Console
 from rich.panel import Panel
 
+if TYPE_CHECKING:
+    from basic_memory.markdown import MarkdownProcessor
+    from basic_memory.services.file_service import FileService
+
 console = Console()
 
 
 async def get_importer_dependencies() -> Tuple[MarkdownProcessor, FileService]:
     """Get MarkdownProcessor and FileService instances for importers."""
+    # Deferred: the markdown/file-service stack pulls SQLAlchemy and must load
+    # only when an import actually runs, not on every CLI start (#886).
+    from basic_memory.markdown import EntityParser, MarkdownProcessor
+    from basic_memory.services.file_service import FileService
+
     config = get_project_config()
     app_config = ConfigManager().config
     entity_parser = EntityParser(config.home)
@@ -60,6 +69,9 @@ def import_chatgpt(
         console.print(f"\nImporting chats from {conversations_json}...writing to {base_path}")
 
         # Create importer and run import
+        # Deferred: importer stack loads at import-command run time only (#886).
+        from basic_memory.importers import ChatGPTImporter
+
         importer = ChatGPTImporter(
             config.home, markdown_processor, file_service, project_name=config.name
         )

src/basic_memory/cli/commands/import_claude_conversations.py

@@ -1,25 +1,34 @@
 """Import command for basic-memory CLI to import chat data from conversations2.json format."""
 
+# PEP 563 lazy annotations keep heavy importer types out of module import (#886).
+from __future__ import annotations
+
 import json
 from pathlib import Path
-from typing import Annotated, Tuple
+from typing import TYPE_CHECKING, Annotated, Tuple
 
 import typer
 from basic_memory.cli.app import claude_app
 from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.config import ConfigManager, get_project_config
-from basic_memory.importers.claude_conversations_importer import ClaudeConversationsImporter
-from basic_memory.markdown import EntityParser, MarkdownProcessor
-from basic_memory.services.file_service import FileService
 from loguru import logger
 from rich.console import Console
 from rich.panel import Panel
 
+if TYPE_CHECKING:
+    from basic_memory.markdown import MarkdownProcessor
+    from basic_memory.services.file_service import FileService
+
 console = Console()
 
 
 async def get_importer_dependencies() -> Tuple[MarkdownProcessor, FileService]:
     """Get MarkdownProcessor and FileService instances for importers."""
+    # Deferred: the markdown/file-service stack pulls SQLAlchemy and must load
+    # only when an import actually runs, not on every CLI start (#886).
+    from basic_memory.markdown import EntityParser, MarkdownProcessor
+    from basic_memory.services.file_service import FileService
+
     config = get_project_config()
     app_config = ConfigManager().config
     entity_parser = EntityParser(config.home)
@@ -57,6 +66,9 @@ def import_claude(
         markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
+        # Deferred: importer stack loads at import-command run time only (#886).
+        from basic_memory.importers.claude_conversations_importer import ClaudeConversationsImporter
+
         importer = ClaudeConversationsImporter(
             config.home, markdown_processor, file_service, project_name=config.name
         )

src/basic_memory/cli/commands/import_claude_projects.py

@@ -1,25 +1,34 @@
 """Import command for basic-memory CLI to import project data from Claude.ai."""
 
+# PEP 563 lazy annotations keep heavy importer types out of module import (#886).
+from __future__ import annotations
+
 import json
 from pathlib import Path
-from typing import Annotated, Tuple
+from typing import TYPE_CHECKING, Annotated, Tuple
 
 import typer
 from basic_memory.cli.app import claude_app
 from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.config import ConfigManager, get_project_config
-from basic_memory.importers.claude_projects_importer import ClaudeProjectsImporter
-from basic_memory.markdown import EntityParser, MarkdownProcessor
-from basic_memory.services.file_service import FileService
 from loguru import logger
 from rich.console import Console
 from rich.panel import Panel
 
+if TYPE_CHECKING:
+    from basic_memory.markdown import MarkdownProcessor
+    from basic_memory.services.file_service import FileService
+
 console = Console()
 
 
 async def get_importer_dependencies() -> Tuple[MarkdownProcessor, FileService]:
     """Get MarkdownProcessor and FileService instances for importers."""
+    # Deferred: the markdown/file-service stack pulls SQLAlchemy and must load
+    # only when an import actually runs, not on every CLI start (#886).
+    from basic_memory.markdown import EntityParser, MarkdownProcessor
+    from basic_memory.services.file_service import FileService
+
     config = get_project_config()
     app_config = ConfigManager().config
     entity_parser = EntityParser(config.home)
@@ -56,6 +65,9 @@ def import_projects(
         markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
+        # Deferred: importer stack loads at import-command run time only (#886).
+        from basic_memory.importers.claude_projects_importer import ClaudeProjectsImporter
+
         importer = ClaudeProjectsImporter(
             config.home, markdown_processor, file_service, project_name=config.name
         )

src/basic_memory/cli/commands/import_memory_json.py

@@ -1,25 +1,34 @@
 """Import command for basic-memory CLI to import from JSON memory format."""
 
+# PEP 563 lazy annotations keep heavy importer types out of module import (#886).
+from __future__ import annotations
+
 import json
 from pathlib import Path
-from typing import Annotated, Tuple
+from typing import TYPE_CHECKING, Annotated, Tuple
 
 import typer
 from basic_memory.cli.app import import_app
 from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.config import ConfigManager, get_project_config
-from basic_memory.importers.memory_json_importer import MemoryJsonImporter
-from basic_memory.markdown import EntityParser, MarkdownProcessor
-from basic_memory.services.file_service import FileService
 from loguru import logger
 from rich.console import Console
 from rich.panel import Panel
 
+if TYPE_CHECKING:
+    from basic_memory.markdown import MarkdownProcessor
+    from basic_memory.services.file_service import FileService
+
 console = Console()
 
 
 async def get_importer_dependencies() -> Tuple[MarkdownProcessor, FileService]:
     """Get MarkdownProcessor and FileService instances for importers."""
+    # Deferred: the markdown/file-service stack pulls SQLAlchemy and must load
+    # only when an import actually runs, not on every CLI start (#886).
+    from basic_memory.markdown import EntityParser, MarkdownProcessor
+    from basic_memory.services.file_service import FileService
+
     config = get_project_config()
     app_config = ConfigManager().config
     entity_parser = EntityParser(config.home)
@@ -55,6 +64,9 @@ def memory_json(
         markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
+        # Deferred: importer stack loads at import-command run time only (#886).
+        from basic_memory.importers.memory_json_importer import MemoryJsonImporter
+
         importer = MemoryJsonImporter(
             config.home, markdown_processor, file_service, project_name=config.name
         )

src/basic_memory/cli/commands/man.py

@@ -0,0 +1,76 @@
+"""Install the bundled man pages so `man bm` works."""
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+
+from basic_memory.cli.app import app
+
+console = Console()
+
+man_app = typer.Typer(help="Manage the bm man pages.")
+app.add_typer(man_app, name="man")
+
+# Bundled groff sources ship inside the package (src/basic_memory/man).
+_MAN_SOURCE_DIR = Path(__file__).parent.parent.parent / "man"
+
+
+def _default_man_root() -> Path:
+    # Why ~/.local/share/man: manpath(1) derives man directories from PATH
+    # entries on both man-db (Linux) and BSD man (macOS), so ~/.local/bin on
+    # PATH — the pipx/uv tool layout — makes this root searchable without any
+    # MANPATH configuration.
+    return Path.home() / ".local" / "share" / "man"
+
+
+def _man_root_on_manpath(man_root: Path) -> Optional[bool]:
+    """Best-effort check whether man(1) will search man_root; None if unknown."""
+    try:
+        result = subprocess.run(["manpath"], capture_output=True, text=True, timeout=5)
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    paths = [entry.rstrip("/") for entry in result.stdout.strip().split(":") if entry]
+    return str(man_root).rstrip("/") in paths
+
+
+@man_app.command()
+def install(
+    directory: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--dir",
+            help="Man root to install into (default: ~/.local/share/man)",
+        ),
+    ] = None,
+) -> None:
+    """Install the bm man pages, then try `man bm`."""
+    man_root = (directory or _default_man_root()).expanduser()
+    man1 = man_root / "man1"
+    man1.mkdir(parents=True, exist_ok=True)
+
+    pages = sorted(_MAN_SOURCE_DIR.glob("*.1"))
+    if not pages:  # pragma: no cover - broken packaging, not a runtime state
+        console.print("[red]No bundled man pages found — broken installation[/red]")
+        raise typer.Exit(1)
+
+    for page in pages:
+        shutil.copyfile(page, man1 / page.name)
+        console.print(f"installed {man1 / page.name}")
+
+    # Trigger: the chosen root is provably absent from manpath output.
+    # Why: a silent install into an unsearched directory looks like success
+    #   but `man bm` still fails; say so and hand over the one-line fix.
+    # Outcome: actionable hint; unknown (None) stays quiet to avoid false alarms.
+    if _man_root_on_manpath(man_root) is False:
+        console.print(
+            f"\n[yellow]{man_root} is not on your manpath.[/yellow] Add it with:\n"
+            f'  export MANPATH="{man_root}:$MANPATH"'
+        )
+
+    console.print("\nTry: [bold]man bm[/bold]")

src/basic_memory/cli/commands/orphans.py

@@ -5,7 +5,6 @@ from typing import Annotated, Optional
 
 import typer
 from loguru import logger
-from mcp.server.fastmcp.exceptions import ToolError
 from rich.console import Console
 from rich.table import Table
 
@@ -50,6 +49,9 @@ def orphans(
     """
     from basic_memory.cli.commands.command_utils import run_with_cleanup
 
+    # Deferred: ToolError lives in the mcp SDK, which must not load at CLI startup (#886).
+    from mcp.server.fastmcp.exceptions import ToolError
+
     try:
         validate_routing_flags(local, cloud)
         with force_routing(local=local, cloud=cloud):

src/basic_memory/cli/commands/schema.py

@@ -20,9 +20,10 @@ from basic_memory.cli.app import app
 from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.cli.commands.routing import force_routing, validate_routing_flags
 from basic_memory.config import ConfigManager
-from basic_memory.mcp.tools import schema_diff as mcp_schema_diff
-from basic_memory.mcp.tools import schema_infer as mcp_schema_infer
-from basic_memory.mcp.tools import schema_validate as mcp_schema_validate
+
+# MCP tool functions are imported inside each command: importing
+# basic_memory.mcp.tools loads the entire tool stack (fastmcp, mcp SDK,
+# SQLAlchemy), which would slow every CLI invocation, including --help (#886).
 
 console = Console()
 
@@ -189,6 +190,9 @@ def validate(
     Use --local to force local routing when cloud mode is enabled.
     Use --cloud to force cloud routing when cloud mode is disabled.
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import schema_validate as mcp_schema_validate
+
     try:
         validate_routing_flags(local, cloud)
         project_name = _resolve_project_name(project)
@@ -272,6 +276,9 @@ def infer(
     Use --local to force local routing when cloud mode is enabled.
     Use --cloud to force cloud routing when cloud mode is disabled.
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import schema_infer as mcp_schema_infer
+
     try:
         validate_routing_flags(local, cloud)
         project_name = _resolve_project_name(project)
@@ -352,6 +359,9 @@ def diff(
     Use --local to force local routing when cloud mode is enabled.
     Use --cloud to force cloud routing when cloud mode is disabled.
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import schema_diff as mcp_schema_diff
+
     try:
         validate_routing_flags(local, cloud)
         project_name = _resolve_project_name(project)

src/basic_memory/cli/commands/status.py

@@ -5,7 +5,6 @@ import json
 import time
 from typing import Annotated, Dict, Optional, Set
 
-from mcp.server.fastmcp.exceptions import ToolError
 import typer
 from loguru import logger
 from rich.console import Console
@@ -190,9 +189,16 @@ async def run_status(
             if sync_report.total == 0:
                 return project_item.name, sync_report
             if time.monotonic() >= deadline:
+                # Why the hint: indexing is done by the sync coordinator, which
+                # only runs inside a live server (bm mcp / hosted API). In a
+                # CLI-only session nothing will ever drain the pending count,
+                # so this wait cannot succeed — point at the command that
+                # actually indexes (#959).
                 raise StatusTimeout(
                     f"Timed out after {timeout:g}s waiting for '{project_item.name}' "
-                    f"to finish indexing ({sync_report.total} pending change(s) remaining)."
+                    f"to finish indexing ({sync_report.total} pending change(s) remaining). "
+                    f"If no Basic Memory server is running, pending changes are never "
+                    f"indexed — run 'bm reindex --project {project_item.name}' instead."
                 )
             await asyncio.sleep(poll_interval)
 
@@ -224,6 +230,9 @@ def status(
     """
     from basic_memory.cli.commands.command_utils import run_with_cleanup
 
+    # Deferred: ToolError lives in the mcp SDK, which must not load at CLI startup (#886).
+    from mcp.server.fastmcp.exceptions import ToolError
+
     # Trigger: --wait with a negative --timeout
     # Why: a negative deadline times out on the very first poll, producing a confusing
     #      "Timed out after -5s" message instead of flagging the bad input. Raised

src/basic_memory/cli/commands/tool.py

@@ -14,18 +14,10 @@ from loguru import logger
 from basic_memory.cli.app import app
 from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.cli.commands.routing import force_routing, validate_routing_flags
-from basic_memory.mcp.tools import build_context as mcp_build_context
-from basic_memory.mcp.tools import delete_note as mcp_delete_note
-from basic_memory.mcp.tools import edit_note as mcp_edit_note
-from basic_memory.mcp.tools import list_memory_projects as mcp_list_projects
-from basic_memory.mcp.tools import list_workspaces as mcp_list_workspaces
-from basic_memory.mcp.tools import read_note as mcp_read_note
-from basic_memory.mcp.tools import recent_activity as mcp_recent_activity
-from basic_memory.mcp.tools import schema_diff as mcp_schema_diff
-from basic_memory.mcp.tools import schema_infer as mcp_schema_infer
-from basic_memory.mcp.tools import schema_validate as mcp_schema_validate
-from basic_memory.mcp.tools import search_notes as mcp_search
-from basic_memory.mcp.tools import write_note as mcp_write_note
+
+# MCP tool functions are imported inside each command: importing
+# basic_memory.mcp.tools loads the entire tool stack (fastmcp, mcp SDK,
+# SQLAlchemy), which would slow every CLI invocation, including --help (#886).
 
 tool_app = typer.Typer()
 app.add_typer(tool_app, name="tool", help="Access to MCP tools via CLI")
@@ -120,6 +112,9 @@ def write_note(
     bm tool write-note --title "My Note" --folder "notes" --overwrite
     bm tool write-note --title "My Note" --folder "notes" --local
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import write_note as mcp_write_note
+
     try:
         validate_routing_flags(local, cloud)
 
@@ -206,6 +201,9 @@ def read_note(
     bm tool read-note my-note
     bm tool read-note my-note --include-frontmatter
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import read_note as mcp_read_note
+
     try:
         validate_routing_flags(local, cloud)
 
@@ -272,6 +270,9 @@ def delete_note(
     bm tool delete-note notes/old-draft
     bm tool delete-note docs/archive --is-directory
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import delete_note as mcp_delete_note
+
     try:
         validate_routing_flags(local, cloud)
 
@@ -346,6 +347,9 @@ def edit_note(
     bm tool edit-note my-note --operation find_replace --find-text "old" --content "new"
     bm tool edit-note my-note --operation replace_section --section "## Notes" --content "updated"
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import edit_note as mcp_edit_note
+
     try:
         validate_routing_flags(local, cloud)
 
@@ -413,6 +417,9 @@ def build_context(
     bm tool build-context memory://specs/search
     bm tool build-context specs/search --depth 2 --timeframe 30d
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import build_context as mcp_build_context
+
     try:
         validate_routing_flags(local, cloud)
 
@@ -476,6 +483,9 @@ def recent_activity(
     bm tool recent-activity --timeframe 30d --page-size 20
     bm tool recent-activity --type entity --type observation
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import recent_activity as mcp_recent_activity
+
     try:
         validate_routing_flags(local, cloud)
 
@@ -582,6 +592,9 @@ def search_notes(
     bm tool search-notes --meta status=draft
     bm tool search-notes "auth" --entity-type observation --category requirement
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import search_notes as mcp_search
+
     try:
         validate_routing_flags(local, cloud)
 
@@ -687,6 +700,9 @@ def list_projects(
     bm tool list-projects
     bm tool list-projects --local
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import list_memory_projects as mcp_list_projects
+
     try:
         validate_routing_flags(local, cloud)
 
@@ -720,6 +736,9 @@ def list_workspaces(
     bm tool list-workspaces
     bm tool list-workspaces --cloud
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import list_workspaces as mcp_list_workspaces
+
     try:
         validate_routing_flags(local, cloud)
 
@@ -772,6 +791,9 @@ def schema_validate(
     bm tool schema-validate people/ada-lovelace.md
     bm tool schema-validate --project research
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import schema_validate as mcp_schema_validate
+
     try:
         validate_routing_flags(local, cloud)
 
@@ -840,6 +862,9 @@ def schema_infer(
     bm tool schema-infer meeting --threshold 0.5
     bm tool schema-infer person --project research
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import schema_infer as mcp_schema_infer
+
     try:
         validate_routing_flags(local, cloud)
 
@@ -896,6 +921,9 @@ def schema_diff(
     bm tool schema-diff person
     bm tool schema-diff person --project research
     """
+    # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
+    from basic_memory.mcp.tools import schema_diff as mcp_schema_diff
+
     try:
         validate_routing_flags(local, cloud)
 

src/basic_memory/cli/main.py

@@ -24,6 +24,7 @@ if not _version_only_invocation(sys.argv[1:]):
         import_claude_conversations,
         import_claude_projects,
         import_memory_json,
+        man,
         mcp,
         orphans,
         project,

src/basic_memory/config.py

@@ -4,6 +4,7 @@ import importlib.util
 import json
 import os
 import shutil
+import threading
 from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
@@ -657,6 +658,26 @@ class BasicMemoryConfig(BaseSettings):
         entry = self.projects.get(project_name)
         return entry.mode if entry else ProjectMode.CLOUD
 
+    def is_locally_syncable(self, project_name: str, project_path: str) -> bool:
+        """Whether a project should be synced/watched on the local filesystem.
+
+        Both conditions are required (issue #949):
+
+          * The project is present in config. Config is the source of truth, so a
+            stale database row that was removed from config — but whose deletion
+            has not yet been reconciled, or whose reconciliation failed — must
+            not be synced even though it still has a real directory on disk.
+          * Its path is absolute. An empty or relative path resolves against the
+            process cwd, so syncing it would adopt whatever directory the server
+            was launched from as the project root and mutate unrelated files.
+
+        Cloud-only projects (empty/slug path) and cloud projects with a real
+        local bisync copy (absolute path) are handled correctly by these two
+        conditions, so no separate mode check is needed.
+        """
+        entry = self.projects.get(project_name)
+        return entry is not None and Path(project_path).is_absolute()
+
     def set_project_mode(self, project_name: str, mode: ProjectMode) -> None:
         """Set the routing mode for a project.
 
@@ -1099,8 +1120,21 @@ def save_basic_memory_config(file_path: Path, config: BasicMemoryConfig) -> None
         _secure_config_dir(file_path.parent)
         # Use model_dump with mode='json' to serialize datetime objects properly
         config_dict = config.model_dump(mode="json")
-        file_path.write_text(json.dumps(config_dict, indent=2))
-        _secure_config_file(file_path)
+        # Trigger: long-lived readers (MCP stdio server config reload, background
+        # auto-update threads) re-read config.json whenever its mtime changes,
+        # concurrently with CLI commands saving it.
+        # Why: writing the destination in place truncates it first, so a concurrent
+        # reader can observe empty/partial JSON and load_config() exits the process.
+        # Outcome: write a sibling temp file (unique per process/thread so parallel
+        # savers cannot interleave) and publish atomically via os.replace — readers
+        # always see either the old or the new complete document. (#940)
+        tmp_path = file_path.parent / f"{file_path.name}.{os.getpid()}.{threading.get_ident()}.tmp"
+        try:
+            tmp_path.write_text(json.dumps(config_dict, indent=2))
+            _secure_config_file(tmp_path)
+            os.replace(tmp_path, file_path)
+        finally:
+            tmp_path.unlink(missing_ok=True)
     except Exception as e:  # pragma: no cover
         logger.error(f"Failed to save config: {e}")
 

src/basic_memory/db.py

@@ -19,7 +19,7 @@ from sqlalchemy.ext.asyncio import (
     AsyncEngine,
     async_scoped_session,
 )
-from sqlalchemy.pool import NullPool
+from sqlalchemy.pool import AsyncAdaptedQueuePool, NullPool
 
 from basic_memory.repository.postgres_search_repository import PostgresSearchRepository
 from basic_memory.repository.sqlite_search_repository import SQLiteSearchRepository
@@ -216,19 +216,31 @@ def _create_sqlite_engine(db_url: str, db_type: DatabaseType) -> AsyncEngine:
                 "isolation_level": None,  # Use autocommit mode
             }
         )
+
+    if db_type == DatabaseType.MEMORY:
+        # Trigger: an in-memory SQLite URL would default to StaticPool, which hands the
+        # same DBAPI connection to every concurrently checked-out session.
+        # Why: concurrent asyncio tasks then share one transaction scope — a rollback
+        # issued by one session (scoped_session exception handling or the pool's
+        # reset-on-return) silently destroys another session's uncommitted writes (#940).
+        # Outcome: a single-connection blocking queue pool keeps the in-memory database
+        # alive for the engine's lifetime while serializing sessions at transaction
+        # granularity, restoring the isolation the repositories assume.
+        engine = create_async_engine(
+            db_url,
+            connect_args=connect_args,
+            poolclass=AsyncAdaptedQueuePool,
+            pool_size=1,
+            max_overflow=0,
+        )
+    elif os.name == "nt":
         # Use NullPool for Windows filesystem databases to avoid connection pooling issues
-        # Important: Do NOT use NullPool for in-memory databases as it will destroy the database
-        # between connections
-        if db_type == DatabaseType.FILESYSTEM:
-            engine = create_async_engine(
-                db_url,
-                connect_args=connect_args,
-                poolclass=NullPool,  # Disable connection pooling on Windows
-                echo=False,
-            )
-        else:
-            # In-memory databases need connection pooling to maintain state
-            engine = create_async_engine(db_url, connect_args=connect_args)
+        engine = create_async_engine(
+            db_url,
+            connect_args=connect_args,
+            poolclass=NullPool,  # Disable connection pooling on Windows
+            echo=False,
+        )
     else:
         engine = create_async_engine(db_url, connect_args=connect_args)
 

src/basic_memory/file_utils.py

@@ -302,26 +302,76 @@ async def format_file(
         return None
 
 
+# A frontmatter fence is a line containing exactly `---`, optionally followed by
+# trailing horizontal whitespace. Anchoring to a full line (rather than a bare
+# substring/`startswith`) prevents single-line content like
+# `---\nstatus: active\n---\nBody` — where `\n` is a literal backslash-n, not a
+# newline — from being misread as frontmatter. See issue #972.
+_FENCE_RE = re.compile(r"^---[ \t]*$")
+
+
+def _split_frontmatter(content: str) -> Optional[tuple[str, str]]:
+    """Split content into (yaml_block, body) when it opens with a line-anchored fence.
+
+    The opening fence must be the very first line and the closing fence must be a
+    later line, each matching exactly `---` (with optional trailing whitespace).
+
+    Returns:
+        A `(yaml_block, body)` tuple when a complete fenced block is present, or
+        ``None`` when the content does not open with a frontmatter fence.
+
+    Raises:
+        ParseError: If the content opens with a fence but has no closing fence.
+    """
+    lines = content.splitlines(keepends=True)
+
+    # Skip leading blank lines: a document may begin with whitespace before the
+    # opening fence (e.g. a heredoc/dedented string starting with a newline). This
+    # does NOT relax line-anchoring — the opening fence must still be the first
+    # non-blank line, all on its own, so a single-line `---\\nstatus...` (literal
+    # backslash-n) is still rejected. See issue #972.
+    start = 0
+    while start < len(lines) and lines[start].strip() == "":
+        start += 1
+
+    if start >= len(lines) or not _FENCE_RE.match(lines[start].rstrip("\r\n")):
+        return None
+
+    # Find the closing fence on its own line somewhere after the opening fence.
+    for index in range(start + 1, len(lines)):
+        if _FENCE_RE.match(lines[index].rstrip("\r\n")):
+            yaml_block = "".join(lines[start + 1 : index])
+            body = "".join(lines[index + 1 :])
+            return yaml_block, body
+
+    raise ParseError("Invalid frontmatter format")
+
+
 def has_frontmatter(content: str) -> bool:
     """
     Check if content contains valid YAML frontmatter.
 
+    Frontmatter requires `---` fences on their own lines; an inline `---` (such as
+    a single-line string that merely starts with the characters `---`) is not
+    frontmatter.
+
     Args:
         content: Content to check
 
     Returns:
-        True if content has valid frontmatter markers (---), False otherwise
+        True if content has line-anchored frontmatter fences, False otherwise
     """
     if not content:
         return False
 
     # Strip BOM before checking for frontmatter markers
-    content = strip_bom(content).strip()
-    if not content.startswith("---"):
+    content = strip_bom(content)
+    try:
+        return _split_frontmatter(content) is not None
+    except ParseError:
+        # An opening fence with no closing fence is not usable frontmatter.
         return False
 
-    return "---" in content[3:]
-
 
 def parse_frontmatter(content: str) -> Dict[str, Any]:
     """
@@ -339,17 +389,14 @@ def parse_frontmatter(content: str) -> Dict[str, Any]:
     try:
         # Strip BOM before parsing frontmatter
         content = strip_bom(content)
-        if not content.strip().startswith("---"):
+        split = _split_frontmatter(content)
+        if split is None:
             raise ParseError("Content has no frontmatter")
-
-        # Split on first two occurrences of ---
-        parts = content.split("---", 2)
-        if len(parts) < 3:
-            raise ParseError("Invalid frontmatter format")
+        yaml_block, _ = split
 
         # Parse YAML
         try:
-            frontmatter = yaml.safe_load(parts[1])
+            frontmatter = yaml.safe_load(yaml_block)
             # Handle empty frontmatter (None from yaml.safe_load)
             if frontmatter is None:
                 return {}
@@ -381,18 +428,17 @@ def remove_frontmatter(content: str) -> str:
         ParseError: If content starts with frontmatter marker but is malformed
     """
     # Strip BOM before processing
-    content = strip_bom(content).strip()
+    content = strip_bom(content)
 
-    # Return as-is if no frontmatter marker
-    if not content.startswith("---"):
-        return content
+    split = _split_frontmatter(content)
+    # Trigger: content does not open with a line-anchored fence
+    # Why: inline `---` is ordinary content, not frontmatter (issue #972)
+    # Outcome: return the content untouched (stripped to preserve prior behavior)
+    if split is None:
+        return content.strip()
 
-    # Split on first two occurrences of ---
-    parts = content.split("---", 2)
-    if len(parts) < 3:
-        raise ParseError("Invalid frontmatter format")
-
-    return parts[2].strip()
+    _, body = split
+    return body.strip()
 
 
 def dump_frontmatter(post: frontmatter.Post) -> str:

src/basic_memory/man/basic-memory.1

@@ -0,0 +1 @@
+.so man1/bm.1

src/basic_memory/man/bm.1

@@ -0,0 +1,134 @@
+.TH BM 1 "2026-06-11" "basic-memory" "Basic Memory Manual"
+.SH NAME
+bm \- local-first knowledge base for humans and AI agents
+.SH SYNOPSIS
+.B bm
+.I COMMAND
+.RI [ ARGS ]...
+.br
+.B basic-memory
+.I COMMAND
+.RI [ ARGS ]...
+.SH DESCRIPTION
+.B bm
+manages Basic Memory projects: plain markdown files that form a knowledge
+graph. Files are the source of truth; SQLite provides indexing and
+full-text search; the same operations are exposed to AI agents over the
+Model Context Protocol (MCP) and to humans and scripts through this CLI.
+.PP
+Notes use semantic markdown: observations
+.RB ( "\- [category] text #tag" )
+and relations
+.RB ( "\- relation_type [[Target]]" )
+become queryable graph structure. Projects route independently to the
+local API or to Basic Memory Cloud.
+.SH COMMANDS
+Knowledge operations:
+.TP
+.B bm tool
+CLI access to the MCP tools (write-note, read-note, search-notes,
+build-context, ...). These emit JSON and are the scriptable surface.
+.TP
+.B bm status
+Show sync status between files and the database.
+.TP
+.B bm reindex
+Index local file changes and rebuild search/embeddings. This is the manual
+sync trigger when no MCP server is running.
+.TP
+.B bm doctor
+Run end-to-end file/database consistency checks.
+.TP
+.B bm orphans
+List entities with no relations in the knowledge graph.
+.TP
+.B bm format
+Run configured formatters over note files.
+.PP
+Projects and schemas:
+.TP
+.B bm project
+Add, remove, list projects; set the default; flip a project between local
+and cloud routing.
+.TP
+.B bm schema
+List, validate, infer, and drift-check Picoschema note-type contracts.
+.PP
+Data and cloud:
+.TP
+.B bm import
+Import from ChatGPT, Claude, or memory.json exports. Imports write files;
+run
+.B bm reindex
+afterwards.
+.TP
+.B bm cloud
+Authenticate, sync (push/pull/sync/bisync), snapshots, and team workspace
+administration.
+.PP
+Infrastructure:
+.TP
+.B bm mcp
+Run the MCP server (hosts the live file watcher).
+.TP
+.B bm man
+Manage these man pages
+.RB ( "bm man install" ).
+.TP
+.B bm reset
+Drop and recreate the database (destructive).
+.PP
+Most commands accept
+.B \-\-project
+.I NAME
+to target a project and
+.BR \-\-local / \-\-cloud
+to override routing.
+.SH EXAMPLES
+Write and find a note from the shell:
+.PP
+.nf
+.RS
+echo "# Standup notes" | bm tool write-note \\
+    \-\-title "Standup" \-\-folder notes
+bm tool search-notes "standup"
+.RE
+.fi
+.PP
+Pick up files created outside the tools:
+.PP
+.nf
+.RS
+bm status            # shows pending changes
+bm reindex           # indexes them
+.RE
+.fi
+.SH FILES
+.TP
+.I ~/.basic-memory/config.json
+Projects, default project, per-project routing modes, cloud settings.
+.TP
+.I ~/.basic-memory/memory.db
+SQLite index (derived; safe to rebuild with bm reindex).
+.SH ENVIRONMENT
+.TP
+.B BASIC_MEMORY_FORCE_LOCAL
+Force local routing regardless of cloud mode.
+.TP
+.B BASIC_MEMORY_LOG_LEVEL
+Logging verbosity (e.g. DEBUG).
+.SH SEE ALSO
+Full manual (machine-readable, agent-traversable): the
+.I manual
+Basic Memory project \(em see docs/manual-pages.md in the repository.
+Documentation: https://docs.basicmemory.com
+.PP
+For AI agents: the complete tool reference lives in the manual project as
+section\-3 pages (write-note(3), search-notes(3), ...), queryable via
+.B search_notes
+with
+.BR "metadata_filters={\(dqtype\(dq: \(dqmanpage\(dq}" .
+.SH BUGS
+https://github.com/basicmachines-co/basic-memory/issues
+.SH AUTHORS
+Basic Machines (https://basicmachines.co)

src/basic_memory/mcp/async_client.py

@@ -5,14 +5,16 @@ from dataclasses import dataclass
 from threading import RLock
 from typing import TYPE_CHECKING, Annotated, Any, AsyncIterator, Callable, Optional
 
-from fastapi import Depends, FastAPI, Request
 from httpx import ASGITransport, AsyncClient, Timeout
 from loguru import logger
 
 import logfire
-from basic_memory.config import ConfigManager, ProjectMode
+from basic_memory.config import ConfigManager, ProjectMode, has_cloud_credentials
 
 if TYPE_CHECKING:
+    # FastAPI is only needed when a request routes through the local ASGI
+    # transport; importing it at module level costs ~0.1s on every CLI start (#886).
+    from fastapi import FastAPI
     from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
 
 LocalDatabaseState = tuple["AsyncEngine", "async_sessionmaker[AsyncSession]"]
@@ -28,8 +30,8 @@ class _PreparedLocalAsgiDatabase:
 
 
 _prepared_local_asgi_database_lock = RLock()
-_prepared_local_asgi_database_prepare_locks: dict[FastAPI, Lock] = {}
-_prepared_local_asgi_databases: dict[FastAPI, _PreparedLocalAsgiDatabase] = {}
+_prepared_local_asgi_database_prepare_locks: dict["FastAPI", Lock] = {}
+_prepared_local_asgi_databases: dict["FastAPI", _PreparedLocalAsgiDatabase] = {}
 
 
 def _force_local_mode() -> bool:
@@ -57,7 +59,7 @@ def _build_timeout() -> Timeout:
     )
 
 
-def _build_asgi_client(app: FastAPI, timeout: Timeout) -> AsyncClient:
+def _build_asgi_client(app: "FastAPI", timeout: Timeout) -> AsyncClient:
     """Create a local ASGI client for an already-prepared FastAPI app."""
     from basic_memory.workspace_context import workspace_permalink_headers
 
@@ -71,7 +73,7 @@ def _build_asgi_client(app: FastAPI, timeout: Timeout) -> AsyncClient:
     )
 
 
-def _get_prepared_local_asgi_database_prepare_lock(app: FastAPI) -> Lock:
+def _get_prepared_local_asgi_database_prepare_lock(app: "FastAPI") -> Lock:
     """Get the async lock that serializes first-time DB preparation for an app."""
     with _prepared_local_asgi_database_lock:
         prepare_lock = _prepared_local_asgi_database_prepare_locks.get(app)
@@ -82,8 +84,10 @@ def _get_prepared_local_asgi_database_prepare_lock(app: FastAPI) -> Lock:
 
 
 @asynccontextmanager
-async def _resolve_local_asgi_database(app: FastAPI) -> AsyncIterator[LocalDatabaseState]:
+async def _resolve_local_asgi_database(app: "FastAPI") -> AsyncIterator[LocalDatabaseState]:
     """Resolve database state for a local ASGI request."""
+    # Imported on first local-ASGI use so CLI startup never pays for FastAPI (#886).
+    from fastapi import Depends, Request
     from fastapi.dependencies.utils import get_dependant, solve_dependencies
 
     from basic_memory.deps import get_engine_factory
@@ -127,7 +131,7 @@ async def _resolve_local_asgi_database(app: FastAPI) -> AsyncIterator[LocalDatab
         yield await resolve_database_state(**solved.values)
 
 
-def _retain_prepared_local_asgi_database(app: FastAPI) -> bool:
+def _retain_prepared_local_asgi_database(app: "FastAPI") -> bool:
     """Retain an active local ASGI database preparation if one exists."""
     with _prepared_local_asgi_database_lock:
         active = _prepared_local_asgi_databases.get(app)
@@ -139,7 +143,7 @@ def _retain_prepared_local_asgi_database(app: FastAPI) -> bool:
 
 
 def _install_prepared_local_asgi_database(
-    app: FastAPI,
+    app: "FastAPI",
     database_state: LocalDatabaseState,
     dependency_context: AbstractAsyncContextManager[LocalDatabaseState],
 ) -> None:
@@ -163,7 +167,7 @@ def _install_prepared_local_asgi_database(
         )
 
 
-def _restore_local_asgi_state_attribute(app: FastAPI, name: str, previous_value: object) -> None:
+def _restore_local_asgi_state_attribute(app: "FastAPI", name: str, previous_value: object) -> None:
     """Restore a FastAPI app.state attribute captured before local ASGI preparation."""
     if previous_value is _MISSING_STATE_VALUE:
         if hasattr(app.state, name):
@@ -173,7 +177,7 @@ def _restore_local_asgi_state_attribute(app: FastAPI, name: str, previous_value:
 
 
 def _release_prepared_local_asgi_database(
-    app: FastAPI,
+    app: "FastAPI",
 ) -> AbstractAsyncContextManager[LocalDatabaseState] | None:
     """Release local ASGI database state after a client context exits."""
     with _prepared_local_asgi_database_lock:
@@ -196,7 +200,7 @@ def _release_prepared_local_asgi_database(
 
 
 @asynccontextmanager
-async def _prepared_local_asgi_database(app: FastAPI) -> AsyncIterator[None]:
+async def _prepared_local_asgi_database(app: "FastAPI") -> AsyncIterator[None]:
     """Initialize local ASGI database state before the first request."""
     prepare_lock = _get_prepared_local_asgi_database_prepare_lock(app)
     async with prepare_lock:
@@ -368,7 +372,8 @@ async def get_client(
     1. Factory injection.
     2. Explicit routing flags (--local/--cloud).
     3. Per-project mode routing when project_name is provided.
-    4. Local ASGI transport by default.
+    4. Cloud routing when a workspace selector is provided.
+    5. Local ASGI transport by default.
     """
     if _client_factory:
         async with _client_factory(workspace=workspace) as client:
@@ -428,6 +433,26 @@ async def get_client(
             yield client
         return
 
+    # --- Workspace-selector routing ---
+    # Trigger: caller passed a cloud workspace selector and nothing above routed.
+    # Why: a workspace names a cloud tenant — silently serving the request from
+    #   the local ASGI app sent writes to the wrong destination (#954: a cloud
+    #   project create either failed on the cloud-style path or landed locally).
+    # Outcome: route to the cloud proxy when credentials exist; without
+    #   credentials fail fast instead of pretending the operation succeeded.
+    if workspace is not None:
+        if not has_cloud_credentials(config):
+            raise RuntimeError(
+                f"A cloud workspace was requested ('{workspace}') but no cloud "
+                "credentials were found. Run 'bm cloud login' or "
+                "'bm cloud set-key <key>' first, or omit the workspace selector "
+                "for a local operation."
+            )
+        logger.debug(f"Workspace selector '{workspace}' provided - using cloud proxy client")
+        async with _cloud_client(config, timeout, workspace=workspace) as client:
+            yield client
+        return
+
     # --- Default fallback ---
     logger.debug("Default routing - using ASGI client for local Basic Memory API")
     async with _asgi_client(timeout) as client:

src/basic_memory/mcp/clients/directory.py

@@ -7,7 +7,9 @@ from typing import Optional, Any
 
 from httpx import AsyncClient
 
-from basic_memory.mcp.tools.utils import call_get
+# call_* helpers live in basic_memory.mcp.tools.utils; importing that at module
+# level executes the whole tools package (fastmcp + mcp SDK) during CLI startup,
+# so each method defers the import to call time instead (#886).
 
 
 class DirectoryClient:
@@ -55,6 +57,8 @@ class DirectoryClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_get
+
         params: dict = {
             "dir_name": dir_name,
             "depth": depth,

src/basic_memory/mcp/clients/knowledge.py

@@ -8,7 +8,10 @@ from typing import Any
 from httpx import AsyncClient
 
 import logfire
-from basic_memory.mcp.tools.utils import call_get, call_post, call_put, call_patch, call_delete
+
+# call_* helpers live in basic_memory.mcp.tools.utils; importing that at module
+# level executes the whole tools package (fastmcp + mcp SDK) during CLI startup,
+# so each method defers the import to call time instead (#886).
 from basic_memory.schemas.response import (
     EntityResponse,
     DeleteEntitiesResponse,
@@ -57,6 +60,8 @@ class KnowledgeClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_post
+
         with logfire.span(
             "mcp.client.knowledge.create_entity",
             client_name="knowledge",
@@ -89,6 +94,8 @@ class KnowledgeClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_put
+
         with logfire.span(
             "mcp.client.knowledge.update_entity",
             client_name="knowledge",
@@ -116,6 +123,8 @@ class KnowledgeClient:
         Raises:
             ToolError: If the entity is not found or request fails
         """
+        from basic_memory.mcp.tools.utils import call_get
+
         with logfire.span(
             "mcp.client.knowledge.get_entity",
             client_name="knowledge",
@@ -147,6 +156,8 @@ class KnowledgeClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_patch
+
         with logfire.span(
             "mcp.client.knowledge.patch_entity",
             client_name="knowledge",
@@ -174,6 +185,8 @@ class KnowledgeClient:
         Raises:
             ToolError: If the entity is not found or request fails
         """
+        from basic_memory.mcp.tools.utils import call_delete
+
         with logfire.span(
             "mcp.client.knowledge.delete_entity",
             client_name="knowledge",
@@ -201,6 +214,8 @@ class KnowledgeClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_put
+
         with logfire.span(
             "mcp.client.knowledge.move_entity",
             client_name="knowledge",
@@ -231,6 +246,8 @@ class KnowledgeClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_post
+
         with logfire.span(
             "mcp.client.knowledge.move_directory",
             client_name="knowledge",
@@ -261,6 +278,8 @@ class KnowledgeClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_post
+
         with logfire.span(
             "mcp.client.knowledge.delete_directory",
             client_name="knowledge",
@@ -290,6 +309,8 @@ class KnowledgeClient:
         Raises:
             ToolError: If the file does not exist on disk or indexing fails
         """
+        from basic_memory.mcp.tools.utils import call_post
+
         with logfire.span(
             "mcp.client.knowledge.sync_file",
             client_name="knowledge",
@@ -309,6 +330,8 @@ class KnowledgeClient:
 
     async def get_orphans(self) -> list[GraphNode]:
         """Get entities that have no incoming or outgoing relations."""
+        from basic_memory.mcp.tools.utils import call_get
+
         with logfire.span(
             "mcp.client.knowledge.get_orphans",
             client_name="knowledge",
@@ -338,6 +361,8 @@ class KnowledgeClient:
         Raises:
             ToolError: If the identifier cannot be resolved
         """
+        from basic_memory.mcp.tools.utils import call_post
+
         with logfire.span(
             "mcp.client.knowledge.resolve_entity",
             client_name="knowledge",

src/basic_memory/mcp/clients/memory.py

@@ -8,7 +8,10 @@ from typing import Optional
 from httpx import AsyncClient
 
 import logfire
-from basic_memory.mcp.tools.utils import call_get
+
+# call_* helpers live in basic_memory.mcp.tools.utils; importing that at module
+# level executes the whole tools package (fastmcp + mcp SDK) during CLI startup,
+# so each method defers the import to call time instead (#886).
 from basic_memory.schemas.memory import GraphContext
 
 
@@ -63,6 +66,8 @@ class MemoryClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_get
+
         params: dict = {
             "depth": depth,
             "page": page,
@@ -113,6 +118,8 @@ class MemoryClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_get
+
         params: dict = {
             "timeframe": timeframe,
             "depth": depth,

src/basic_memory/mcp/clients/project.py

@@ -7,13 +7,9 @@ from typing import Any
 
 from httpx import AsyncClient
 
-from basic_memory.mcp.tools.utils import (
-    call_delete,
-    call_get,
-    call_patch,
-    call_post,
-    call_put,
-)
+# call_* helpers live in basic_memory.mcp.tools.utils; importing that at module
+# level executes the whole tools package (fastmcp + mcp SDK) during CLI startup,
+# so each method defers the import to call time instead (#886).
 from basic_memory.schemas import ProjectInfoResponse, SyncReportResponse
 from basic_memory.schemas.project_info import ProjectList, ProjectStatusResponse
 from basic_memory.schemas.v2 import ProjectResolveResponse
@@ -53,6 +49,8 @@ class ProjectClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_get
+
         response = await call_get(
             self.http_client,
             "/v2/projects/",
@@ -71,6 +69,8 @@ class ProjectClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_post
+
         response = await call_post(
             self.http_client,
             "/v2/projects/",
@@ -93,6 +93,8 @@ class ProjectClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_delete
+
         url = f"/v2/projects/{project_external_id}"
         if delete_notes:
             url += "?delete_notes=true"
@@ -114,6 +116,8 @@ class ProjectClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_post
+
         response = await call_post(
             self.http_client,
             "/v2/projects/resolve",
@@ -133,6 +137,8 @@ class ProjectClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_put
+
         response = await call_put(
             self.http_client,
             f"/v2/projects/{project_external_id}/default",
@@ -154,6 +160,8 @@ class ProjectClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_patch
+
         response = await call_patch(
             self.http_client,
             f"/v2/projects/{project_external_id}",
@@ -181,6 +189,8 @@ class ProjectClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_post
+
         url = f"/v2/projects/{project_external_id}/sync"
         params = []
         if force_full:
@@ -204,6 +214,8 @@ class ProjectClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_post
+
         response = await call_post(
             self.http_client,
             f"/v2/projects/{project_external_id}/status",
@@ -222,6 +234,8 @@ class ProjectClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_get
+
         response = await call_get(
             self.http_client,
             f"/v2/projects/{project_external_id}/info",

src/basic_memory/mcp/clients/resource.py

@@ -6,7 +6,9 @@ Encapsulates all /v2/projects/{project_id}/resource/* endpoints.
 from httpx import AsyncClient, Response
 
 import logfire
-from basic_memory.mcp.tools.utils import call_get
+# call_* helpers live in basic_memory.mcp.tools.utils; importing that at module
+# level executes the whole tools package (fastmcp + mcp SDK) during CLI startup,
+# so each method defers the import to call time instead (#886).
 
 
 class ResourceClient:
@@ -49,6 +51,8 @@ class ResourceClient:
         Raises:
             ToolError: If the resource is not found or request fails
         """
+        from basic_memory.mcp.tools.utils import call_get
+
         with logfire.span(
             "mcp.client.resource.read",
             client_name="resource",

src/basic_memory/mcp/clients/schema.py

@@ -5,7 +5,9 @@ Encapsulates all /v2/projects/{project_id}/schema/* endpoints.
 
 from httpx import AsyncClient
 
-from basic_memory.mcp.tools.utils import call_post, call_get
+# call_* helpers live in basic_memory.mcp.tools.utils; importing that at module
+# level executes the whole tools package (fastmcp + mcp SDK) during CLI startup,
+# so each method defers the import to call time instead (#886).
 from basic_memory.schemas.schema import (
     ValidationReport,
     InferenceReport,
@@ -56,6 +58,8 @@ class SchemaClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_post
+
         params: dict[str, str] = {}
         if note_type:
             params["note_type"] = note_type
@@ -87,6 +91,8 @@ class SchemaClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_post
+
         response = await call_post(
             self.http_client,
             f"{self._base_path}/infer",
@@ -106,6 +112,8 @@ class SchemaClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_get
+
         response = await call_get(
             self.http_client,
             f"{self._base_path}/diff/{note_type}",

src/basic_memory/mcp/clients/search.py

@@ -8,7 +8,10 @@ from typing import Any
 from httpx import AsyncClient
 
 import logfire
-from basic_memory.mcp.tools.utils import call_post
+
+# call_* helpers live in basic_memory.mcp.tools.utils; importing that at module
+# level executes the whole tools package (fastmcp + mcp SDK) during CLI startup,
+# so each method defers the import to call time instead (#886).
 from basic_memory.schemas.search import SearchResponse
 
 
@@ -57,6 +60,8 @@ class SearchClient:
         Raises:
             ToolError: If the request fails
         """
+        from basic_memory.mcp.tools.utils import call_post
+
         with logfire.span(
             "mcp.client.search.search",
             client_name="search",

src/basic_memory/mcp/project_context.py

@@ -8,10 +8,24 @@ The resolve_project_parameter function is a thin wrapper for backwards
 compatibility with existing MCP tools.
 """
 
+# PEP 563 lazy annotations keep `Context` usable in signatures without importing
+# fastmcp at module load — the fastmcp/mcp stack costs ~0.5s of CLI startup (#886).
+from __future__ import annotations
+
 import asyncio
 from contextlib import asynccontextmanager, nullcontext
+from typing import (
+    TYPE_CHECKING,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    List,
+    Optional,
+    Sequence,
+    Tuple,
+    cast,
+)
 from dataclasses import dataclass, field
-from typing import AsyncIterator, Awaitable, Callable, List, Optional, Sequence, Tuple, cast
 from uuid import UUID
 
 from httpx import AsyncClient
@@ -19,8 +33,6 @@ from httpx._types import (
     HeaderTypes,
 )
 from loguru import logger
-from fastmcp import Context
-from mcp.server.fastmcp.exceptions import ToolError
 
 import logfire
 from basic_memory.config import BasicMemoryConfig, ConfigManager, ProjectMode, has_cloud_credentials
@@ -46,6 +58,9 @@ from basic_memory.workspace_context import (
     workspace_permalink_context,
 )
 
+if TYPE_CHECKING:
+    from fastmcp import Context
+
 # --- Workspace provider injection ---
 # Mirrors the set_client_factory() pattern in async_client.py.
 # The cloud MCP server sets a provider that queries its own database directly,
@@ -54,6 +69,14 @@ _workspace_provider: Optional[Callable[[], Awaitable[list[WorkspaceInfo]]]] = No
 _WORKSPACE_PROJECT_INDEX_STATE_KEY = "workspace_project_index"
 
 
+class WorkspaceProjectLookupMiss(ValueError):
+    """A project was absent from the workspace index (as opposed to ambiguous).
+
+    Misses are retried once against a freshly rebuilt index, because the
+    session cache may simply predate an out-of-band project creation (#956).
+    """
+
+
 @dataclass(frozen=True)
 class WorkspaceProjectEntry:
     """A cloud project resolved together with the workspace that owns it."""
@@ -460,6 +483,17 @@ def _canonical_memory_path_for_workspace(
     # Outcome: lookups preserve the complete workspace/project canonical permalink.
     if not normalized_remainder:
         normalized_remainder = project_permalink
+
+    # Same index-form rule as _canonical_memory_path_for_active_route (#957):
+    # without an active workspace permalink context, stored permalinks are
+    # project-qualified and a workspace-prefixed pattern cannot match.
+    if "*" in normalized_remainder and current_workspace_permalink_context() is None:
+        return build_qualified_permalink_reference(
+            project_permalink,
+            normalized_remainder,
+            include_project=True,
+        )
+
     return build_qualified_permalink_reference(
         project_permalink,
         normalized_remainder,
@@ -477,6 +511,24 @@ def _canonical_memory_path_for_active_route(
 ) -> str:
     """Return the canonical permalink path for the currently routed project/workspace."""
     project_prefix = active_project.permalink
+
+    # Trigger: the path contains a glob wildcard (folder/*) and no server-side
+    #   workspace permalink context is active.
+    # Why: patterns match raw against the search index, so they must mirror the
+    #   stored permalink form. The contextvar is what qualified permalinks at
+    #   write time — when it is absent, stored rows are project-qualified and a
+    #   workspace prefix (from the client's cached_workspace display state)
+    #   guarantees zero matches (#957). Direct lookups keep full qualification
+    #   because the link resolver understands it; patterns have no fallback.
+    # Outcome: without the contextvar, qualify patterns with the project prefix
+    #   only; with it, fall through to normal workspace canonicalization.
+    if "*" in path and current_workspace_permalink_context() is None:
+        if not include_project:
+            return path
+        if path == project_prefix or path.startswith(f"{project_prefix}/"):
+            return path
+        return f"{project_prefix}/{path}"
+
     workspace_remainder = path
     if include_project and (path == project_prefix or path.startswith(f"{project_prefix}/")):
         # Trigger: the memory URL already names the active project root/prefix
@@ -722,9 +774,15 @@ async def _fetch_workspace_project_entries(
 
 async def _ensure_workspace_project_index(
     context: Optional[Context] = None,
+    *,
+    force_refresh: bool = False,
 ) -> WorkspaceProjectIndex:
-    """Build or load the session-local workspace/project lookup index."""
-    if context:
+    """Build or load the session-local workspace/project lookup index.
+
+    force_refresh bypasses the cached index and rebuilds from discovery —
+    used by resolve_workspace_project_identifier when a lookup misses (#956).
+    """
+    if context and not force_refresh:
         cached_raw = await context.get_state(_WORKSPACE_PROJECT_INDEX_STATE_KEY)
         cached_index = _workspace_project_index_from_state(cached_raw)
         if cached_index is not None:
@@ -798,13 +856,99 @@ async def ensure_workspace_project_index(
     return await _ensure_workspace_project_index(context=context)
 
 
+def _match_workspace_identifier(
+    workspaces: tuple[WorkspaceInfo, ...],
+    workspace_identifier: str,
+) -> WorkspaceInfo:
+    """Resolve the first segment of a qualified route to a single workspace.
+
+    The edit_note/write_note contract advertises that the workspace segment may be a
+    slug, tenant_id, or display name. We honor those forms in a fixed priority order so
+    that adding tenant_id/name support never changes the meaning of an identifier that
+    already resolves today:
+
+    1. slug (casefold) — existing behavior, checked first so working routes are stable.
+    2. tenant_id — exact match against the opaque id (no casefolding, mirroring the
+       precedent in ``workspace_matches_exact_identifier``).
+    3. display name (casefold) — names are not guaranteed unique, so a name that matches
+       multiple workspaces is rejected rather than silently picking one.
+    """
+    # Trigger: identifier equals a workspace slug (casefold).
+    # Why: slug is the canonical routing key; resolving it first guarantees a workspace
+    # whose display name collides with another workspace's slug yields to the slug owner.
+    # Outcome: return the slug owner before tenant_id/name are considered.
+    slug_matches = [
+        workspace
+        for workspace in workspaces
+        if workspace.slug.casefold() == workspace_identifier.casefold()
+    ]
+    if slug_matches:
+        return slug_matches[0]
+
+    # Trigger: identifier exactly equals a workspace tenant_id (an opaque id).
+    # Why: tenant_ids are unique, so an exact hit is unambiguous and needs no tie-break.
+    tenant_matches = [
+        workspace for workspace in workspaces if workspace.tenant_id == workspace_identifier
+    ]
+    if tenant_matches:
+        return tenant_matches[0]
+
+    # Trigger: identifier matches one or more workspace display names (casefold).
+    # Why: names are not guaranteed unique; failing fast on collisions keeps routing
+    # deterministic and tells the caller exactly how to disambiguate.
+    name_matches = [
+        workspace
+        for workspace in workspaces
+        if workspace.name.casefold() == workspace_identifier.casefold()
+    ]
+    if len(name_matches) > 1:
+        candidates = ", ".join(workspace.slug for workspace in name_matches)
+        raise ValueError(
+            f"Workspace name '{workspace_identifier}' matched multiple workspaces "
+            f"(slugs: {candidates}). Use the workspace slug or tenant_id to disambiguate."
+        )
+    if name_matches:
+        return name_matches[0]
+
+    available = ", ".join(workspace.slug for workspace in workspaces)
+    raise ValueError(
+        f"Workspace '{workspace_identifier}' was not found by slug, tenant_id, or name. "
+        f"Available workspace slugs: {available}"
+    )
+
+
 async def resolve_workspace_project_identifier(
     project: str,
     context: Optional[Context] = None,
 ) -> WorkspaceProjectEntry:
     """Resolve a project by external_id (UUID), qualified name, or unqualified name."""
     index = await _ensure_workspace_project_index(context=context)
+    try:
+        return await _resolve_workspace_project_from_index(index, project, context)
+    except WorkspaceProjectLookupMiss:
+        # Trigger: the lookup missed the session-cached index.
+        # Why: a miss is exactly the signal the cache may be stale — projects
+        #   created out-of-band (CLI, a teammate in a shared workspace) post-date
+        #   the index built at session start (#956).
+        # Outcome: rebuild the index once and retry; a second miss is authoritative
+        #   and its error (with the refreshed project list) propagates.
+        logger.info(
+            f"Workspace project lookup missed for '{project}'; refreshing index and retrying"
+        )
+        refreshed = await _ensure_workspace_project_index(context=context, force_refresh=True)
+        return await _resolve_workspace_project_from_index(refreshed, project, context)
 
+
+async def _resolve_workspace_project_from_index(
+    index: WorkspaceProjectIndex,
+    project: str,
+    context: Optional[Context] = None,
+) -> WorkspaceProjectEntry:
+    """Resolve a project against one concrete index snapshot.
+
+    Raises WorkspaceProjectLookupMiss for absent projects (retryable via index
+    refresh) and plain ValueError for ambiguity, which a refresh cannot fix.
+    """
     # Fast path: direct lookup by external_id when the identifier is a UUID
     # Canonicalize via str(UUID(...)) so uppercase, brace-wrapped, or urn:uuid forms
     # all hash to the same lowercase-hyphenated key as the stored external_ids.
@@ -816,23 +960,14 @@ async def resolve_workspace_project_identifier(
     except ValueError:
         pass
 
-    workspace_slug, project_identifier = _split_qualified_project_identifier(project)
+    workspace_identifier, project_identifier = _split_qualified_project_identifier(project)
     project_permalink = generate_permalink(project_identifier)
 
-    if workspace_slug:
-        workspace_matches = [
-            workspace
-            for workspace in index.workspaces
-            if workspace.slug.casefold() == workspace_slug.casefold()
-        ]
-        if not workspace_matches:
-            available = ", ".join(workspace.slug for workspace in index.workspaces)
-            raise ValueError(
-                f"Workspace '{workspace_slug}' was not found. "
-                f"Available workspace slugs: {available}"
-            )
-
-        workspace = workspace_matches[0]
+    if workspace_identifier:
+        # Honor the documented "slug, name, or tenant_id" contract for the workspace
+        # segment; _match_workspace_identifier raises a clear error on ambiguous names
+        # and unknown identifiers, listing what forms were tried.
+        workspace = _match_workspace_identifier(index.workspaces, workspace_identifier)
         matches = [
             entry
             for entry in index.entries_by_permalink.get(project_permalink, ())
@@ -843,7 +978,7 @@ async def resolve_workspace_project_identifier(
                 failed_workspace.tenant_id == workspace.tenant_id
                 for failed_workspace in index.failed_workspaces
             ):
-                raise ValueError(
+                raise WorkspaceProjectLookupMiss(
                     f"Projects for workspace '{workspace.name}' ({workspace.slug}) "
                     "could not be loaded. Retry after workspace discovery recovers."
                 )
@@ -852,7 +987,7 @@ async def resolve_workspace_project_identifier(
                 for entry in index.entries
                 if entry.workspace.tenant_id == workspace.tenant_id
             )
-            raise ValueError(
+            raise WorkspaceProjectLookupMiss(
                 f"Project '{project_identifier}' was not found in workspace "
                 f"'{workspace.name}' ({workspace.slug}). Available projects: {available}"
             )
@@ -877,7 +1012,7 @@ async def resolve_workspace_project_identifier(
                 "retry or use a qualified project from an indexed workspace."
             )
         available = ", ".join(entry.qualified_name for entry in index.entries)
-        raise ValueError(
+        raise WorkspaceProjectLookupMiss(
             f"Project '{project}' was not found in indexed cloud workspaces. "
             f"Available projects: {available}.{failed_note}"
         )
@@ -1212,6 +1347,9 @@ async def resolve_project_and_path(
         # Why: allow project-scoped memory URLs without requiring a separate project parameter
         # Outcome: attempt to resolve the prefix as a project and route to it
         if project_prefix:
+            # Deferred: ToolError lives in the mcp SDK, which must not load at CLI startup (#886).
+            from mcp.server.fastmcp.exceptions import ToolError
+
             if cached_project and _project_matches_identifier(cached_project, project_prefix):
                 resolved_project = await resolve_project_parameter(project_prefix, context=context)
                 if resolved_project and generate_permalink(resolved_project) != generate_permalink(
@@ -1438,6 +1576,9 @@ async def get_project_client(
         is_factory_mode,
     )
 
+    # Deferred: ToolError lives in the mcp SDK, which must not load at CLI startup (#886).
+    from mcp.server.fastmcp.exceptions import ToolError
+
     # When project_id (UUID) is provided, prefer it as the resolution identifier.
     # external_id is unambiguous across workspaces; project name can collide.
     project_identifier = project_id if project_id else project

src/basic_memory/mcp/resources/discovery.py

@@ -0,0 +1,17 @@
+"""Shared loader for the bundled cloud-discovery markdown resources."""
+
+from pathlib import Path
+
+
+def load_discovery_resource(filename: str) -> str:
+    """Read a bundled discovery markdown file with promo placeholders rendered.
+
+    The markdown carries a {{OSS_DISCOUNT_CODE}} placeholder so the promo code
+    has one source of truth (cli.promo); substitute before it reaches users.
+    """
+    # Import here to avoid pulling CLI promo machinery (analytics, rich, config)
+    # into the MCP server import graph at module load.
+    from basic_memory.cli.promo import OSS_DISCOUNT_CODE
+
+    content = (Path(__file__).parent / filename).read_text(encoding="utf-8")
+    return content.replace("{{OSS_DISCOUNT_CODE}}", OSS_DISCOUNT_CODE)

src/basic_memory/mcp/tools/__init__.py

@@ -36,11 +36,7 @@ from basic_memory.mcp.tools.chatgpt_tools import search, fetch
 # Schema tools
 from basic_memory.mcp.tools.schema import schema_validate, schema_infer, schema_diff
 
-# Diagnostics tool
-from basic_memory.mcp.tools.basic_memory_diagnostics import basic_memory_diagnostics
-
 __all__ = [
-    "basic_memory_diagnostics",
     "build_context",
     "canvas",
     "cloud_info",

src/basic_memory/mcp/tools/basic_memory_diagnostics.py

@@ -1,132 +0,0 @@
-"""Diagnostic tool for Basic Memory version and system information."""
-
-import json
-import platform
-import sys
-from urllib.parse import urlparse, urlunparse
-
-import basic_memory
-from basic_memory.config import CONFIG_FILE_NAME, ConfigManager
-from basic_memory.mcp.server import mcp
-
-# Fields in BasicMemoryConfig that contain secrets and must never be surfaced.
-_SECRET_FIELDS = frozenset({"cloud_api_key"})
-
-# Fields whose values are URLs that may embed user:password credentials.
-# The userinfo component is stripped before surfacing.
-_URL_FIELDS = frozenset({"database_url"})
-
-
-def _redact_url(url: str) -> str:
-    """Strip the userinfo (user:password) from a URL string.
-
-    Replaces any credentials with *** so the host/path remain visible for
-    diagnostics (e.g. ``postgresql://***@localhost/mydb``).  If the value
-    cannot be parsed as a URL it is returned unchanged.
-    """
-    try:
-        parsed = urlparse(url)
-    except Exception:  # pragma: no cover — urlparse is very permissive
-        return url
-
-    if not parsed.hostname:
-        # Not a meaningful URL (e.g. a bare file path); leave it alone.
-        return url
-
-    if parsed.username or parsed.password:
-        # Rebuild with credentials replaced by a placeholder.
-        netloc = f"***@{parsed.hostname}"
-        if parsed.port:
-            netloc = f"{netloc}:{parsed.port}"
-        redacted = parsed._replace(netloc=netloc)
-        return urlunparse(redacted)
-
-    return url
-
-
-def _redact_config(raw: dict) -> dict:
-    """Return a copy of the raw config dict with secret fields removed.
-
-    - Keys in ``_SECRET_FIELDS`` are dropped entirely.
-    - Keys in ``_URL_FIELDS`` have their userinfo component stripped so that
-      host and database name remain visible for diagnostics.
-
-    Only top-level keys are processed. Nested keys within project entries are
-    not currently credential-bearing, but the two sets make the pattern easy
-    to extend.
-    """
-    result: dict = {}
-    for k, v in raw.items():
-        if k in _SECRET_FIELDS:
-            # Drop entirely — value has no diagnostic value.
-            continue
-        if k in _URL_FIELDS and isinstance(v, str):
-            result[k] = _redact_url(v)
-        else:
-            result[k] = v
-    return result
-
-
-@mcp.tool(
-    "basic_memory_diagnostics",
-    title="Basic Memory Diagnostics",
-    tags={"diagnostics"},
-    annotations={"readOnlyHint": True, "openWorldHint": False},
-    # The report is a markdown string; suppress FastMCP's wrap_result so the
-    # payload isn't duplicated into structuredContent.
-    output_schema=None,
-)
-def basic_memory_diagnostics() -> str:
-    """Return version, system, and configuration diagnostics for Basic Memory.
-
-    Provides:
-    - Basic Memory package version
-    - Python version and platform details
-    - Config file path and its contents (secrets redacted)
-
-    Useful for troubleshooting installations and gathering information for
-    support requests. Read-only; never emits secrets or API keys.
-    """
-    # --- Version information ---
-    bm_version = basic_memory.__version__
-
-    # --- System information ---
-    python_version = sys.version
-    platform_info = platform.platform()
-    machine = platform.machine()
-
-    # --- Configuration ---
-    manager = ConfigManager()
-    config_file = manager.config_dir / CONFIG_FILE_NAME
-    config_exists = config_file.exists()
-
-    if config_exists:
-        try:
-            raw_config = json.loads(config_file.read_text(encoding="utf-8"))
-            safe_config = _redact_config(raw_config)
-            config_dump = json.dumps(safe_config, indent=2, default=str)
-        except Exception as exc:  # pragma: no cover
-            config_dump = f"<error reading config: {exc}>"
-    else:
-        config_dump = "<config file not found>"
-
-    lines = [
-        "# Basic Memory Diagnostics",
-        "",
-        "## Version",
-        f"- basic-memory: {bm_version}",
-        "",
-        "## System",
-        f"- Python: {python_version}",
-        f"- Platform: {platform_info}",
-        f"- Architecture: {machine}",
-        "",
-        "## Configuration",
-        f"- Config path: {config_file}",
-        f"- Config exists: {config_exists}",
-        "",
-        "```json",
-        config_dump,
-        "```",
-    ]
-    return "\n".join(lines)

src/basic_memory/mcp/tools/build_context.py

@@ -54,7 +54,10 @@ def _format_entity_block(result: ContextResult) -> str:
         lines.append("")
         lines.append("### Relations")
         for rel in relation_items:
-            lines.append(f"- {rel.relation_type} [[{rel.to_entity}]]")
+            # Unresolved forward references have no resolved entity yet; fall back
+            # to the literal target text instead of rendering [[None]] (#955)
+            target = rel.to_entity or rel.to_name
+            lines.append(f"- {rel.relation_type} [[{target}]]")
 
     # --- Related entities (non-relation related results) ---
     related_entities: list[EntitySummary | ObservationSummary] = [
@@ -112,6 +115,7 @@ def _format_context_markdown(graph: GraphContext, project: str) -> str:
 
 
 @mcp.tool(
+    title="Build Context",
     description="""Build context from a memory:// URI to continue conversations naturally.
 
     Use this to follow up on previous discussions or explore related topics.
@@ -131,6 +135,7 @@ def _format_context_markdown(graph: GraphContext, project: str) -> str:
     - "json" (default): Structured JSON with internal fields excluded
     - "text": Compact markdown text for LLM consumption
     """,
+    tags={"navigation", "notes"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def build_context(

src/basic_memory/mcp/tools/canvas.py

@@ -17,7 +17,9 @@ from basic_memory.mcp.tools.utils import call_put, call_post, resolve_entity_id
 
 
 @mcp.tool(
+    title="Create Canvas",
     description="Create an Obsidian canvas file to visualize concepts and connections.",
+    tags={"canvas", "notes"},
     annotations={"destructiveHint": False, "idempotentHint": True, "openWorldHint": False},
 )
 async def canvas(

src/basic_memory/mcp/tools/chatgpt_tools.py

@@ -105,7 +105,9 @@ def _format_document_for_chatgpt(
 
 
 @mcp.tool(
+    title="Search Knowledge Base",
     description="Search for content across the knowledge base",
+    tags={"search"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def search(
@@ -167,7 +169,9 @@ async def search(
 
 
 @mcp.tool(
+    title="Fetch Document",
     description="Fetch the full contents of a search result document",
+    tags={"search", "notes"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def fetch(

src/basic_memory/mcp/tools/cloud_info.py

@@ -1,15 +1,15 @@
 """Cloud information MCP tool."""
 
-from pathlib import Path
-
+from basic_memory.mcp.resources.discovery import load_discovery_resource
 from basic_memory.mcp.server import mcp
 
 
 @mcp.tool(
     "cloud_info",
+    title="Cloud Info",
+    tags={"cloud"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 def cloud_info() -> str:
     """Return optional Basic Memory Cloud information and setup guidance."""
-    content_path = Path(__file__).parent.parent / "resources" / "cloud_info.md"
-    return content_path.read_text(encoding="utf-8")
+    return load_discovery_resource("cloud_info.md")

src/basic_memory/mcp/tools/delete_note.py

@@ -182,7 +182,9 @@ def _directory_path_for_delete(
 
 
 @mcp.tool(
+    title="Delete Note",
     description="Delete a note or directory by title, permalink, or path",
+    tags={"notes"},
     annotations={"destructiveHint": True, "openWorldHint": False},
 )
 async def delete_note(

src/basic_memory/mcp/tools/edit_note.py

@@ -304,7 +304,9 @@ Error editing note '{identifier}': {error_message}
 
 
 @mcp.tool(
+    title="Edit Note",
     description="Edit an existing markdown note using various operations like append, prepend, find_replace, replace_section, insert_before_section, or insert_after_section.",
+    tags={"notes"},
     annotations={"destructiveHint": False, "openWorldHint": False},
 )
 async def edit_note(

src/basic_memory/mcp/tools/list_directory.py

@@ -11,7 +11,9 @@ from basic_memory.mcp.server import mcp
 
 
 @mcp.tool(
+    title="List Directory",
     description="List directory contents with filtering and depth control.",
+    tags={"navigation", "notes"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def list_directory(

src/basic_memory/mcp/tools/move_note.py

@@ -357,7 +357,9 @@ delete_note("{identifier}")
 
 
 @mcp.tool(
+    title="Move Note",
     description="Move a note or directory to a new location, updating database and maintaining links.",
+    tags={"notes"},
     annotations={"destructiveHint": False, "openWorldHint": False},
 )
 async def move_note(

src/basic_memory/mcp/tools/project_management.py

@@ -357,6 +357,8 @@ def _format_project_list_json(
 
 @mcp.tool(
     "list_memory_projects",
+    title="List Memory Projects",
+    tags={"projects"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def list_memory_projects(
@@ -475,10 +477,14 @@ async def _resolve_workspace_routing(
     if workspace is None:
         return None
 
-    explicit_cloud_routing = _explicit_routing() and not _force_local_mode()
+    forced_local = _explicit_routing() and _force_local_mode()
     config = ConfigManager().config
+    # Resolve whenever credentials make workspace discovery possible — not only
+    # under explicit --cloud. A workspace selector implies cloud routing
+    # (get_client routes it to the cloud proxy, #954), and the transport needs
+    # the tenant id in X-Workspace-ID, not a slug or display name.
     should_resolve_workspace = is_factory_mode() or (
-        explicit_cloud_routing and has_cloud_credentials(config)
+        has_cloud_credentials(config) and not forced_local
     )
     if not should_resolve_workspace:
         return workspace
@@ -495,6 +501,8 @@ async def _resolve_workspace_routing(
 
 @mcp.tool(
     "create_memory_project",
+    title="Create Memory Project",
+    tags={"projects"},
     annotations={"destructiveHint": False, "openWorldHint": False},
 )
 async def create_memory_project(
@@ -517,8 +525,9 @@ async def create_memory_project(
         workspace: Optional cloud workspace selector to create the project in. Slug is
             preferred for AI callers, but tenant_id and unique name are also accepted.
             When omitted, the connection's default workspace is used. Discover values
-            via `list_workspaces`. In local mode the selector is passed through
-            without slug resolution.
+            via `list_workspaces`. A workspace selector implies cloud routing:
+            without cloud credentials the call fails fast instead of silently
+            creating a local project (#954).
         output_format: "text" returns the existing human-readable result text.
             "json" returns structured project creation metadata.
         context: Optional FastMCP context for progress/status logging.
@@ -636,6 +645,8 @@ async def create_memory_project(
 
 
 @mcp.tool(
+    title="Delete Project",
+    tags={"projects"},
     annotations={"destructiveHint": True, "openWorldHint": False},
 )
 async def delete_project(
@@ -654,8 +665,9 @@ async def delete_project(
         workspace: Optional cloud workspace selector to delete the project from.
             Slug is preferred for AI callers, but tenant_id and unique name are
             also accepted. When omitted, the connection's default workspace is
-            used. In local mode the selector is passed through without slug
-            resolution, matching create_memory_project behavior.
+            used. A workspace selector implies cloud routing: without cloud
+            credentials the call fails fast, matching create_memory_project
+            behavior (#954).
 
     Returns:
         Confirmation message about project deletion

src/basic_memory/mcp/tools/read_content.py

@@ -155,7 +155,9 @@ def optimize_image(img, content_length, max_output_bytes=350000):
 
 
 @mcp.tool(
+    title="Read Content",
     description="Read a file's raw content by path or permalink",
+    tags={"notes"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def read_content(

src/basic_memory/mcp/tools/read_note.py

@@ -74,7 +74,9 @@ def _parse_opening_frontmatter(content: str) -> tuple[str, dict | None]:
 
 
 @mcp.tool(
+    title="Read Note",
     description="Read a markdown note by title or permalink.",
+    tags={"notes"},
     # TODO: re-enable once MCP client rendering is working
     # meta={"ui/resourceUri": "ui://basic-memory/note-preview"},
     annotations={"readOnlyHint": True, "openWorldHint": False},

src/basic_memory/mcp/tools/recent_activity.py

@@ -26,6 +26,7 @@ from basic_memory.schemas.search import SearchItemType
 
 
 @mcp.tool(
+    title="Recent Activity",
     description="""Get recent activity for a project or across all projects.
 
     Timeframe supports natural language formats like:
@@ -36,6 +37,7 @@ from basic_memory.schemas.search import SearchItemType
     - "3 weeks ago"
     Or standard formats like "7d"
     """,
+    tags={"navigation", "notes"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def recent_activity(

src/basic_memory/mcp/tools/release_notes.py

@@ -1,15 +1,15 @@
 """Release notes MCP tool."""
 
-from pathlib import Path
-
+from basic_memory.mcp.resources.discovery import load_discovery_resource
 from basic_memory.mcp.server import mcp
 
 
 @mcp.tool(
     "release_notes",
+    title="Release Notes",
+    tags={"cloud"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 def release_notes() -> str:
     """Return the latest product release notes for optional user review."""
-    content_path = Path(__file__).parent.parent / "resources" / "release_notes.md"
-    return content_path.read_text(encoding="utf-8")
+    return load_discovery_resource("release_notes.md")

src/basic_memory/mcp/tools/schema.py

@@ -204,7 +204,9 @@ def _no_schema_guidance(note_type: str, tool_name: str) -> str:
 
 
 @mcp.tool(
+    title="Validate Schema",
     description="Validate notes against their Picoschema definitions.",
+    tags={"schema"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def schema_validate(
@@ -317,7 +319,9 @@ async def schema_validate(
 
 
 @mcp.tool(
+    title="Infer Schema",
     description="Analyze existing notes and suggest a Picoschema definition.",
+    tags={"schema"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def schema_infer(
@@ -438,7 +442,9 @@ async def schema_infer(
 
 
 @mcp.tool(
+    title="Schema Diff",
     description="Detect drift between a schema definition and actual note usage.",
+    tags={"schema"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def schema_diff(

src/basic_memory/mcp/tools/search.py

@@ -14,7 +14,7 @@ from basic_memory.config import ConfigManager, has_cloud_credentials
 from basic_memory.utils import (
     build_canonical_permalink,
     coerce_dict,
-    coerce_list,
+    parse_str_list,
     parse_tags,
     strict_search_tags,
 )
@@ -612,7 +612,9 @@ async def _search_all_projects(
 
 
 @mcp.tool(
+    title="Search Notes",
     description="Search across all content in the knowledge base with advanced syntax support.",
+    tags={"search"},
     # TODO: re-enable once MCP client rendering is working
     # meta={"ui/resourceUri": "ui://basic-memory/search-results"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
@@ -649,24 +651,30 @@ async def search_notes(
     # Plural-vs-singular trips models constantly. Accept the singular too.
     note_types: Annotated[
         List[str] | None,
-        BeforeValidator(coerce_list),
+        # parse_str_list, not coerce_list: "note,task" must split into ["note", "task"]
+        # consistent with how tags are handled (#910/#930). coerce_list wraps the whole
+        # comma string as the single literal type ["note,task"], which matches nothing.
+        BeforeValidator(parse_str_list),
         Field(default=None, validation_alias=AliasChoices("note_types", "note_type", "types")),
         "Filter by the 'type' field in note frontmatter (e.g. 'note', 'chapter', 'person'). "
+        "Accepts a list, a comma-separated string (e.g. 'note,task'), or a JSON-array string. "
         "Case-insensitive.",
     ] = None,
     entity_types: Annotated[
         List[str] | None,
-        BeforeValidator(coerce_list),
+        BeforeValidator(parse_str_list),
         Field(default=None, validation_alias=AliasChoices("entity_types", "entity_type")),
         "Filter by knowledge graph item type: 'entity' (whole notes), 'observation', or "
         "'relation'. Defaults to 'entity'. Do NOT pass schema/frontmatter types like "
-        "'Chapter' here — use note_types instead.",
+        "'Chapter' here — use note_types instead. "
+        "Accepts a list, a comma-separated string (e.g. 'entity,observation'), or a JSON-array string.",
     ] = None,
     categories: Annotated[
         List[str] | None,
-        BeforeValidator(coerce_list),
+        BeforeValidator(parse_str_list),
         Field(default=None, validation_alias=AliasChoices("categories", "category")),
         "Filter observation results to these exact categories (e.g. ['requirement']). "
+        "Accepts a list, a comma-separated string (e.g. 'requirement,decision'), or a JSON-array string. "
         "Pair with entity_types=['observation'] to return only observations whose "
         "category matches exactly — not every row mentioning the word.",
     ] = None,
@@ -820,6 +828,11 @@ async def search_notes(
         Formatted markdown text (output_format="text"), dict (output_format="json"),
         or helpful error guidance string if search fails
 
+        Pagination note: `total` is exact only for text/title/permalink searches.
+        Vector and hybrid searches skip the count query (it would cost a second
+        semantic retrieval pass) and report `total: 0` even when results are
+        returned — use `has_more` for pagination in those modes.
+
     Examples:
         # Basic text search
         results = await search_notes("project planning")
@@ -893,6 +906,17 @@ async def search_notes(
     if page_size < 1:
         raise ValueError(f"page_size must be >= 1, got {page_size}")
 
+    # Trigger: list params arrived via a direct function call instead of the MCP layer.
+    # Why: the BeforeValidator annotations only run through MCP/Pydantic validation; direct
+    #      callers (e.g. `bm tool search-notes --type note,task` in cli/commands/tool.py,
+    #      which Typer collects as the one-element list ["note,task"]) would otherwise
+    #      forward the comma string as one literal type that matches nothing (#930).
+    # Outcome: comma-split/list normalization applies on every path; parse_str_list is
+    #          idempotent, so MCP-validated input passes through unchanged.
+    note_types = parse_str_list(note_types) if note_types is not None else []
+    entity_types = parse_str_list(entity_types) if entity_types is not None else []
+    categories = parse_str_list(categories) if categories is not None else []
+
     # Avoid mutable-default-argument footguns. Treat None as "no filter".
     # Lowercase note_types so "Chapter" matches the stored "chapter".
     note_types = [t.lower() for t in note_types] if note_types else []

src/basic_memory/mcp/tools/ui_sdk.py

@@ -18,7 +18,9 @@ def _text_block(message: str) -> List[ContentBlock]:
 
 
 @mcp.tool(
+    title="Search Notes (UI)",
     description="Search notes and return an embedded MCP-UI resource (raw HTML).",
+    tags={"search", "ui"},
     output_schema=None,
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
@@ -92,7 +94,9 @@ async def search_notes_ui(
 
 
 @mcp.tool(
+    title="Read Note (UI)",
     description="Read a note and return an embedded MCP-UI resource (raw HTML).",
+    tags={"notes", "ui"},
     output_schema=None,
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )

src/basic_memory/mcp/tools/view_note.py

@@ -11,7 +11,9 @@ from basic_memory.mcp.tools.read_note import read_note
 
 
 @mcp.tool(
+    title="View Note",
     description="View a note as a formatted artifact for better readability.",
+    tags={"notes"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def view_note(

src/basic_memory/mcp/tools/workspaces.py

@@ -45,7 +45,9 @@ def _workspace_list_response(workspaces: list[WorkspaceInfo]) -> WorkspaceListRe
 
 
 @mcp.tool(
+    title="List Workspaces",
     description="List available cloud workspaces (tenant_id, type, role, and name).",
+    tags={"cloud", "projects"},
     annotations={"readOnlyHint": True, "openWorldHint": False},
 )
 async def list_workspaces(

src/basic_memory/mcp/tools/write_note.py

@@ -25,8 +25,39 @@ from basic_memory.workspace_context import current_workspace_permalink_context
 TagType = Union[List[str], str, None]
 
 
+def _compose_workspace_project_route(
+    *,
+    workspace: Optional[str],
+    project: Optional[str],
+    project_id: Optional[str],
+) -> Optional[str]:
+    """Return the explicit project route requested by workspace/project args."""
+    if workspace is None:
+        return project
+
+    cleaned_workspace = workspace.strip().strip("/")
+    if not cleaned_workspace:
+        raise ValueError("workspace must not be empty when provided")
+    if "/" in cleaned_workspace:
+        raise ValueError("workspace must be a single workspace slug, name, or tenant_id")
+    if project_id is not None:
+        raise ValueError("workspace cannot be combined with project_id; use project_id alone")
+    if project is None or not project.strip().strip("/"):
+        raise ValueError("workspace requires an explicit project argument")
+
+    cleaned_project = project.strip().strip("/")
+    if "/" in cleaned_project:
+        raise ValueError(
+            "Use either workspace='workspace' with project='project', "
+            "or project='workspace/project', not both"
+        )
+    return f"{cleaned_workspace}/{cleaned_project}"
+
+
 @mcp.tool(
+    title="Write Note",
     description="Create a markdown note. If the note already exists, returns an error by default — pass overwrite=True to replace.",
+    tags={"notes"},
     annotations={"destructiveHint": True, "idempotentHint": False, "openWorldHint": False},
 )
 async def write_note(
@@ -38,6 +69,7 @@ async def write_note(
         Field(validation_alias=AliasChoices("directory", "folder", "dir", "path")),
     ],
     project: Optional[str] = None,
+    workspace: Optional[str] = None,
     project_id: Optional[str] = None,
     tags: list[str] | str | None = None,
     note_type: str = "note",
@@ -93,6 +125,8 @@ async def write_note(
                 form (or project_id) to disambiguate. If unknown, use
                 list_memory_projects() to discover available projects and their
                 qualified names.
+        workspace: Workspace slug, name, or tenant_id. When provided with `project`,
+                routes as `workspace/project`. Cannot be combined with `project_id`.
         project_id: Project external_id (UUID). Prefer this over `project` when known —
                 it routes to the exact project regardless of name collisions across cloud
                 workspaces. Takes precedence over `project`. Get from list_memory_projects().
@@ -170,6 +204,11 @@ async def write_note(
     effective_overwrite = (
         overwrite if overwrite is not None else ConfigManager().config.write_note_overwrite_default
     )
+    project = _compose_workspace_project_route(
+        workspace=workspace,
+        project=project,
+        project_id=project_id,
+    )
 
     with logfire.span(
         "mcp.tool.write_note",

src/basic_memory/repository/postgres_search_repository.py

@@ -18,6 +18,7 @@ from basic_memory.repository.search_index_row import SearchIndexRow
 from basic_memory.repository.search_repository_base import (
     SearchRepositoryBase,
     VectorChunkState,
+    relaxed_query_words,
 )
 from basic_memory.repository.metadata_filters import parse_metadata_filters
 from basic_memory.repository.semantic_errors import SemanticDependenciesMissingError
@@ -176,6 +177,14 @@ class PostgresSearchRepository(SearchRepositoryBase):
         # For non-Boolean queries, prepare single term
         return self._prepare_single_term(term, is_prefix)
 
+    @staticmethod
+    def _relaxed_tsquery_text(search_text: Optional[str]) -> Optional[str]:
+        """OR-relaxed tsquery expression for a failed strict query, or None."""
+        words = relaxed_query_words(search_text)
+        if not words:
+            return None
+        return " | ".join(f"{word}:*" for word in words)
+
     def _prepare_boolean_query(self, query: str) -> str:
         """Convert Boolean query to tsquery format.
 
@@ -236,7 +245,12 @@ class PostgresSearchRepository(SearchRepositoryBase):
 
         # Handle multi-word queries
         if " " in cleaned_term:
-            words = [w for w in cleaned_term.split() if w.strip()]
+            # Strip sentence punctuation from word edges so question-form
+            # queries produce clean lexemes (parity with SQLite FTS5 prep).
+            # The tsquery tokenizer ignores this punctuation anyway; leaving it
+            # in only risks tsquery syntax errors. Interior characters are kept.
+            words = [w.strip("?!.,;") for w in cleaned_term.split()]
+            words = [w for w in words if w]
             if not words:
                 # All characters were special chars, search won't match anything
                 # Return a safe search term that won't cause syntax errors
@@ -249,8 +263,11 @@ class PostgresSearchRepository(SearchRepositoryBase):
             # Join with AND operator
             return " & ".join(prepared_words)
 
-        # Single word
-        cleaned_term = cleaned_term.strip()
+        # Single word: strip edge punctuation; guard the now-empty case so a
+        # bare ":*"/"" never reaches tsquery.
+        cleaned_term = cleaned_term.strip().strip("?!.,;")
+        if not cleaned_term:
+            return "NOSPECIALCHARS:*"
         if is_prefix:
             return f"{cleaned_term}:*"
         else:
@@ -908,6 +925,7 @@ class PostgresSearchRepository(SearchRepositoryBase):
         min_similarity: Optional[float] = None,
         limit: int = 10,
         offset: int = 0,
+        allow_relaxed: bool = False,
     ) -> List[SearchIndexRow]:
         """Search across all indexed content using PostgreSQL tsvector."""
         # --- Dispatch vector / hybrid modes (shared logic) ---
@@ -982,6 +1000,20 @@ class PostgresSearchRepository(SearchRepositoryBase):
             async with db.scoped_session(self.session_maker) as session:
                 result = await session.execute(text(sql), params)
                 rows = result.fetchall()
+                # Trigger: multi-word natural-language query matched nothing
+                # under the default all-terms-AND tsquery semantics.
+                # Why: questions rarely have every word in one document;
+                # without relaxation the FTS half of hybrid search contributes
+                # zero candidates (parity with the SQLite path).
+                # Outcome: one retry with OR-joined prefix lexemes; ts_rank
+                # still ranks multi-term matches first.
+                relaxed = (
+                    self._relaxed_tsquery_text(search_text) if allow_relaxed and not rows else None
+                )
+                if relaxed and params.get("text"):
+                    params["text"] = relaxed
+                    result = await session.execute(text(sql), params)
+                    rows = result.fetchall()
         except Exception as e:
             if self._is_tsquery_syntax_error(e):
                 logger.warning(f"tsquery syntax error for search term: {search_text}, error: {e}")

src/basic_memory/repository/search_index_row.py

@@ -36,6 +36,7 @@ class SearchIndexRow:
     category: Optional[str] = None  # observations
     from_id: Optional[int] = None  # relations
     to_id: Optional[int] = None  # relations
+    to_name: Optional[str] = None  # relations: literal target text, set even when unresolved
     relation_type: Optional[str] = None  # relations
 
     # Matched chunk text from vector search (the actual content that matched the query)
@@ -94,6 +95,7 @@ class SearchIndexRow:
             else self.metadata,
             "from_id": self.from_id,
             "to_id": self.to_id,
+            "to_name": self.to_name,
             "relation_type": self.relation_type,
             "entity_id": self.entity_id,
             "category": self.category,

src/basic_memory/repository/search_repository_base.py

@@ -40,6 +40,55 @@ BULLET_PATTERN = re.compile(r"^[\-\*]\s+")
 OVERSIZED_ENTITY_VECTOR_SHARD_SIZE = 256
 _SQLITE_MAX_PREPARE_WINDOW = 8
 
+# Interrogative/function words contribute lexical noise when a strict
+# full-text query is relaxed: "when OR did OR a" matches loud wrong documents
+# that displace genuine results from the ranking window.
+RELAXATION_STOPWORDS = frozenset(
+    "a an and are as at be but by did do does for from had has have how i in is it of on "
+    "or that the their they this to was we were what when where which who whom whose why "
+    "will with you your".split()
+)
+
+
+def relaxed_query_words(search_text: Optional[str]) -> Optional[list[str]]:
+    """Content-bearing words for OR-relaxing a strict full-text query.
+
+    Returns None when relaxation must not apply. These eligibility rules match
+    SearchService._is_relaxed_fts_fallback_eligible so the hybrid FTS branch
+    relaxes exactly the same query shapes as the service-level FTS path:
+
+    - empty / quoted / explicit-boolean queries (user intent is not
+      second-guessed);
+    - fewer than three alphanumeric tokens (short queries like "New Feature"
+      over-broaden under OR — and in hybrid the relaxed FTS-only rows normalize
+      to 1.0 and can outrank the vector result the user wanted);
+    - any pure-digit token ("root note 1", "SPEC 16") — identifier-like queries
+      over-broaden and create false positives under OR.
+    """
+    if not search_text:
+        return None
+    stripped = search_text.strip()
+    if '"' in stripped or any(op in f" {stripped} " for op in (" AND ", " OR ", " NOT ")):
+        return None
+    # Eligibility checks run on raw alphanumeric tokens (parity with the
+    # service), before stopword filtering.
+    tokens = re.findall(r"[A-Za-z0-9]+", stripped.lower())
+    if len(tokens) < 3 or any(token.isdigit() for token in tokens):
+        return None
+    words = [word.strip("?!.,;:") for word in stripped.split()]
+    words = [
+        word
+        for word in words
+        if word and word.isalnum() and word.lower() not in RELAXATION_STOPWORDS
+    ]
+    return words or None
+
+
+# Entity, observation, and relation rows in search_index carry ids from independent
+# auto-increment sequences, so a bare id is ambiguous across row types. Every map in
+# the vector/hybrid retrieval path must key rows by (type, id) to avoid collisions.
+type SearchIndexKey = tuple[str, int]
+
 
 @dataclass
 class VectorSyncBatchResult:
@@ -224,6 +273,7 @@ class SearchRepositoryBase(ABC):
         min_similarity: Optional[float] = None,
         limit: int = 10,
         offset: int = 0,
+        allow_relaxed: bool = False,
     ) -> List[SearchIndexRow]:
         """Search across all indexed content.
 
@@ -1857,7 +1907,7 @@ class SearchRepositoryBase(ABC):
     # ------------------------------------------------------------------
 
     @staticmethod
-    def _parse_chunk_key(chunk_key: str) -> tuple[str, int]:
+    def _parse_chunk_key(chunk_key: str) -> SearchIndexKey:
         """Parse a chunk_key like 'observation:5:0' into (type, search_index_id)."""
         parts = chunk_key.split(":")
         return parts[0], int(parts[1])
@@ -1932,26 +1982,27 @@ class SearchRepositoryBase(ABC):
 
         hydrate_start = time.perf_counter()
         # Build per-search_index_row similarity scores from chunk-level results.
-        # Each chunk_key encodes the search_index row type and id.
+        # Each chunk_key encodes the search_index row type and id; keep both as the
+        # key because different row types can share the same numeric id (#982).
         # Track the best similarity per row (for ranking) and all chunks (for context).
-        similarity_by_si_id: dict[int, float] = {}
-        chunks_by_si_id: dict[int, list[tuple[float, str]]] = {}
+        similarity_by_si_key: dict[SearchIndexKey, float] = {}
+        chunks_by_si_key: dict[SearchIndexKey, list[tuple[float, str]]] = {}
         for row in vector_rows:
             chunk_key = row.get("chunk_key", "")
             distance = float(row["best_distance"])
             similarity = self._distance_to_similarity(distance)
             chunk_text = row.get("chunk_text", "")
             try:
-                _, si_id = self._parse_chunk_key(chunk_key)
+                si_key = self._parse_chunk_key(chunk_key)
             except (ValueError, IndexError):
                 # Fallback: group by entity_id for chunks without parseable keys
                 continue
-            current = similarity_by_si_id.get(si_id)
+            current = similarity_by_si_key.get(si_key)
             if current is None or similarity > current:
-                similarity_by_si_id[si_id] = similarity
-            chunks_by_si_id.setdefault(si_id, []).append((similarity, chunk_text))
+                similarity_by_si_key[si_key] = similarity
+            chunks_by_si_key.setdefault(si_key, []).append((similarity, chunk_text))
 
-        if not similarity_by_si_id:
+        if not similarity_by_si_key:
             hydrate_ms = (time.perf_counter() - hydrate_start) * 1000
             _log_vector_summary()
             return []
@@ -1962,16 +2013,17 @@ class SearchRepositoryBase(ABC):
             min_similarity if min_similarity is not None else self._semantic_min_similarity
         )
         if effective_min_similarity > 0.0:
-            similarity_by_si_id = {
-                k: v for k, v in similarity_by_si_id.items() if v >= effective_min_similarity
+            similarity_by_si_key = {
+                k: v for k, v in similarity_by_si_key.items() if v >= effective_min_similarity
             }
-            if not similarity_by_si_id:
+            if not similarity_by_si_key:
                 hydrate_ms = (time.perf_counter() - hydrate_start) * 1000
                 _log_vector_summary()
                 return []
 
-        # Fetch the actual search_index rows
-        si_ids = list(similarity_by_si_id.keys())
+        # Fetch the actual search_index rows. Colliding (type, id) keys share one
+        # bare id, so deduplicate while preserving first-seen order.
+        si_ids = list(dict.fromkeys(si_id for _, si_id in similarity_by_si_key))
         search_index_rows = await self._fetch_search_index_rows_by_ids(si_ids)
 
         # Apply optional filters if requested
@@ -2003,16 +2055,14 @@ class SearchRepositoryBase(ABC):
                 limit=VECTOR_FILTER_SCAN_LIMIT,
                 offset=0,
             )
-            # Use (id, type) tuples to avoid collisions between different
+            # Use (type, id) tuples to avoid collisions between different
             # search_index row types that share the same auto-increment id.
-            allowed_keys = {(row.id, row.type) for row in filtered_rows if row.id is not None}
-            search_index_rows = {
-                k: v for k, v in search_index_rows.items() if (v.id, v.type) in allowed_keys
-            }
+            allowed_keys = {(row.type, row.id) for row in filtered_rows if row.id is not None}
+            search_index_rows = {k: v for k, v in search_index_rows.items() if k in allowed_keys}
 
         ranked_rows: list[SearchIndexRow] = []
-        for si_id, similarity in similarity_by_si_id.items():
-            row = search_index_rows.get(si_id)
+        for si_key, similarity in similarity_by_si_key.items():
+            row = search_index_rows.get(si_key)
             if row is None:
                 continue
 
@@ -2022,7 +2072,7 @@ class SearchRepositoryBase(ABC):
             if content_snippet and len(content_snippet) <= SMALL_NOTE_CONTENT_LIMIT:
                 matched_chunk_text = content_snippet
             else:
-                si_chunks = chunks_by_si_id.get(si_id, [])
+                si_chunks = chunks_by_si_key.get(si_key, [])
                 si_chunks.sort(key=lambda c: c[0], reverse=True)
                 top_texts = [text for _, text in si_chunks[:TOP_CHUNKS_PER_RESULT]]
                 matched_chunk_text = "\n---\n".join(top_texts) if top_texts else None
@@ -2088,8 +2138,12 @@ class SearchRepositoryBase(ABC):
 
     async def _fetch_search_index_rows_by_ids(
         self, row_ids: list[int]
-    ) -> dict[int, SearchIndexRow]:
-        """Fetch search_index rows by their primary key (id), any type."""
+    ) -> dict[SearchIndexKey, SearchIndexRow]:
+        """Fetch search_index rows by id, keyed by (type, id) to disambiguate types.
+
+        A bare id can match one row per type (independent id sequences), so the
+        result must carry every matching row rather than letting one clobber another.
+        """
         if not row_ids:
             return {}
         placeholders = ",".join(f":id_{idx}" for idx in range(len(row_ids)))
@@ -2106,11 +2160,11 @@ class SearchRepositoryBase(ABC):
             WHERE project_id = :project_id
               AND id IN ({placeholders})
         """
-        result: dict[int, SearchIndexRow] = {}
+        result: dict[SearchIndexKey, SearchIndexRow] = {}
         async with db.scoped_session(self.session_maker) as session:
             row_result = await session.execute(text(sql), params)
             for row in row_result.fetchall():
-                result[row.id] = SearchIndexRow(
+                result[(row.type, row.id)] = SearchIndexRow(
                     project_id=self.project_id,
                     id=row.id,
                     title=row.title,
@@ -2156,7 +2210,7 @@ class SearchRepositoryBase(ABC):
     ) -> List[SearchIndexRow]:
         """Fuse FTS and vector results using score-based fusion.
 
-        Uses search_index row id as the fusion key. The formula
+        Uses the search_index (type, id) pair as the fusion key. The formula
         ``max(vec, fts) + FUSION_BONUS * min(vec, fts)`` preserves
         the dominant signal and rewards dual-source agreement.
         """
@@ -2165,6 +2219,9 @@ class SearchRepositoryBase(ABC):
         query_start = time.perf_counter()
         candidate_limit = max(self._semantic_vector_k, (limit + offset) * 10)
         fts_start = time.perf_counter()
+        # allow_relaxed: question-form queries rarely AND-match, and a dead FTS
+        # branch silently degrades hybrid to vector-only ranking. Fusion plus
+        # bm25 keep relaxed lexical candidates from dominating precision.
         fts_results = await self.search(
             search_text=search_text,
             permalink=permalink,
@@ -2178,6 +2235,7 @@ class SearchRepositoryBase(ABC):
             retrieval_mode=SearchRetrievalMode.FTS,
             limit=candidate_limit,
             offset=0,
+            allow_relaxed=True,
         )
         fts_ms = (time.perf_counter() - fts_start) * 1000
         vector_start = time.perf_counter()
@@ -2199,17 +2257,19 @@ class SearchRepositoryBase(ABC):
         vector_ms = (time.perf_counter() - vector_start) * 1000
         fusion_start = time.perf_counter()
 
-        # --- Score-based fusion keyed on search_index row id ---
+        # --- Score-based fusion keyed on (type, id) ---
+        # A bare row id collides across row types (independent id sequences), so
+        # fusion must key on (type, id) or distinct rows would merge (#982).
         # FTS scores are normalized to [0, 1] (BM25 is unbounded).
         # Vector scores are used raw — already calibrated [0, 1] by _distance_to_similarity().
-        rows_by_id: dict[int, SearchIndexRow] = {}
+        rows_by_key: dict[SearchIndexKey, SearchIndexRow] = {}
 
         # Normalize FTS scores to [0, 1] — handles both SQLite (negative bm25)
         # and Postgres (positive ts_rank) by using absolute values
         fts_abs = [abs(row.score or 0.0) for row in fts_results]
         fts_max = max(fts_abs) if fts_abs else 1.0
 
-        fts_scores: dict[int, float] = {}
+        fts_scores: dict[SearchIndexKey, float] = {}
         for row in fts_results:
             if row.id is None:
                 continue
@@ -2217,32 +2277,32 @@ class SearchRepositoryBase(ABC):
             # Gate: FTS scores below threshold contribute zero
             if norm < FTS_GATE_THRESHOLD:
                 norm = 0.0
-            fts_scores[row.id] = norm
-            rows_by_id[row.id] = row
+            fts_scores[(row.type, row.id)] = norm
+            rows_by_key[(row.type, row.id)] = row
 
-        vec_scores: dict[int, float] = {}
+        vec_scores: dict[SearchIndexKey, float] = {}
         for row in vector_results:
             if row.id is None:
                 continue
             # Trigger: no re-normalization by vec_max
             # Why: vector similarity is already calibrated [0, 1]; re-normalizing
             # inflates weak matches when the entire result set is mediocre
-            vec_scores[row.id] = row.score or 0.0
-            rows_by_id[row.id] = row
+            vec_scores[(row.type, row.id)] = row.score or 0.0
+            rows_by_key[(row.type, row.id)] = row
 
         # Fuse: max(v, f) + FUSION_BONUS * min(v, f)
         # Preserves the dominant signal; bonus rewards dual-source agreement.
         # Output range: [0, 1.3] for dual-source, [0, 1.0] for single-source.
-        fused_scores: dict[int, float] = {}
-        for row_id in fts_scores.keys() | vec_scores.keys():
-            v = vec_scores.get(row_id, 0.0)
-            f = fts_scores.get(row_id, 0.0)
-            fused_scores[row_id] = max(v, f) + FUSION_BONUS * min(v, f)
+        fused_scores: dict[SearchIndexKey, float] = {}
+        for row_key in fts_scores.keys() | vec_scores.keys():
+            v = vec_scores.get(row_key, 0.0)
+            f = fts_scores.get(row_key, 0.0)
+            fused_scores[row_key] = max(v, f) + FUSION_BONUS * min(v, f)
 
         ranked = sorted(fused_scores.items(), key=lambda item: item[1], reverse=True)
         output: list[SearchIndexRow] = []
-        for row_id, fused_score in ranked[offset : offset + limit]:
-            row = rows_by_id[row_id]
+        for row_key, fused_score in ranked[offset : offset + limit]:
+            row = rows_by_key[row_key]
             # Trigger: FTS-only results have no matched_chunk_text from vector search.
             # Why: without chunk text, API falls back to truncated content, losing answer text.
             # Outcome: FTS-only results get full content_snippet as matched_chunk.

src/basic_memory/repository/sqlite_search_repository.py

@@ -23,7 +23,10 @@ from basic_memory.models.search import (
 from basic_memory.repository.embedding_provider import EmbeddingProvider
 from basic_memory.repository.embedding_provider_factory import create_embedding_provider
 from basic_memory.repository.search_index_row import SearchIndexRow
-from basic_memory.repository.search_repository_base import SearchRepositoryBase
+from basic_memory.repository.search_repository_base import (
+    SearchRepositoryBase,
+    relaxed_query_words,
+)
 from basic_memory.repository.metadata_filters import parse_metadata_filters, build_sqlite_json_path
 from basic_memory.repository.semantic_errors import SemanticDependenciesMissingError
 from basic_memory.schemas.search import SearchItemType, SearchRetrievalMode
@@ -255,6 +258,19 @@ class SQLiteSearchRepository(SearchRepositoryBase):
         if "*" in term and all(c.isalnum() or c in "*_-" for c in term):
             return term
 
+        # Natural-language queries arrive with sentence punctuation that FTS5
+        # treats as syntax ("When did Melanie paint a sunrise?"). The tokenizer
+        # ignores this punctuation in the INDEX, so stripping it from word
+        # edges loses nothing — but leaving it forces the whole question into
+        # an exact-phrase match that returns zero rows, silently disabling the
+        # FTS half of hybrid search. Interior characters (hyphens, slashes —
+        # permalinks and paths) are untouched.
+        if " " in term:
+            words = [word.strip("?!.,;:") for word in term.split()]
+            term = " ".join(word for word in words if word)
+            if not term:
+                return ""
+
         # Characters that can cause FTS5 syntax errors when used as operators
         # We're more conservative here - only quote when we detect problematic patterns
         problematic_chars = [
@@ -351,6 +367,14 @@ class SQLiteSearchRepository(SearchRepositoryBase):
         # For non-Boolean queries, use the single term preparation logic
         return self._prepare_single_term(term, is_prefix)
 
+    @staticmethod
+    def _relaxed_fts_text(search_text: Optional[str]) -> Optional[str]:
+        """OR-relaxed FTS5 expression for a failed strict query, or None."""
+        words = relaxed_query_words(search_text)
+        if not words:
+            return None
+        return " OR ".join(f"{word}*" for word in words)
+
     # ------------------------------------------------------------------
     # sqlite-vec extension loading (SQLite-specific)
     # ------------------------------------------------------------------
@@ -953,8 +977,15 @@ class SQLiteSearchRepository(SearchRepositoryBase):
         min_similarity: Optional[float] = None,
         limit: int = 10,
         offset: int = 0,
+        allow_relaxed: bool = False,
     ) -> List[SearchIndexRow]:
-        """Search across all indexed content using SQLite FTS5."""
+        """Search across all indexed content using SQLite FTS5.
+
+        ``allow_relaxed=True`` retries a zero-result strict multi-word query
+        with OR-joined content terms. Only the hybrid path opts in: its FTS
+        branch otherwise contributes nothing for question-form queries.
+        Service-level FTS searches keep their own conservative fallback.
+        """
         # --- Dispatch vector / hybrid modes (shared logic) ---
         dispatched = await self._dispatch_retrieval_mode(
             search_text=search_text,
@@ -1021,6 +1052,21 @@ class SQLiteSearchRepository(SearchRepositoryBase):
             async with db.scoped_session(self.session_maker) as session:
                 result = await session.execute(text(sql), params)
                 rows = result.fetchall()
+                # Trigger: multi-word natural-language query matched nothing
+                # under the default all-terms-AND semantics.
+                # Why: questions ("when did X do Y") rarely have every word in
+                # one document; without relaxation the FTS half of hybrid
+                # search contributes zero candidates and ranking degrades to
+                # vector-only.
+                # Outcome: one retry with OR-joined prefix terms; bm25 still
+                # ranks multi-term matches first.
+                relaxed = (
+                    self._relaxed_fts_text(search_text) if allow_relaxed and not rows else None
+                )
+                if relaxed and params.get("text"):
+                    params["text"] = relaxed
+                    result = await session.execute(text(sql), params)
+                    rows = result.fetchall()
         except Exception as e:
             # Handle FTS5 syntax errors and provide user-friendly feedback
             if self._is_fts5_syntax_error(e):  # pragma: no cover

src/basic_memory/schemas/base.py

@@ -19,7 +19,6 @@ from pathlib import Path
 from typing import List, Optional, Annotated, Dict
 
 from annotated_types import MinLen, MaxLen
-from dateparser import parse
 
 from pydantic import BaseModel, BeforeValidator, Field, model_validator, computed_field
 
@@ -92,6 +91,10 @@ def parse_timeframe(timeframe: str) -> datetime:
         parse_timeframe('1d') -> 2025-06-04 14:50:00-07:00 (24 hours ago with local timezone)
         parse_timeframe('1 week ago') -> 2025-05-29 14:50:00-07:00 (1 week ago with local timezone)
     """
+    # Deferred: dateparser costs ~0.13s to import; schemas load on every CLI
+    # start, but timeframe parsing only happens per request (#886).
+    from dateparser import parse
+
     if timeframe.lower() == "today":
         # For "today", return 1 day ago to ensure we capture recent activity across timezones
         # This handles the case where client and server are in different timezones

src/basic_memory/schemas/memory.py

@@ -155,6 +155,9 @@ class RelationSummary(BaseModel):
     from_entity_id: Optional[int] = None
     from_entity_external_id: Optional[str] = None
     to_entity: Optional[str] = None
+    # Literal target text from the markdown; present even when the relation is
+    # an unresolved forward reference (to_entity is None until the target exists)
+    to_name: Optional[str] = None
     to_entity_id: Optional[int] = None
     to_entity_external_id: Optional[str] = None
     created_at: Annotated[

src/basic_memory/services/context_service.py

@@ -18,6 +18,7 @@ from basic_memory.repository.search_repository import SearchRepository, SearchIn
 from basic_memory.schemas.memory import MemoryUrl, memory_url_path
 from basic_memory.schemas.search import SearchItemType
 from basic_memory.utils import generate_permalink
+from basic_memory.workspace_context import workspace_slug_for_canonical_permalinks
 
 if TYPE_CHECKING:
     from basic_memory.services.link_resolver import LinkResolver
@@ -36,6 +37,7 @@ class ContextResultRow:
     from_id: Optional[int] = None
     to_id: Optional[int] = None
     relation_type: Optional[str] = None
+    to_name: Optional[str] = None
     content: Optional[str] = None
     category: Optional[str] = None
     entity_id: Optional[int] = None
@@ -143,6 +145,29 @@ class ContextService:
                         primary = await self.search_repository.search(
                             permalink_match=normalized_path, limit=fetch_limit, offset=offset
                         )
+
+                        # Trigger: a workspace-qualified pattern matched nothing while a
+                        #   workspace permalink context is active.
+                        # Why: rows written before workspace canonicalization (or via
+                        #   clients that didn't forward workspace headers) store
+                        #   project-qualified permalinks; a workspace-prefixed pattern
+                        #   can never match those legacy rows (#957).
+                        # Outcome: retry once with the workspace prefix stripped so the
+                        #   pattern matches the index form the rows actually carry.
+                        if not primary:
+                            workspace_slug = workspace_slug_for_canonical_permalinks()
+                            ws_prefix = f"{workspace_slug}/" if workspace_slug else None
+                            if ws_prefix and normalized_path.startswith(ws_prefix):
+                                fallback_path = normalized_path.removeprefix(ws_prefix)
+                                logger.debug(
+                                    f"Pattern search fallback without workspace prefix: "
+                                    f"'{fallback_path}'"
+                                )
+                                primary = await self.search_repository.search(
+                                    permalink_match=fallback_path,
+                                    limit=fetch_limit,
+                                    offset=offset,
+                                )
                     else:
                         normalized_path = generate_permalink(path, split_extension=False)
                         logger.debug(f"Direct lookup for '{normalized_path}'")
@@ -392,6 +417,7 @@ class ContextService:
                 from_id=row.from_id,
                 to_id=row.to_id,
                 relation_type=row.relation_type,
+                to_name=row.to_name,
                 content=row.content,
                 category=row.category,
                 entity_id=row.entity_id,
@@ -426,6 +452,7 @@ class ContextService:
                 CAST(NULL AS INTEGER) as from_id,
                 CAST(NULL AS INTEGER) as to_id,
                 CAST(NULL AS TEXT) as relation_type,
+                CAST(NULL AS TEXT) as to_name,
                 CAST(NULL AS TEXT) as content,
                 CAST(NULL AS TEXT) as category,
                 CAST(NULL AS INTEGER) as entity_id,
@@ -478,6 +505,10 @@ class ContextService:
                     WHEN step_type = 1 THEN r.relation_type
                     ELSE NULL
                 END as relation_type,
+                CASE
+                    WHEN step_type = 1 THEN r.to_name
+                    ELSE NULL
+                END as to_name,
                 CAST(NULL AS TEXT) as content,
                 CAST(NULL AS TEXT) as category,
                 CAST(NULL AS INTEGER) as entity_id,
@@ -541,6 +572,7 @@ class ContextService:
             from_id,
             to_id,
             relation_type,
+            to_name,
             content,
             category,
             entity_id,
@@ -550,7 +582,7 @@ class ContextService:
         FROM entity_graph
         WHERE depth > 0
         GROUP BY type, id, title, permalink, file_path, from_id, to_id,
-                 relation_type, content, category, entity_id, root_id, created_at
+                 relation_type, to_name, content, category, entity_id, root_id, created_at
         ORDER BY depth, type, id
         LIMIT :max_results
        """)
@@ -579,6 +611,7 @@ class ContextService:
                 NULL as from_id,
                 NULL as to_id,
                 NULL as relation_type,
+                NULL as to_name,
                 NULL as content,
                 NULL as category,
                 NULL as entity_id,
@@ -606,6 +639,7 @@ class ContextService:
                 r.from_id,
                 r.to_id,
                 r.relation_type,
+                r.to_name,
                 NULL as content,
                 NULL as category,
                 NULL as entity_id,
@@ -644,6 +678,7 @@ class ContextService:
                 NULL as from_id,
                 NULL as to_id,
                 NULL as relation_type,
+                NULL as to_name,
                 NULL as content,
                 NULL as category,
                 NULL as entity_id,
@@ -677,6 +712,7 @@ class ContextService:
             from_id,
             to_id,
             relation_type,
+            to_name,
             content,
             category,
             entity_id,
@@ -686,7 +722,7 @@ class ContextService:
         FROM entity_graph
         WHERE depth > 0
         GROUP BY type, id, title, permalink, file_path, from_id, to_id,
-                 relation_type, content, category, entity_id, root_id, created_at
+                 relation_type, to_name, content, category, entity_id, root_id, created_at
         ORDER BY depth, type, id
         LIMIT :max_results
        """)

src/basic_memory/services/initialization.py

@@ -13,7 +13,7 @@ from pathlib import Path
 from loguru import logger
 
 from basic_memory import db
-from basic_memory.config import BasicMemoryConfig, DatabaseBackend, ProjectMode
+from basic_memory.config import BasicMemoryConfig, DatabaseBackend
 from basic_memory.models import Project
 from basic_memory.repository import (
     ProjectRepository,
@@ -120,18 +120,14 @@ async def initialize_file_sync(
         active_projects = [p for p in active_projects if p.name == constrained_project]
         logger.info(f"Background sync constrained to project: {constrained_project}")
 
-    # Skip cloud-mode projects that have no local directory.
-    # Cloud projects with a local bisync copy (absolute path) are kept for local sync.
-    cloud_skip = []
-    for p in active_projects:
-        if app_config.get_project_mode(p.name) == ProjectMode.CLOUD:
-            entry = app_config.projects.get(p.name)
-            if entry and Path(entry.path).is_absolute():
-                continue  # Cloud project with local bisync copy — keep for local sync
-            cloud_skip.append(p.name)
-    if cloud_skip:
-        active_projects = [p for p in active_projects if p.name not in cloud_skip]
-        logger.info(f"Skipping cloud-mode projects for local sync: {cloud_skip}")
+    # Only sync projects that are in config (source of truth) and have an
+    # absolute local path; see BasicMemoryConfig.is_locally_syncable. This keeps
+    # background sync from adopting the process cwd as a project root and
+    # mutating unrelated files (issue #949).
+    skip = [p.name for p in active_projects if not app_config.is_locally_syncable(p.name, p.path)]
+    if skip:
+        active_projects = [p for p in active_projects if p.name not in skip]
+        logger.info(f"Skipping projects that are not locally syncable for sync: {skip}")
 
     # Start sync for all projects as background tasks (non-blocking)
     async def sync_project_background(project: Project):

src/basic_memory/services/project_service.py

@@ -256,6 +256,41 @@ class ProjectService:
             await self.repository.set_as_default(created_project.id)
             self.config_manager.set_default_project(name)
             logger.info(f"Project '{name}' set as default")
+        else:
+            config_default = self.config_manager.default_project
+            if config_default is not None:
+                db_default_project = await self.repository.get_by_name(config_default)
+                if db_default_project is None:
+                    # Trigger: config names a default project that has no database row
+                    #      (the fresh-config wedge from issue #974).
+                    # Why: synchronize_projects treats an existing database default as
+                    #      authoritative, so a surviving default must win over promoting
+                    #      the just-added project. set_default_project raises for names
+                    #      absent from config — and reconciliation deletes such rows —
+                    #      so a database default unknown to config cannot be repointed to.
+                    # Outcome: config is repointed at a usable database default when one
+                    #      exists; otherwise the added project becomes the default.
+                    db_default = await self.repository.get_default_project()
+                    if (
+                        db_default is not None
+                        and self.config_manager.get_project(db_default.name)[0] is not None
+                    ):
+                        self.config_manager.set_default_project(db_default.name)
+                        logger.info(
+                            "Repointed config default from missing '%s' at existing "
+                            "database default '%s'",
+                            config_default,
+                            db_default.name,
+                        )
+                    else:
+                        await self.repository.set_as_default(created_project.id)
+                        self.config_manager.set_default_project(name)
+                        logger.info(
+                            "Promoted project '%s' to default because configured default '%s' "
+                            "is missing from database",
+                            name,
+                            config_default,
+                        )
 
         logger.info(f"Project '{name}' added at {resolved_path}")
 

src/basic_memory/sync/watch_service.py

@@ -10,7 +10,7 @@ from typing import List, Optional, Set, Sequence, Callable, Awaitable, TYPE_CHEC
 if TYPE_CHECKING:
     from basic_memory.sync.sync_service import SyncService
 
-from basic_memory.config import BasicMemoryConfig, ProjectMode, WATCH_STATUS_JSON
+from basic_memory.config import BasicMemoryConfig, WATCH_STATUS_JSON
 from basic_memory.ignore_utils import load_gitignore_patterns, should_ignore_path
 from basic_memory.models import Project
 from basic_memory.repository import ProjectRepository
@@ -184,24 +184,24 @@ class WatchService:
              ``--project``, only that project is watched. This keeps concurrent
              MCP processes from producing duplicate watchers that race on the
              same files.
-          2. Cloud-only projects without a local bisync copy are skipped so we
-             don't watch a path that does not exist on disk.
+          2. Projects that are not locally syncable are skipped — those missing
+             from config (config is the source of truth, so stale DB rows must
+             not be watched) or with a non-absolute path (which would resolve
+             against the process cwd and make the watcher observe and mutate the
+             directory the server was launched from). See
+             ``BasicMemoryConfig.is_locally_syncable`` (issue #949). Cloud
+             projects with a local bisync copy keep their absolute path and are
+             still watched.
         """
         projects = await self.project_repository.get_active_projects()
 
         if self.constrained_project:
             projects = [p for p in projects if p.name == self.constrained_project]
 
-        cloud_skip: list[str] = []
-        for p in projects:
-            if self.app_config.get_project_mode(p.name) == ProjectMode.CLOUD:
-                entry = self.app_config.projects.get(p.name)
-                if entry and Path(entry.path).is_absolute():
-                    continue  # Cloud project with local bisync copy — keep watching
-                cloud_skip.append(p.name)
-        if cloud_skip:
-            projects = [p for p in projects if p.name not in cloud_skip]
-            logger.debug(f"Skipping cloud-mode projects in watch cycle: {cloud_skip}")
+        skip = [p.name for p in projects if not self.app_config.is_locally_syncable(p.name, p.path)]
+        if skip:
+            projects = [p for p in projects if p.name not in skip]
+            logger.debug(f"Skipping projects that are not locally syncable in watch cycle: {skip}")
 
         return list(projects)
 

src/basic_memory/utils.py

@@ -600,6 +600,62 @@ def strict_search_tags(v: Any) -> Any:
     return v
 
 
+def parse_str_list(v: Any) -> List[str]:
+    """Parse a list of plain strings from various input formats.
+
+    Like parse_tags but without stripping '#' — correct for type/category params
+    where the value is a literal identifier, not a hashtag.
+
+    Handles the four input shapes that MCP clients commonly produce:
+    - None → []
+    - "note,task" → ["note", "task"] (comma-split string)
+    - '["note","task"]' → ["note", "task"] (JSON array string)
+    - ["note,task"] → ["note", "task"] (list with comma-string element)
+
+    Non-str/list/None values are returned unchanged so Pydantic can reject them
+    with a clear validation error instead of silently coercing.
+    """
+    if v is None:
+        return []
+
+    if isinstance(v, list):
+        # Trigger: a list element is not a string (e.g. [42] or ["note", 42]).
+        # Why: str(raw) would silently convert 42 → "42" and let invalid caller data pass
+        #   Pydantic validation as a junk filter, producing a silent no-result search.
+        # Outcome: return the list unchanged so Pydantic rejects it with a clear error.
+        if not all(isinstance(raw, str) for raw in v if raw is not None):
+            return v  # type: ignore[return-value]
+
+        # Trigger: a list element may itself be a comma-separated string (e.g. some MCP clients
+        #   serialise `["note,task"]` when the caller passed `note_types="note,task"`).
+        # Outcome: flatten each element by splitting on commas and stripping whitespace.
+        return [
+            item.strip()
+            for raw in v
+            if raw is not None
+            for item in raw.split(",")
+            if item and item.strip()
+        ]
+
+    if isinstance(v, str):
+        # Trigger: MCP clients sometimes send a JSON array string like '["note","task"]'.
+        # Outcome: parse it as JSON first, then recurse to handle the resulting list.
+        stripped = v.strip()
+        if stripped.startswith("[") and stripped.endswith("]"):
+            try:
+                parsed_json = json.loads(stripped)
+                if isinstance(parsed_json, list):
+                    return parse_str_list(parsed_json)
+            except json.JSONDecodeError:
+                pass
+
+        # Plain comma-separated string: "note,task" → ["note", "task"]
+        return [item.strip() for item in v.split(",") if item and item.strip()]
+
+    # Non-str/list/None — return unchanged so Pydantic rejects with a clear error.
+    return v  # type: ignore[return-value]
+
+
 def coerce_list(v: Any) -> Any:
     """Coerce string input to list for MCP clients that serialize lists as strings."""
     if v is None:

test-int/cli/test_routing_integration.py

@@ -89,6 +89,27 @@ class TestRoutingFlagsValidation:
         assert "Cannot specify both --local and --cloud" in result.output
 
 
+def _stub_auto_update(monkeypatch, mcp_mod) -> None:
+    """Keep `bm mcp` stdio tests from running the real background auto-update.
+
+    The command starts a daemon thread before mcp_server.run; unstubbed it hits
+    PyPI and rewrites config.json from a background thread, leaking into later
+    tests in the same process (#940's KeyError flake on test_mcp_sse_forces_local).
+    """
+    from basic_memory.cli.auto_update import AutoUpdateResult, AutoUpdateStatus, InstallSource
+
+    def skipped_auto_update(**kwargs) -> AutoUpdateResult:
+        return AutoUpdateResult(
+            status=AutoUpdateStatus.SKIPPED,
+            source=InstallSource.UNKNOWN,
+            checked=False,
+            update_available=False,
+            updated=False,
+        )
+
+    monkeypatch.setattr(mcp_mod, "run_auto_update", skipped_auto_update)
+
+
 class TestMcpCommandRouting:
     """Tests that MCP routing varies by transport."""
 
@@ -109,8 +130,10 @@ class TestMcpCommandRouting:
 
         monkeypatch.setattr(mcp_mod.mcp_server, "run", mock_run)
         monkeypatch.setattr(mcp_mod, "init_mcp_logging", lambda: None)
+        _stub_auto_update(monkeypatch, mcp_mod)
 
-        runner.invoke(cli_app, ["mcp"])  # default transport is stdio
+        result = runner.invoke(cli_app, ["mcp"])  # default transport is stdio
+        assert result.exit_code == 0, result.output
 
         # Command should not have set these vars
         assert env_at_run["FORCE_LOCAL"] is None
@@ -132,8 +155,10 @@ class TestMcpCommandRouting:
 
         monkeypatch.setattr(mcp_mod.mcp_server, "run", mock_run)
         monkeypatch.setattr(mcp_mod, "init_mcp_logging", lambda: None)
+        _stub_auto_update(monkeypatch, mcp_mod)
 
-        runner.invoke(cli_app, ["mcp"])
+        result = runner.invoke(cli_app, ["mcp"])
+        assert result.exit_code == 0, result.output
 
         # Externally-set vars should be preserved
         assert env_at_run["FORCE_CLOUD"] == "true"
@@ -153,7 +178,8 @@ class TestMcpCommandRouting:
         monkeypatch.setattr(mcp_mod.mcp_server, "run", mock_run)
         monkeypatch.setattr(mcp_mod, "init_mcp_logging", lambda: None)
 
-        runner.invoke(cli_app, ["mcp", "--transport", "streamable-http"])
+        result = runner.invoke(cli_app, ["mcp", "--transport", "streamable-http"])
+        assert result.exit_code == 0, result.output
 
         assert env_at_run["FORCE_LOCAL"] == "true"
         assert env_at_run["EXPLICIT"] == "true"
@@ -172,7 +198,8 @@ class TestMcpCommandRouting:
         monkeypatch.setattr(mcp_mod.mcp_server, "run", mock_run)
         monkeypatch.setattr(mcp_mod, "init_mcp_logging", lambda: None)
 
-        runner.invoke(cli_app, ["mcp", "--transport", "sse"])
+        result = runner.invoke(cli_app, ["mcp", "--transport", "sse"])
+        assert result.exit_code == 0, result.output
 
         assert env_at_run["FORCE_LOCAL"] == "true"
         assert env_at_run["EXPLICIT"] == "true"

test-int/mcp/test_project_management_integration.py

@@ -591,36 +591,35 @@ async def test_nested_project_paths_rejected(mcp_server, app, test_project, tmp_
 
 
 @pytest.mark.asyncio
-async def test_create_project_accepts_workspace_in_local_mode(
+async def test_create_project_workspace_without_credentials_fails_fast(
     mcp_server, app, test_project, tmp_path
 ):
-    """Passing workspace via the MCP wire is accepted by the tool schema and
-    does not break the local create path.
+    """A workspace selector without cloud credentials fails fast — no local create (#954).
 
-    In local mode there is no cloud factory installed, so workspace is a no-op:
-    the request lands on the ASGI transport which has no workspace concept. This
-    test guards the schema so a future change can't accidentally drop the parameter.
+    The previous contract treated workspace as a local no-op, which was the bug:
+    a caller asking for a cloud team workspace got a silent local project. The
+    tool schema still accepts the parameter (this test exercises it over the
+    MCP wire), but the create must error with auth guidance and leave no
+    project behind.
     """
+    from fastmcp.exceptions import ToolError
 
     async with Client(mcp_server) as client:
-        create_result = await client.call_tool(
-            "create_memory_project",
-            {
-                "project_name": "ws-local-test",
-                "project_path": str(
-                    tmp_path.parent / (tmp_path.name + "-projects") / "project-ws-local-test"
-                ),
-                "workspace": "team-paul",
-            },
-        )
-
-        assert len(create_result.content) == 1
-        create_text = create_result.content[0].text  # pyright: ignore [reportAttributeAccessIssue]
-        assert "✓" in create_text
-        assert "ws-local-test" in create_text
+        with pytest.raises(ToolError, match="cloud workspace was requested"):
+            await client.call_tool(
+                "create_memory_project",
+                {
+                    "project_name": "ws-local-test",
+                    "project_path": str(
+                        tmp_path.parent / (tmp_path.name + "-projects") / "project-ws-local-test"
+                    ),
+                    "workspace": "team-paul",
+                },
+            )
 
+        # The failed create must not leave a local project behind
         list_result = await client.call_tool("list_memory_projects", {})
-        assert "ws-local-test" in list_result.content[0].text  # pyright: ignore [reportAttributeAccessIssue]
+        assert "ws-local-test" not in list_result.content[0].text  # pyright: ignore [reportAttributeAccessIssue]
 
 
 @pytest.mark.asyncio

tests/api/v2/test_project_router.py

@@ -6,6 +6,7 @@ from pathlib import Path
 import pytest
 from httpx import AsyncClient
 
+from basic_memory.config import ProjectEntry
 from basic_memory.models import Project
 from basic_memory.schemas.project_info import ProjectItem, ProjectStatusResponse
 from basic_memory.schemas.v2 import ProjectResolveResponse
@@ -54,6 +55,46 @@ async def test_get_project_by_id_not_found(client: AsyncClient, v2_projects_url)
     assert "not found" in response.json()["detail"].lower()
 
 
+@pytest.mark.asyncio
+async def test_add_project_response_reflects_promoted_default(
+    client: AsyncClient,
+    v2_projects_url,
+    app_config,
+    config_manager,
+    config_home,
+    project_repository,
+):
+    """Regression #974/#985: POST response should echo persisted default promotion."""
+    main_home = config_home / "basic-memory"
+    main_home.mkdir(parents=True, exist_ok=True)
+    qa_path = config_home / "qa-notes"
+    qa_path.mkdir(parents=True, exist_ok=True)
+
+    fresh_config = app_config.model_copy(
+        update={
+            "projects": {"main": ProjectEntry(path=str(main_home))},
+            "default_project": "main",
+        }
+    )
+    config_manager.save_config(fresh_config)
+
+    for project in await project_repository.find_all():
+        await project_repository.delete(project.id)
+
+    response = await client.post(
+        f"{v2_projects_url}/",
+        json={"name": "qa", "path": str(qa_path), "set_default": False},
+    )
+
+    assert response.status_code == 201
+    status_response = ProjectStatusResponse.model_validate(response.json())
+    assert status_response.status == "success"
+    assert status_response.default is True
+    new_project = _project_item(status_response.new_project)
+    assert new_project.name == "qa"
+    assert new_project.is_default is True
+
+
 @pytest.mark.asyncio
 async def test_update_project_path_by_id(
     client: AsyncClient, test_project: Project, v2_projects_url
@@ -137,6 +178,37 @@ async def test_set_default_project_by_id(
     assert old_project.is_default is False
 
 
+@pytest.mark.asyncio
+async def test_set_default_project_when_none_is_set(
+    client: AsyncClient, test_project: Project, v2_projects_url, project_repository
+):
+    """Regression for #975: setting a default must succeed when none is set.
+
+    This is the bootstrap/recovery case: `bm project default <name>` is exactly
+    the command reached for when no default exists, so the endpoint must not 404.
+    """
+    # Clear any existing default so no row has is_default set.
+    await project_repository.update(test_project.id, {"is_default": None})
+    assert await project_repository.get_default_project() is None
+
+    response = await client.put(f"{v2_projects_url}/{test_project.external_id}/default")
+
+    assert response.status_code == 200
+    status_response = ProjectStatusResponse.model_validate(response.json())
+    assert status_response.status == "success"
+    assert status_response.default is True
+    # No previous default existed, so old_project must be None.
+    assert status_response.old_project is None
+    new_project = _project_item(status_response.new_project)
+    assert new_project.external_id == test_project.external_id
+    assert new_project.is_default is True
+
+    # A follow-up read-back must now return the newly set default.
+    default_project = await project_repository.get_default_project()
+    assert default_project is not None
+    assert default_project.external_id == test_project.external_id
+
+
 @pytest.mark.asyncio
 async def test_set_default_project_not_found(client: AsyncClient, v2_projects_url):
     """Test setting a non-existent project as default returns 404."""
@@ -373,6 +445,41 @@ async def test_resolve_project_not_found(client: AsyncClient, v2_projects_url):
     assert "not found" in response.json()["detail"].lower()
 
 
+@pytest.mark.asyncio
+async def test_resolve_project_not_found_fresh_install_names_setup_command(
+    client: AsyncClient, v2_projects_url, project_repository
+):
+    """#974 follow-up: a fresh install fails its first read with a bare not-found.
+
+    config.json bootstraps a "main" default before any reconciliation has created
+    database rows (the one-shot CLI never runs the server lifespan), so resolving
+    the configured default 404s. With an empty projects table the error must point
+    at first-run setup instead of reading like a broken install.
+    """
+    for project in await project_repository.find_all():
+        await project_repository.delete(project.id)
+
+    response = await client.post(f"{v2_projects_url}/resolve", json={"identifier": "main"})
+
+    assert response.status_code == 404
+    detail = response.json()["detail"]
+    assert detail.startswith("Project not found: 'main'")
+    assert "basic-memory project add" in detail
+
+
+@pytest.mark.asyncio
+async def test_resolve_project_not_found_with_projects_keeps_plain_message(
+    client: AsyncClient, test_project: Project, v2_projects_url
+):
+    """A miss against a populated projects table stays a plain not-found."""
+    response = await client.post(
+        f"{v2_projects_url}/resolve", json={"identifier": "nonexistent-project"}
+    )
+
+    assert response.status_code == 404
+    assert response.json()["detail"] == "Project not found: 'nonexistent-project'"
+
+
 @pytest.mark.asyncio
 async def test_resolve_project_empty_identifier(client: AsyncClient, v2_projects_url):
     """Test resolving with empty identifier returns 422."""

tests/cli/test_auto_update.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import subprocess
+import sys
 from datetime import datetime, timedelta, timezone
 from io import StringIO
 from typing import Any, cast
@@ -15,6 +16,7 @@ from basic_memory.cli.auto_update import (
     InstallSource,
     _check_homebrew_update_available,
     _is_interactive_session,
+    _preload_lazy_console_modules,
     detect_install_source,
     maybe_run_periodic_auto_update,
     run_auto_update,
@@ -159,6 +161,19 @@ def test_check_homebrew_update_available_exit_code_0_means_up_to_date(monkeypatc
     assert is_outdated is False
 
 
+def test_preload_lazy_console_modules_imports_deferred_modules(monkeypatch):
+    # Regression: the in-place upgrade deletes the running install's files, so
+    # any module rich/typer defers until print time must already be loaded or
+    # the final status message crashes with ModuleNotFoundError.
+    monkeypatch.delitem(sys.modules, "rich._emoji_codes", raising=False)
+    monkeypatch.delitem(sys.modules, "typer.rich_utils", raising=False)
+
+    _preload_lazy_console_modules()
+
+    assert "rich._emoji_codes" in sys.modules
+    assert "typer.rich_utils" in sys.modules
+
+
 def test_homebrew_outdated_triggers_upgrade(monkeypatch, tmp_path):
     config = _base_config(tmp_path)
     manager = StubConfigManager(config)

tests/cli/test_ci_commands.py

@@ -219,8 +219,8 @@ def test_setup_does_not_partially_write_generated_files_when_target_exists(
     mock_seed.assert_not_awaited()
 
 
-@patch("basic_memory.cli.commands.ci.mcp_search_notes", new_callable=AsyncMock)
-@patch("basic_memory.cli.commands.ci.mcp_write_note", new_callable=AsyncMock)
+@patch("basic_memory.mcp.tools.search_notes", new_callable=AsyncMock)
+@patch("basic_memory.mcp.tools.write_note", new_callable=AsyncMock)
 async def test_seed_project_update_schemas_skips_existing_notes_by_default(
     mock_write: AsyncMock,
     mock_search: AsyncMock,
@@ -235,8 +235,8 @@ async def test_seed_project_update_schemas_skips_existing_notes_by_default(
     mock_write.assert_not_awaited()
 
 
-@patch("basic_memory.cli.commands.ci.mcp_search_notes", new_callable=AsyncMock)
-@patch("basic_memory.cli.commands.ci.mcp_write_note", new_callable=AsyncMock)
+@patch("basic_memory.mcp.tools.search_notes", new_callable=AsyncMock)
+@patch("basic_memory.mcp.tools.write_note", new_callable=AsyncMock)
 async def test_seed_project_update_schemas_refreshes_existing_notes(
     mock_write: AsyncMock,
     mock_search: AsyncMock,
@@ -327,8 +327,8 @@ def test_agent_schema_command_writes_schema(tmp_path: Path) -> None:
     assert schema["title"] == "AgentSynthesis"
 
 
-@patch("basic_memory.cli.commands.ci.mcp_search_notes", new_callable=AsyncMock)
-@patch("basic_memory.cli.commands.ci.mcp_write_note", new_callable=AsyncMock)
+@patch("basic_memory.mcp.tools.search_notes", new_callable=AsyncMock)
+@patch("basic_memory.mcp.tools.write_note", new_callable=AsyncMock)
 def test_publish_command_upserts_project_update_note(
     mock_write: AsyncMock,
     mock_search: AsyncMock,
@@ -401,8 +401,8 @@ def test_publish_command_upserts_project_update_note(
     )
 
 
-@patch("basic_memory.cli.commands.ci.mcp_search_notes", new_callable=AsyncMock)
-@patch("basic_memory.cli.commands.ci.mcp_write_note", new_callable=AsyncMock)
+@patch("basic_memory.mcp.tools.search_notes", new_callable=AsyncMock)
+@patch("basic_memory.mcp.tools.write_note", new_callable=AsyncMock)
 def test_publish_command_preserves_existing_note_path_for_idempotency_match(
     mock_write: AsyncMock,
     mock_search: AsyncMock,
@@ -464,8 +464,8 @@ def test_publish_command_preserves_existing_note_path_for_idempotency_match(
     assert kwargs["directory"] == "custom/project-updates"
 
 
-@patch("basic_memory.cli.commands.ci.mcp_search_notes", new_callable=AsyncMock)
-@patch("basic_memory.cli.commands.ci.mcp_write_note", new_callable=AsyncMock)
+@patch("basic_memory.mcp.tools.search_notes", new_callable=AsyncMock)
+@patch("basic_memory.mcp.tools.write_note", new_callable=AsyncMock)
 def test_publish_command_uses_project_id_without_workspace_qualifying_project(
     mock_write: AsyncMock,
     mock_search: AsyncMock,

tests/cli/test_cli_exit.py

@@ -86,6 +86,46 @@ def test_bm_version_does_not_import_heavy_modules():
     )
 
 
+def test_bm_cli_import_does_not_load_heavy_stack():
+    """Regression test (#886): registering all CLI commands must stay lightweight.
+
+    Importing basic_memory.cli.main with a normal argv registers every command
+    module. None of them may pull FastAPI, the API app, SQLAlchemy/Alembic, the
+    MCP tool stack, or the markdown/services layers in at import time — those
+    must load lazily when a command actually runs.
+    """
+    heavy_modules = (
+        "fastapi",
+        "sqlalchemy",
+        "alembic",
+        "fastmcp",
+        "mcp",
+        "basic_memory.api.app",
+        "basic_memory.db",
+        "basic_memory.markdown",
+        "basic_memory.mcp.tools",
+        "basic_memory.services",
+    )
+    check_script = (
+        "import sys; "
+        "sys.argv = ['bm', 'tool', 'search-notes', '--help']; "
+        "import basic_memory.cli.main; "
+        f"heavy = [m for m in {heavy_modules!r} if m in sys.modules]; "
+        "print(','.join(heavy) if heavy else 'CLEAN')"
+    )
+    result = subprocess.run(
+        ["uv", "run", "python", "-c", check_script],
+        capture_output=True,
+        text=True,
+        timeout=20,
+        cwd=Path(__file__).parent.parent.parent,
+    )
+    assert result.returncode == 0
+    assert "CLEAN" in result.stdout, (
+        f"Heavy modules loaded during CLI import: {result.stdout.strip()}"
+    )
+
+
 def test_bm_help_does_not_import_api_app():
     """Regression test: 'bm --help' must not build the FastAPI app graph."""
     check_script = (

tests/cli/test_cli_schema.py

@@ -87,7 +87,7 @@ def _mock_config_manager():
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_validate",
+    "basic_memory.mcp.tools.schema_validate",
     new_callable=AsyncMock,
     return_value=VALIDATE_REPORT,
 )
@@ -108,7 +108,7 @@ def test_validate_renders_table(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_validate",
+    "basic_memory.mcp.tools.schema_validate",
     new_callable=AsyncMock,
     return_value=VALIDATE_REPORT,
 )
@@ -123,7 +123,7 @@ def test_validate_strict_exits_on_errors(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_validate",
+    "basic_memory.mcp.tools.schema_validate",
     new_callable=AsyncMock,
     return_value={"error": "No notes found of type 'person'"},
 )
@@ -139,7 +139,7 @@ def test_validate_error_response(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_validate",
+    "basic_memory.mcp.tools.schema_validate",
     new_callable=AsyncMock,
     return_value=VALIDATE_REPORT,
 )
@@ -159,7 +159,7 @@ def test_validate_identifier_heuristic(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_infer",
+    "basic_memory.mcp.tools.schema_infer",
     new_callable=AsyncMock,
     return_value=INFER_REPORT,
 )
@@ -179,7 +179,7 @@ def test_infer_renders_table(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_infer",
+    "basic_memory.mcp.tools.schema_infer",
     new_callable=AsyncMock,
     return_value=INFER_REPORT,
 )
@@ -195,7 +195,7 @@ def test_infer_threshold_passthrough(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_infer",
+    "basic_memory.mcp.tools.schema_infer",
     new_callable=AsyncMock,
     return_value={"error": "No schema pattern found for 'person' (threshold: 25%)"},
 )
@@ -211,7 +211,7 @@ def test_infer_error_response(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_infer",
+    "basic_memory.mcp.tools.schema_infer",
     new_callable=AsyncMock,
     return_value={
         "note_type": "person",
@@ -238,7 +238,7 @@ def test_infer_zero_notes(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_diff",
+    "basic_memory.mcp.tools.schema_diff",
     new_callable=AsyncMock,
     return_value=DIFF_REPORT_WITH_DRIFT,
 )
@@ -259,7 +259,7 @@ def test_diff_renders_drift(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_diff",
+    "basic_memory.mcp.tools.schema_diff",
     new_callable=AsyncMock,
     return_value=DIFF_REPORT_NO_DRIFT,
 )
@@ -275,7 +275,7 @@ def test_diff_no_drift(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_diff",
+    "basic_memory.mcp.tools.schema_diff",
     new_callable=AsyncMock,
     return_value={"error": "No schema found for type 'person'"},
 )

tests/cli/test_cli_tool_json_output.py

@@ -98,7 +98,7 @@ SEARCH_RESULT = {
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_write_note",
+    "basic_memory.mcp.tools.write_note",
     new_callable=AsyncMock,
     return_value=WRITE_NOTE_RESULT,
 )
@@ -129,7 +129,7 @@ def test_write_note_json_output(mock_mcp_write):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_write_note",
+    "basic_memory.mcp.tools.write_note",
     new_callable=AsyncMock,
     return_value=WRITE_NOTE_RESULT,
 )
@@ -161,7 +161,7 @@ def test_write_note_project_id_passthrough(mock_mcp_write):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_write_note",
+    "basic_memory.mcp.tools.write_note",
     new_callable=AsyncMock,
     return_value=WRITE_NOTE_RESULT,
 )
@@ -190,7 +190,7 @@ def test_write_note_with_tags(mock_mcp_write):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_write_note",
+    "basic_memory.mcp.tools.write_note",
     new_callable=AsyncMock,
     return_value=WRITE_NOTE_RESULT,
 )
@@ -217,7 +217,7 @@ def test_write_note_type_passthrough(mock_mcp_write):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_write_note",
+    "basic_memory.mcp.tools.write_note",
     new_callable=AsyncMock,
     return_value=WRITE_NOTE_RESULT,
 )
@@ -245,7 +245,7 @@ def test_write_note_type_defaults_to_note(mock_mcp_write):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_read_note",
+    "basic_memory.mcp.tools.read_note",
     new_callable=AsyncMock,
     return_value=READ_NOTE_RESULT,
 )
@@ -267,7 +267,7 @@ def test_read_note_json_output(mock_mcp_read):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_read_note",
+    "basic_memory.mcp.tools.read_note",
     new_callable=AsyncMock,
     return_value=READ_NOTE_RESULT,
 )
@@ -286,7 +286,7 @@ def test_read_note_include_frontmatter(mock_mcp_read):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_delete_note",
+    "basic_memory.mcp.tools.delete_note",
     new_callable=AsyncMock,
     return_value=DELETE_NOTE_RESULT,
 )
@@ -307,7 +307,7 @@ def test_delete_note_json_output(mock_mcp_delete: AsyncMock) -> None:
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_delete_note",
+    "basic_memory.mcp.tools.delete_note",
     new_callable=AsyncMock,
     return_value=DELETE_DIRECTORY_RESULT,
 )
@@ -325,7 +325,7 @@ def test_delete_note_directory_flag(mock_mcp_delete: AsyncMock) -> None:
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_delete_note",
+    "basic_memory.mcp.tools.delete_note",
     new_callable=AsyncMock,
     return_value={
         "deleted": False,
@@ -349,7 +349,7 @@ def test_delete_note_not_found_outputs_json(mock_mcp_delete: AsyncMock) -> None:
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_delete_note",
+    "basic_memory.mcp.tools.delete_note",
     new_callable=AsyncMock,
     return_value={
         "deleted": False,
@@ -371,7 +371,7 @@ def test_delete_note_error_response(mock_mcp_delete: AsyncMock) -> None:
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_delete_note",
+    "basic_memory.mcp.tools.delete_note",
     new_callable=AsyncMock,
     return_value={
         "deleted": False,
@@ -398,7 +398,7 @@ def test_delete_note_directory_partial_failure_exits_nonzero(
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_delete_note",
+    "basic_memory.mcp.tools.delete_note",
     new_callable=AsyncMock,
     return_value=DELETE_NOTE_RESULT,
 )
@@ -418,7 +418,7 @@ def test_delete_note_project_id_passthrough(mock_mcp_delete: AsyncMock) -> None:
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_edit_note",
+    "basic_memory.mcp.tools.edit_note",
     new_callable=AsyncMock,
     return_value=EDIT_NOTE_RESULT,
 )
@@ -446,7 +446,7 @@ def test_edit_note_json_output(mock_mcp_edit):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_edit_note",
+    "basic_memory.mcp.tools.edit_note",
     new_callable=AsyncMock,
     return_value={"title": "Test", "permalink": "test", "error": "Edit failed: not found"},
 )
@@ -472,7 +472,7 @@ def test_edit_note_error_response(mock_mcp_edit):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_build_context",
+    "basic_memory.mcp.tools.build_context",
     new_callable=AsyncMock,
     return_value=BUILD_CONTEXT_RESULT,
 )
@@ -491,7 +491,7 @@ def test_build_context_json_output(mock_build_ctx):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_build_context",
+    "basic_memory.mcp.tools.build_context",
     new_callable=AsyncMock,
     return_value=BUILD_CONTEXT_RESULT,
 )
@@ -526,7 +526,7 @@ def test_build_context_with_options(mock_build_ctx):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_recent_activity",
+    "basic_memory.mcp.tools.recent_activity",
     new_callable=AsyncMock,
     return_value=RECENT_ACTIVITY_RESULT,
 )
@@ -548,7 +548,7 @@ def test_recent_activity_json_output(mock_mcp_recent):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_recent_activity",
+    "basic_memory.mcp.tools.recent_activity",
     new_callable=AsyncMock,
     return_value=RECENT_ACTIVITY_RESULT,
 )
@@ -566,7 +566,7 @@ def test_recent_activity_pagination(mock_mcp_recent):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_recent_activity",
+    "basic_memory.mcp.tools.recent_activity",
     new_callable=AsyncMock,
     return_value=[],
 )
@@ -586,7 +586,7 @@ def test_recent_activity_empty(mock_mcp_recent):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_search",
+    "basic_memory.mcp.tools.search_notes",
     new_callable=AsyncMock,
     return_value=SEARCH_RESULT,
 )
@@ -606,7 +606,7 @@ def test_search_notes_json_output(mock_mcp_search):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_search",
+    "basic_memory.mcp.tools.search_notes",
     new_callable=AsyncMock,
     return_value=SEARCH_RESULT,
 )
@@ -622,7 +622,7 @@ def test_search_notes_with_meta_filter(mock_mcp_search):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_search",
+    "basic_memory.mcp.tools.search_notes",
     new_callable=AsyncMock,
     return_value=SEARCH_RESULT,
 )
@@ -638,7 +638,7 @@ def test_search_notes_permalink_mode(mock_mcp_search):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_search",
+    "basic_memory.mcp.tools.search_notes",
     new_callable=AsyncMock,
     return_value="Error: search failed",
 )
@@ -699,7 +699,7 @@ SCHEMA_VALIDATE_RESULT = {
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_schema_validate",
+    "basic_memory.mcp.tools.schema_validate",
     new_callable=AsyncMock,
     return_value=SCHEMA_VALIDATE_RESULT,
 )
@@ -719,7 +719,7 @@ def test_schema_validate_json_output(mock_mcp):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_schema_validate",
+    "basic_memory.mcp.tools.schema_validate",
     new_callable=AsyncMock,
     return_value=SCHEMA_VALIDATE_RESULT,
 )
@@ -736,7 +736,7 @@ def test_schema_validate_identifier_heuristic(mock_mcp):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_schema_validate",
+    "basic_memory.mcp.tools.schema_validate",
     new_callable=AsyncMock,
     return_value={"error": "No notes found of type 'person'"},
 )
@@ -769,7 +769,7 @@ SCHEMA_INFER_RESULT = {
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_schema_infer",
+    "basic_memory.mcp.tools.schema_infer",
     new_callable=AsyncMock,
     return_value=SCHEMA_INFER_RESULT,
 )
@@ -789,7 +789,7 @@ def test_schema_infer_json_output(mock_mcp):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_schema_infer",
+    "basic_memory.mcp.tools.schema_infer",
     new_callable=AsyncMock,
     return_value=SCHEMA_INFER_RESULT,
 )
@@ -818,7 +818,7 @@ SCHEMA_DIFF_RESULT = {
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_schema_diff",
+    "basic_memory.mcp.tools.schema_diff",
     new_callable=AsyncMock,
     return_value=SCHEMA_DIFF_RESULT,
 )
@@ -860,7 +860,7 @@ LIST_PROJECTS_RESULT = {
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_list_projects",
+    "basic_memory.mcp.tools.list_memory_projects",
     new_callable=AsyncMock,
     return_value=LIST_PROJECTS_RESULT,
 )
@@ -898,7 +898,7 @@ LIST_WORKSPACES_RESULT = {
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_list_workspaces",
+    "basic_memory.mcp.tools.list_workspaces",
     new_callable=AsyncMock,
     return_value=LIST_WORKSPACES_RESULT,
 )
@@ -919,7 +919,7 @@ def test_list_workspaces_json_output(mock_mcp):
 
 
 @patch(
-    "basic_memory.cli.commands.tool.mcp_list_workspaces",
+    "basic_memory.mcp.tools.list_workspaces",
     new_callable=AsyncMock,
     return_value={"workspaces": [], "count": 0},
 )

tests/cli/test_db_reindex.py

@@ -195,15 +195,21 @@ async def test_reindex_project_full_passes_force_full_to_sync_and_reports_mode(m
             if "total" in kwargs:
                 self.tasks[task_id].total = kwargs["total"]
 
-    monkeypatch.setattr(db_cmd, "reconcile_projects_with_config", AsyncMock())
+    # _reindex imports its database/sync dependencies at call time (#886),
+    # so stubs target the source modules instead of db_cmd attributes.
     monkeypatch.setattr(
-        db_cmd.db,
-        "get_or_create_db",
+        "basic_memory.services.initialization.reconcile_projects_with_config", AsyncMock()
+    )
+    monkeypatch.setattr(
+        "basic_memory.db.get_or_create_db",
         AsyncMock(return_value=(None, session_maker)),
     )
-    monkeypatch.setattr(db_cmd.db, "shutdown_db", AsyncMock())
-    monkeypatch.setattr(db_cmd, "ProjectRepository", StubProjectRepository)
-    monkeypatch.setattr(db_cmd, "get_sync_service", AsyncMock(return_value=sync_service))
+    monkeypatch.setattr("basic_memory.db.shutdown_db", AsyncMock())
+    monkeypatch.setattr("basic_memory.repository.ProjectRepository", StubProjectRepository)
+    monkeypatch.setattr(
+        "basic_memory.sync.sync_service.get_sync_service",
+        AsyncMock(return_value=sync_service),
+    )
     monkeypatch.setattr(db_cmd, "Progress", SilentProgress)
     monkeypatch.setattr(
         db_cmd.console,
@@ -277,14 +283,17 @@ async def test_reindex_embeddings_only_full_passes_force_full_to_vector_reindex(
             if "total" in kwargs:
                 self.tasks[task_id].total = kwargs["total"]
 
-    monkeypatch.setattr(db_cmd, "reconcile_projects_with_config", AsyncMock())
+    # _reindex imports its database/sync dependencies at call time (#886),
+    # so stubs target the source modules instead of db_cmd attributes.
     monkeypatch.setattr(
-        db_cmd.db,
-        "get_or_create_db",
+        "basic_memory.services.initialization.reconcile_projects_with_config", AsyncMock()
+    )
+    monkeypatch.setattr(
+        "basic_memory.db.get_or_create_db",
         AsyncMock(return_value=(None, session_maker)),
     )
-    monkeypatch.setattr(db_cmd.db, "shutdown_db", AsyncMock())
-    monkeypatch.setattr(db_cmd, "ProjectRepository", StubProjectRepository)
+    monkeypatch.setattr("basic_memory.db.shutdown_db", AsyncMock())
+    monkeypatch.setattr("basic_memory.repository.ProjectRepository", StubProjectRepository)
     monkeypatch.setattr(
         "basic_memory.repository.search_repository.create_search_repository",
         lambda *args, **kwargs: object(),

tests/cli/test_json_output.py

@@ -368,7 +368,7 @@ def test_status_wait_json_timeout_emits_error(
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_validate",
+    "basic_memory.mcp.tools.schema_validate",
     new_callable=AsyncMock,
     return_value=VALIDATE_REPORT,
 )
@@ -387,7 +387,7 @@ def test_schema_validate_json(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_validate",
+    "basic_memory.mcp.tools.schema_validate",
     new_callable=AsyncMock,
     return_value={"error": "No schema found for type 'person'"},
 )
@@ -404,7 +404,7 @@ def test_schema_validate_json_error(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_validate",
+    "basic_memory.mcp.tools.schema_validate",
     new_callable=AsyncMock,
     return_value=VALIDATE_REPORT,
 )
@@ -427,7 +427,7 @@ def test_schema_validate_json_strict_exit(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_infer",
+    "basic_memory.mcp.tools.schema_infer",
     new_callable=AsyncMock,
     return_value=INFER_REPORT,
 )
@@ -451,7 +451,7 @@ def test_schema_infer_json(mock_mcp, mock_config_cls):
 
 @patch("basic_memory.cli.commands.schema.ConfigManager")
 @patch(
-    "basic_memory.cli.commands.schema.mcp_schema_diff",
+    "basic_memory.mcp.tools.schema_diff",
     new_callable=AsyncMock,
     return_value=DIFF_REPORT_WITH_DRIFT,
 )

tests/cli/test_man_command.py

@@ -0,0 +1,95 @@
+"""Tests for `bm man install` (#952 / #610: make `man bm` work)."""
+
+import subprocess
+
+from typer.testing import CliRunner
+
+from basic_memory.cli.app import app
+
+# Importing the module registers the man command group on the top-level app.
+import basic_memory.cli.commands.man as man_command  # noqa: F401
+
+runner = CliRunner()
+
+
+def _flattened(output: str) -> str:
+    # rich wraps console output at the terminal width, which differs between
+    # local shells and CI — collapse all whitespace so phrase assertions can't
+    # be split by a line break.
+    return " ".join(output.split())
+
+
+def test_man_install_writes_pages_to_target(tmp_path):
+    """Install copies every bundled page into <root>/man1 as valid groff."""
+    result = runner.invoke(app, ["man", "install", "--dir", str(tmp_path)])
+
+    assert result.exit_code == 0, result.output
+
+    bm_page = tmp_path / "man1" / "bm.1"
+    alias_page = tmp_path / "man1" / "basic-memory.1"
+    assert bm_page.exists()
+    assert alias_page.exists()
+    # groff sanity: a real title header and the alias .so include
+    assert bm_page.read_text().startswith(".TH BM 1")
+    assert alias_page.read_text().strip() == ".so man1/bm.1"
+    assert "Try:" in _flattened(result.output)
+
+
+def test_man_install_warns_when_root_not_on_manpath(tmp_path, monkeypatch):
+    """A root provably absent from manpath output gets the MANPATH hint."""
+
+    def fake_run(*args, **kwargs):
+        return subprocess.CompletedProcess(
+            args=["manpath"], returncode=0, stdout="/usr/share/man:/opt/man", stderr=""
+        )
+
+    monkeypatch.setattr(man_command.subprocess, "run", fake_run)
+    result = runner.invoke(app, ["man", "install", "--dir", str(tmp_path)])
+
+    assert result.exit_code == 0, result.output
+    assert "not on your manpath" in _flattened(result.output)
+    assert "MANPATH" in _flattened(result.output)
+
+
+def test_man_install_stays_quiet_when_manpath_unavailable(tmp_path, monkeypatch):
+    """No manpath binary → no false-alarm warning, install still succeeds."""
+
+    def fake_run(*args, **kwargs):
+        raise FileNotFoundError("manpath")
+
+    monkeypatch.setattr(man_command.subprocess, "run", fake_run)
+    result = runner.invoke(app, ["man", "install", "--dir", str(tmp_path)])
+
+    assert result.exit_code == 0, result.output
+    assert "not on your manpath" not in _flattened(result.output)
+
+
+def test_man_install_treats_manpath_failure_as_unknown(tmp_path, monkeypatch):
+    """manpath exiting non-zero → unknown, no warning."""
+
+    def fake_run(*args, **kwargs):
+        return subprocess.CompletedProcess(args=["manpath"], returncode=1, stdout="", stderr="boom")
+
+    monkeypatch.setattr(man_command.subprocess, "run", fake_run)
+    result = runner.invoke(app, ["man", "install", "--dir", str(tmp_path)])
+
+    assert result.exit_code == 0, result.output
+    assert "not on your manpath" not in _flattened(result.output)
+
+
+def test_man_install_skips_app_initialization(tmp_path, monkeypatch):
+    """man install must not touch the database (PR #971 review).
+
+    Installing offline docs only copies packaged files; a locked or broken
+    local database must not block it, so `man` is in skip_init_commands.
+    """
+    import basic_memory.services.initialization as init_module
+
+    def explode(*args, **kwargs):
+        raise AssertionError("ensure_initialization must not run for `bm man`")
+
+    monkeypatch.setattr(init_module, "ensure_initialization", explode)
+    result = runner.invoke(app, ["man", "install", "--dir", str(tmp_path)])
+
+    assert result.exit_code == 0, result.output
+    assert (tmp_path / "man1" / "bm.1").exists()

tests/cli/test_status_wait_timeout.py

@@ -0,0 +1,55 @@
+"""Tests for the `bm status --wait` timeout guidance (#959)."""
+
+import pytest
+
+import basic_memory.cli.commands.status as status_module
+from basic_memory.cli.commands.status import StatusTimeout, run_status
+from basic_memory.schemas import SyncReportResponse
+from basic_memory.schemas.project_info import ProjectItem
+
+
+@pytest.mark.asyncio
+async def test_status_wait_timeout_points_at_reindex(monkeypatch, config_manager):
+    """The timeout error must hand the user the command that actually indexes.
+
+    In CLI-only sessions no sync coordinator runs, so pending changes never
+    drain and --wait always times out; without the hint the dead end looks
+    like a hung indexer (#959).
+    """
+    project_item = ProjectItem(
+        id=1,
+        external_id="11111111-1111-1111-1111-111111111111",
+        name="scratch",
+        path="/tmp/scratch",
+        is_default=True,
+    )
+    pending_report = SyncReportResponse(new={"notes/seed.md"}, total=1)
+
+    class FakeProjectClient:
+        def __init__(self, client):
+            pass
+
+        async def get_status(self, external_id):
+            return pending_report
+
+    class FakeClientContext:
+        async def __aenter__(self):
+            return object()
+
+        async def __aexit__(self, *args):
+            return False
+
+    async def fake_get_active_project(client, project, context):
+        return project_item
+
+    monkeypatch.setattr(status_module, "get_client", lambda **kwargs: FakeClientContext())
+    monkeypatch.setattr(status_module, "get_active_project", fake_get_active_project)
+    monkeypatch.setattr(status_module, "ProjectClient", FakeProjectClient)
+
+    with pytest.raises(StatusTimeout) as exc_info:
+        await run_status(project="scratch", wait=True, timeout=0.01, poll_interval=0.001)
+
+    message = str(exc_info.value)
+    assert "Timed out" in message
+    assert "bm reindex --project scratch" in message
+    assert "no Basic Memory server is running" in message

tests/db/test_memory_db_session_isolation.py

@@ -0,0 +1,93 @@
+"""Regression test for issue #940: lost writes on the in-memory SQLite engine.
+
+The in-memory SQLite URL (``sqlite+aiosqlite://``) used to fall back to
+SQLAlchemy's StaticPool, which hands the same DBAPI connection to every
+concurrently checked-out session. Concurrent asyncio tasks then share one
+transaction scope: a rollback issued by one session — scoped_session's
+exception handling, or the pool's reset-on-return at checkin — silently rolls
+back another session's uncommitted writes. During sync this manifested as a
+freshly inserted relation row vanishing without any error, which is how
+``test_sync_entity_circular_relations`` failed on CI with
+``len(entity_b.outgoing_relations) == 0``.
+
+This test pins the isolation invariant directly: a session that rolls back in
+one task must never destroy an uncommitted write of a session in another task.
+"""
+
+import asyncio
+from pathlib import Path
+
+import pytest
+from sqlalchemy import text
+
+from basic_memory import db
+from basic_memory.models import Base
+
+
+class _SimulatedIndexingFailure(Exception):
+    """Stand-in for any per-file error that _run_bounded swallows during sync."""
+
+
+@pytest.mark.asyncio
+async def test_concurrent_session_rollback_does_not_destroy_uncommitted_writes():
+    """A rolled-back session in one task must not erase another task's writes."""
+    async with db.engine_session_factory(
+        db_path=Path("unused.db"), db_type=db.DatabaseType.MEMORY
+    ) as (engine, session_maker):
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+
+        # Seed a project and entity so a relation row satisfies its FK constraints.
+        async with db.scoped_session(session_maker) as session:
+            await session.execute(
+                text(
+                    "INSERT INTO project (id, external_id, name, description, path, is_active,"
+                    " is_default, created_at, updated_at, permalink) "
+                    "VALUES (1, 'px', 'p', '', '/tmp', 1, 1, '2024-01-01', '2024-01-01', 'p')"
+                )
+            )
+            await session.execute(
+                text(
+                    "INSERT INTO entity (id, external_id, title, note_type, content_type,"
+                    " project_id, file_path, created_at, updated_at) "
+                    "VALUES (1, 'ex', 'E', 'note', 'text/markdown', 1, 'e.md',"
+                    " '2024-01-01', '2024-01-01')"
+                )
+            )
+
+        write_in_flight = asyncio.Event()
+
+        async def writer() -> None:
+            # Mirrors RelationRepository.add_all_ignore_duplicates: INSERT executed,
+            # commit only happens at scoped_session exit several awaits later.
+            async with db.scoped_session(session_maker) as session:
+                await session.execute(
+                    text(
+                        "INSERT INTO relation (project_id, from_id, to_id, to_name,"
+                        " relation_type) VALUES (1, 1, NULL, 'target', 'depends_on')"
+                    )
+                )
+                write_in_flight.set()
+                # Real DB roundtrips (not sleeps) keep this transaction open across
+                # await points, exactly like the multi-statement sessions in sync.
+                for _ in range(10):
+                    await session.execute(text("SELECT 1"))
+
+        async def failing_reader() -> None:
+            # Mirrors any per-file failure during batch indexing: scoped_session
+            # rolls back on the exception path while sibling tasks are mid-write.
+            await write_in_flight.wait()
+            with pytest.raises(_SimulatedIndexingFailure):
+                async with db.scoped_session(session_maker) as session:
+                    await session.execute(text("SELECT 1"))
+                    raise _SimulatedIndexingFailure()
+
+        await asyncio.gather(writer(), failing_reader())
+
+        async with db.scoped_session(session_maker) as session:
+            count = (await session.execute(text("SELECT count(*) FROM relation"))).scalar()
+
+        assert count == 1, (
+            "writer's committed INSERT was rolled back by a concurrent session — "
+            "the in-memory engine is sharing one transaction scope across sessions"
+        )

tests/mcp/clients/test_clients.py

@@ -27,7 +27,6 @@ class TestKnowledgeClient:
     @pytest.mark.asyncio
     async def test_create_entity(self, monkeypatch):
         """Test create_entity calls correct endpoint."""
-        from basic_memory.mcp.clients import knowledge as knowledge_mod
 
         mock_response = MagicMock()
         mock_response.json.return_value = {
@@ -47,7 +46,7 @@ class TestKnowledgeClient:
             assert kwargs.get("params") is None
             return mock_response
 
-        monkeypatch.setattr(knowledge_mod, "call_post", mock_call_post)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_post", mock_call_post)
 
         mock_http = MagicMock()
         client = KnowledgeClient(mock_http, "proj-123")
@@ -57,7 +56,6 @@ class TestKnowledgeClient:
     @pytest.mark.asyncio
     async def test_update_entity(self, monkeypatch):
         """Test update_entity calls correct endpoint without fast query params."""
-        from basic_memory.mcp.clients import knowledge as knowledge_mod
 
         mock_response = MagicMock()
         mock_response.json.return_value = {
@@ -77,7 +75,7 @@ class TestKnowledgeClient:
             assert kwargs.get("params") is None
             return mock_response
 
-        monkeypatch.setattr(knowledge_mod, "call_put", mock_call_put)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_put", mock_call_put)
 
         mock_http = MagicMock()
         client = KnowledgeClient(mock_http, "proj-123")
@@ -87,7 +85,6 @@ class TestKnowledgeClient:
     @pytest.mark.asyncio
     async def test_patch_entity(self, monkeypatch):
         """Test patch_entity calls correct endpoint without fast query params."""
-        from basic_memory.mcp.clients import knowledge as knowledge_mod
 
         mock_response = MagicMock()
         mock_response.json.return_value = {
@@ -107,7 +104,7 @@ class TestKnowledgeClient:
             assert kwargs.get("params") is None
             return mock_response
 
-        monkeypatch.setattr(knowledge_mod, "call_patch", mock_call_patch)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_patch", mock_call_patch)
 
         mock_http = MagicMock()
         client = KnowledgeClient(mock_http, "proj-123")
@@ -117,7 +114,6 @@ class TestKnowledgeClient:
     @pytest.mark.asyncio
     async def test_resolve_entity(self, monkeypatch):
         """Test resolve_entity returns external_id."""
-        from basic_memory.mcp.clients import knowledge as knowledge_mod
 
         mock_response = MagicMock()
         mock_response.json.return_value = {"external_id": "entity-uuid-123"}
@@ -126,7 +122,7 @@ class TestKnowledgeClient:
             assert "/v2/projects/proj-123/knowledge/resolve" in url
             return mock_response
 
-        monkeypatch.setattr(knowledge_mod, "call_post", mock_call_post)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_post", mock_call_post)
 
         mock_http = MagicMock()
         client = KnowledgeClient(mock_http, "proj-123")
@@ -136,7 +132,6 @@ class TestKnowledgeClient:
     @pytest.mark.asyncio
     async def test_sync_file(self, monkeypatch):
         """Test sync_file posts the file path to the sync-file endpoint."""
-        from basic_memory.mcp.clients import knowledge as knowledge_mod
 
         mock_response = MagicMock()
         mock_response.json.return_value = {
@@ -156,7 +151,7 @@ class TestKnowledgeClient:
             assert kwargs.get("json") == {"file_path": "notes/disk-note.md"}
             return mock_response
 
-        monkeypatch.setattr(knowledge_mod, "call_post", mock_call_post)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_post", mock_call_post)
 
         mock_http = MagicMock()
         client = KnowledgeClient(mock_http, "proj-123")
@@ -166,7 +161,6 @@ class TestKnowledgeClient:
     @pytest.mark.asyncio
     async def test_get_orphans_validates_response(self, monkeypatch):
         """Orphan responses are validated into GraphNode objects."""
-        from basic_memory.mcp.clients import knowledge as knowledge_mod
         from basic_memory.schemas.v2.graph import GraphNode
 
         mock_response = MagicMock()
@@ -186,7 +180,7 @@ class TestKnowledgeClient:
             assert "/v2/projects/proj-123/knowledge/orphans" in url
             return mock_response
 
-        monkeypatch.setattr(knowledge_mod, "call_get", mock_call_get)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_get", mock_call_get)
 
         mock_http = MagicMock()
         client = KnowledgeClient(mock_http, "proj-123")
@@ -211,7 +205,6 @@ class TestSearchClient:
     @pytest.mark.asyncio
     async def test_search(self, monkeypatch):
         """Test search calls correct endpoint."""
-        from basic_memory.mcp.clients import search as search_mod
 
         mock_response = MagicMock()
         mock_response.json.return_value = {
@@ -225,7 +218,7 @@ class TestSearchClient:
             assert kwargs.get("params") == {"page": 1, "page_size": 10}
             return mock_response
 
-        monkeypatch.setattr(search_mod, "call_post", mock_call_post)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_post", mock_call_post)
 
         mock_http = MagicMock()
         client = SearchClient(mock_http, "proj-123")
@@ -248,7 +241,6 @@ class TestMemoryClient:
     @pytest.mark.asyncio
     async def test_build_context(self, monkeypatch):
         """Test build_context calls correct endpoint."""
-        from basic_memory.mcp.clients import memory as memory_mod
         from datetime import datetime
 
         mock_response = MagicMock()
@@ -264,7 +256,7 @@ class TestMemoryClient:
             assert "/v2/projects/proj-123/memory/specs/search" in url
             return mock_response
 
-        monkeypatch.setattr(memory_mod, "call_get", mock_call_get)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_get", mock_call_get)
 
         mock_http = MagicMock()
         client = MemoryClient(mock_http, "proj-123")
@@ -274,7 +266,6 @@ class TestMemoryClient:
     @pytest.mark.asyncio
     async def test_recent(self, monkeypatch):
         """Test recent calls correct endpoint."""
-        from basic_memory.mcp.clients import memory as memory_mod
         from datetime import datetime
 
         mock_response = MagicMock()
@@ -293,7 +284,7 @@ class TestMemoryClient:
             assert params.get("depth") == 2
             return mock_response
 
-        monkeypatch.setattr(memory_mod, "call_get", mock_call_get)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_get", mock_call_get)
 
         mock_http = MagicMock()
         client = MemoryClient(mock_http, "proj-123")
@@ -304,7 +295,6 @@ class TestMemoryClient:
     @pytest.mark.asyncio
     async def test_recent_with_types(self, monkeypatch):
         """Test recent with types filter."""
-        from basic_memory.mcp.clients import memory as memory_mod
         from datetime import datetime
 
         mock_response = MagicMock()
@@ -322,7 +312,7 @@ class TestMemoryClient:
             assert params.get("type") == "note,spec"
             return mock_response
 
-        monkeypatch.setattr(memory_mod, "call_get", mock_call_get)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_get", mock_call_get)
 
         mock_http = MagicMock()
         client = MemoryClient(mock_http, "proj-123")
@@ -344,7 +334,6 @@ class TestDirectoryClient:
     @pytest.mark.asyncio
     async def test_list(self, monkeypatch):
         """Test list calls correct endpoint."""
-        from basic_memory.mcp.clients import directory as directory_mod
 
         mock_response = MagicMock()
         mock_response.json.return_value = [{"name": "folder", "type": "directory"}]
@@ -353,7 +342,7 @@ class TestDirectoryClient:
             assert "/v2/projects/proj-123/directory/list" in url
             return mock_response
 
-        monkeypatch.setattr(directory_mod, "call_get", mock_call_get)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_get", mock_call_get)
 
         mock_http = MagicMock()
         client = DirectoryClient(mock_http, "proj-123")
@@ -376,7 +365,6 @@ class TestResourceClient:
     @pytest.mark.asyncio
     async def test_read(self, monkeypatch):
         """Test read calls correct endpoint."""
-        from basic_memory.mcp.clients import resource as resource_mod
 
         mock_response = MagicMock()
         mock_response.text = "# Note content"
@@ -385,7 +373,7 @@ class TestResourceClient:
             assert "/v2/projects/proj-123/resource/entity-123" in url
             return mock_response
 
-        monkeypatch.setattr(resource_mod, "call_get", mock_call_get)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_get", mock_call_get)
 
         mock_http = MagicMock()
         client = ResourceClient(mock_http, "proj-123")
@@ -405,7 +393,6 @@ class TestProjectClient:
     @pytest.mark.asyncio
     async def test_list_projects(self, monkeypatch):
         """Test list_projects calls correct endpoint."""
-        from basic_memory.mcp.clients import project as project_mod
 
         mock_response = MagicMock()
         mock_response.json.return_value = {
@@ -425,7 +412,7 @@ class TestProjectClient:
             assert "/v2/projects" in url
             return mock_response
 
-        monkeypatch.setattr(project_mod, "call_get", mock_call_get)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_get", mock_call_get)
 
         mock_http = MagicMock()
         client = ProjectClient(mock_http)

tests/mcp/test_async_client_modes.py

@@ -618,3 +618,42 @@ async def test_get_cloud_control_plane_client_raises_without_credentials(config_
     with pytest.raises(RuntimeError, match="Cloud routing requested but no credentials found"):
         async with get_cloud_control_plane_client():
             pass
+
+
+@pytest.mark.asyncio
+async def test_get_client_workspace_selector_routes_to_cloud(config_manager):
+    """A bare workspace selector routes to the cloud proxy, not local ASGI (#954).
+
+    This is the create_memory_project(workspace=...) path on a local MCP
+    server: no factory, no explicit flags, no project_name — the selector
+    alone must imply cloud routing.
+    """
+    cfg = config_manager.load_config()
+    cfg.cloud_host = "https://cloud.example.test"
+    cfg.cloud_api_key = "bmc_test_key_123"
+    config_manager.save_config(cfg)
+
+    async with get_client(workspace="tenant-123") as client:
+        assert str(client.base_url).rstrip("/") == "https://cloud.example.test/proxy"
+        assert client.headers.get("X-Workspace-ID") == "tenant-123"
+
+
+@pytest.mark.asyncio
+async def test_get_client_workspace_selector_without_credentials_fails_fast(
+    config_manager, monkeypatch
+):
+    """No credentials + workspace selector must raise, never fall back to local (#954).
+
+    The silent local fallback was the bug: a cloud project create either
+    failed on a cloud-style path or silently created a local project.
+    """
+    cfg = config_manager.load_config()
+    cfg.cloud_host = "https://cloud.example.test"
+    cfg.cloud_api_key = None
+    cfg.cloud_client_id = "cid"
+    cfg.cloud_domain = "https://auth.example.test"
+    config_manager.save_config(cfg)
+
+    with pytest.raises(RuntimeError, match="cloud workspace was requested"):
+        async with get_client(workspace="team-slug"):
+            pass

tests/mcp/test_client_schema.py

@@ -63,7 +63,7 @@ class TestSchemaClientValidate:
             assert kwargs.get("params") == {}
             return mock_response
 
-        monkeypatch.setattr("basic_memory.mcp.clients.schema.call_post", mock_call_post)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_post", mock_call_post)
 
         result = await schema_client.validate()
         assert isinstance(result, ValidationReport)
@@ -88,7 +88,7 @@ class TestSchemaClientValidate:
             assert kwargs["params"]["note_type"] == "person"
             return mock_response
 
-        monkeypatch.setattr("basic_memory.mcp.clients.schema.call_post", mock_call_post)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_post", mock_call_post)
 
         result = await schema_client.validate(note_type="person")
         assert result.note_type == "person"
@@ -113,7 +113,7 @@ class TestSchemaClientValidate:
             assert kwargs["params"]["identifier"] == "people/alice"
             return mock_response
 
-        monkeypatch.setattr("basic_memory.mcp.clients.schema.call_post", mock_call_post)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_post", mock_call_post)
 
         result = await schema_client.validate(identifier="people/alice")
         assert result.total_notes == 1
@@ -144,7 +144,7 @@ class TestSchemaClientInfer:
             assert kwargs["params"]["threshold"] == 0.25
             return mock_response
 
-        monkeypatch.setattr("basic_memory.mcp.clients.schema.call_post", mock_call_post)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_post", mock_call_post)
 
         result = await schema_client.infer("person")
         assert isinstance(result, InferenceReport)
@@ -171,7 +171,7 @@ class TestSchemaClientInfer:
             assert kwargs["params"]["threshold"] == 0.5
             return mock_response
 
-        monkeypatch.setattr("basic_memory.mcp.clients.schema.call_post", mock_call_post)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_post", mock_call_post)
 
         result = await schema_client.infer("meeting", threshold=0.5)
         assert result.note_type == "meeting"
@@ -197,7 +197,7 @@ class TestSchemaClientDiff:
             assert url == "/v2/projects/test-project-id/schema/diff/person"
             return mock_response
 
-        monkeypatch.setattr("basic_memory.mcp.clients.schema.call_get", mock_call_get)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_get", mock_call_get)
 
         result = await schema_client.diff("person")
         assert isinstance(result, DriftReport)
@@ -235,7 +235,7 @@ class TestSchemaClientDiff:
         async def mock_call_get(client, url, **kwargs):
             return mock_response
 
-        monkeypatch.setattr("basic_memory.mcp.clients.schema.call_get", mock_call_get)
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_get", mock_call_get)
 
         result = await schema_client.diff("person")
         assert len(result.new_fields) == 1