Workspace project index never refreshes on miss — out-of-band/teammate-created projects invisible and unroutable by project_id in running sessions

[phernandez]

Summary

The per-session workspace project index is built once and never refreshed on lookup miss. A cloud project created out-of-band (via CLI, another client, or — the worst case — a teammate in a shared team workspace) is invisible to every already-running MCP session:

• list_memory_projects omits it
• project_id routing hard-errors: Project '<uuid>' was not found in indexed cloud workspaces — asserting nonexistence of a project that demonstrably exists
• read_note's fuzzy-fallback breaks even when the caller's project name resolves fine, because the fallback internally re-resolves via project_id

Reproduction (one session, minutes apart)

1. MCP session running (local stdio, OAuth). Create a project out-of-band:
   bm project add manual --cloud --workspace <team-slug> --visibility shared
2. In the running session:
   • search_notes(project="manual", query="x") → works (name resolves via local config per-project routing)
   • search_notes(project_id="0e6a327b-...", query="x") → error: Project '0e6a327b-...' was not found in indexed cloud workspaces. Available projects: <stale list omitting manual>
   • read_note("fuzzy text", project="manual") → error (same), because the fallback at mcp/tools/read_note.py:319 passes project_id=active_project.external_id to search_notes, and project_id takes precedence — so the already-successfully-resolved project gets re-resolved through the stale index and dies
   • list_memory_projects() → stale list, no manual

The same asymmetry means a teammate adding a project to a shared workspace is invisible (and unroutable by project_id) to everyone's long-running sessions — e.g. Claude Desktop sessions that stay up for days.

Root cause

src/basic_memory/mcp/project_context.py:

• The index is cached in FastMCP context state under _WORKSPACE_PROJECT_INDEX_STATE_KEY (~line 728/787) with no TTL
• resolve_workspace_project_identifier() (~line 801) looks up the cached index and on miss raises ValueError (~line 881) with no attempt to rebuild
• invalidate_workspace_project_index() exists but is only called after in-session create_memory_project — out-of-band creation has no invalidation path

Expected

Cache-miss refresh: when an external_id / qualified-name lookup misses the cached index, rebuild the index once and retry before raising. (Optionally also a short TTL, but miss-refresh alone fixes the correctness issue — a miss is exactly the signal that the cache may be stale.)

Also worth fixing alongside: read_note's fallback should not re-resolve a project it already holds — it has active_project in hand and could pass routing through directly.

Severity

High for Teams: shared-workspace project creation is a core flow, and the failure mode is a confident wrong answer ("project does not exist") rather than a miss.

Context

Found during live verification for #952. Related: #954 (create_memory_project workspace routing) — same discovery session.

[claude]

Claude finished @phernandez's task in 1m 50s —— View job

---

Issue Triage

• Gather context and read issue
• Read relevant source files (project_context.py, read_note.py)
• Check for duplicate issues
• Apply labels and provide triage

---

Classification

Field	Value
Type	Bug
Priority	High
Component	Cloud / MCP tools
Complexity	Medium

Analysis

This is a well-diagnosed, high-severity bug. The root cause is confirmed in the code:

_ensure_workspace_project_index() (line 723–791) caches on first build and returns immediately on a cache hit. resolve_workspace_project_identifier() (line 801) calls it and raises ValueError on miss — no rebuild attempt on miss.

# Lines 870–883 — raises immediately on miss, no rebuild:
matches = list(index.entries_by_permalink.get(project_permalink, ()))
if not matches:
    ...
    raise ValueError(
        f"Project '{project}' was not found in indexed cloud workspaces. ..."
    )

The invalidate_workspace_project_index() function (line 682) exists but is only wired to in-session create_memory_project — out-of-band creation has no invalidation path.

Two independent fixes needed:

1. Miss-refresh in resolve_workspace_project_identifier(): When a UUID or name lookup fails against the cached index, invalidate the cache and rebuild once before raising. This is the minimum fix for the correctness issue.

2. read_note.py fallback re-resolution (line 319): The _search_candidates closure passes project_id=active_project.external_id to search_notes. This causes the already-successfully-resolved active_project to be re-routed through resolve_workspace_project_identifier() via the UUID fast-path, which hits the stale index and raises. Since active_project is already resolved, the inner project_id arg serves no purpose for routing — the outer get_project_client() has already bound the right client. This pass-through should be dropped or the inner call should avoid triggering cloud re-resolution.

No Duplicate Found

Closest prior issue is #834 (local-only project_id routing failure, now closed). Issue #954 (related same discovery session) is about create_memory_project workspace routing — separate root cause, same discovery session.

Suggested Fix Approach

In resolve_workspace_project_identifier():

• After each miss path (external_id miss, qualified-name miss, unqualified-name miss), check if the current index is potentially stale: if so, call invalidate_workspace_project_index(), rebuild via _ensure_workspace_project_index(), and retry the lookup once before raising.

In read_note.py:

• The _search_candidates closure should omit project_id (or use a routing-neutral form) since the outer get_project_client() has already resolved the project — passing project_id of an already-resolved project forces an unnecessary and failure-prone re-resolution through the cloud index.

[phernandez]

Fixed in #981 (commit 1ad3a35, on main). Lookup misses now raise WorkspaceProjectLookupMiss, which triggers a one-time index rebuild and retry before failing — out-of-band/teammate-created projects become visible and routable without restarting the session. The read_note fuzzy-fallback re-resolution path was also un-broken. Regression tests in tests/mcp/test_project_context.py (refresh-on-miss, 4 scenarios).

Note: the #952 manual's live cloud re-verification is still planned after release and will exercise this fix against a real team workspace. The PR body's comma-separated "Fixes" list only auto-closed the first issue (#954) — closing manually.