feat(mcp): add all_projects flag to mem_search (#408)

Adds an optional boolean argument to mem_search that bypasses project
detection and runs a global FTS5 search. Resolves the case where an
agent needs to recall context from a project whose key it does not
know.

When all_projects is true, the handler skips
resolveReadProjectWithProcessOverride entirely and passes an empty
project to Store.Search. The project argument is ignored in this mode;
documented and tested. The response envelope reports
project_source="all_projects" and an empty project so callers can
distinguish cross-project results from a scoped query.

Adds a new SourceAllProjects constant in internal/project to keep the
envelope contract typed and explicit.

Closes #303

Author: carlosmoradev

DOCS.md

@@ -760,6 +760,8 @@ Returns success even when cwd is ambiguous — empty `project` + non-empty `avai
 
 Search persistent memory across all sessions. Supports FTS5 full-text search with type/project/scope/limit filters.
 
+Set `all_projects: true` to search across every project instead of the resolved one. This bypasses project detection entirely and ignores the `project` argument, so an agent can recall a decision logged elsewhere without knowing the project key. The response envelope reports `project_source: "all_projects"` and an empty `project` to reflect the cross-project scope.
+
 When an observation has judged relations in `memory_relations`, the result entry includes annotation lines immediately after the title/content block:
 
 ```

internal/mcp/mcp.go

@@ -271,7 +271,10 @@ func registerTools(srv *server.MCPServer, s *store.Store, cfg MCPConfig, allowli
 					mcp.Description("Filter by type: tool_use, file_change, command, file_read, search, manual, decision, architecture, bugfix, pattern"),
 				),
 				mcp.WithString("project",
-					mcp.Description("Filter by project name"),
+					mcp.Description("Filter by project name. Ignored when all_projects=true."),
+				),
+				mcp.WithBoolean("all_projects",
+					mcp.Description("Search across every project instead of the current one. When true, the project argument is ignored and results may come from any project. Useful for recalling decisions logged elsewhere when you don't know the project key."),
 				),
 				mcp.WithString("scope",
 					mcp.Description("Filter by scope: project (default) or personal"),
@@ -899,23 +902,35 @@ func handleSearch(s *store.Store, cfg MCPConfig, activity *SessionActivity) serv
 		typ, _ := req.GetArguments()["type"].(string)
 		projectOverride, _ := req.GetArguments()["project"].(string)
 		scope, _ := req.GetArguments()["scope"].(string)
+		allProjects := boolArg(req, "all_projects", false)
 		limit := intArg(req, "limit", 10)
 
-		// Resolve project: validate override or auto-detect (REQ-310, REQ-311)
-		detRes, err := resolveReadProjectWithProcessOverride(s, projectOverride, cfg.DefaultProject)
-		if err != nil {
-			var upe *unknownProjectError
-			if errors.As(err, &upe) {
-				return errorWithMeta("unknown_project",
-					fmt.Sprintf("Project %q not found in store", upe.Name),
-					upe.AvailableProjects,
-				), nil
+		// all_projects=true short-circuits project resolution: we search globally
+		// regardless of the project override or any auto-detected project. This
+		// keeps the cross-project flow independent of cwd-based detection so the
+		// agent can recall context from any project without knowing its key.
+		var detRes projectpkg.DetectionResult
+		var project string
+		if allProjects {
+			detRes = projectpkg.DetectionResult{Source: projectpkg.SourceAllProjects}
+		} else {
+			// Resolve project: validate override or auto-detect (REQ-310, REQ-311)
+			res, err := resolveReadProjectWithProcessOverride(s, projectOverride, cfg.DefaultProject)
+			if err != nil {
+				var upe *unknownProjectError
+				if errors.As(err, &upe) {
+					return errorWithMeta("unknown_project",
+						fmt.Sprintf("Project %q not found in store", upe.Name),
+						upe.AvailableProjects,
+					), nil
+				}
+				return mcp.NewToolResultError(fmt.Sprintf("Project resolution failed: %s", err)), nil
 			}
-			return mcp.NewToolResultError(fmt.Sprintf("Project resolution failed: %s", err)), nil
+			detRes = res
+			project = detRes.Project
+			project, _ = store.NormalizeProject(project)
+			detRes.Project = project // JR2-1: keep envelope in sync with normalized query project
 		}
-		project := detRes.Project
-		project, _ = store.NormalizeProject(project)
-		detRes.Project = project // JR2-1: keep envelope in sync with normalized query project
 
 		sessionID := defaultSessionID(project)
 		activity.RecordToolCall(sessionID)

internal/mcp/mcp_test.go

@@ -6519,3 +6519,132 @@ func TestProcessOverrideSaveHandlerWritesToDefaultProject(t *testing.T) {
 		t.Fatalf("results in trusted project = %d; want 1", len(results))
 	}
 }
+
+// seedCrossProjectMemories inserts one observation per project so cross-project
+// search tests have something to find. Returns the session IDs created.
+func seedCrossProjectMemories(t *testing.T, s *store.Store) {
+	t.Helper()
+	type seed struct {
+		session string
+		project string
+		title   string
+		content string
+	}
+	seeds := []seed{
+		{"s-alpha", "alpha", "Auth middleware in alpha", "JWT auth middleware decided here"},
+		{"s-beta", "beta", "Auth middleware in beta", "Different auth approach for beta"},
+		{"s-gamma", "gamma", "Logging only", "Nothing about authentication here"},
+	}
+	for _, sd := range seeds {
+		if err := s.CreateSession(sd.session, sd.project, "/tmp/"+sd.project); err != nil {
+			t.Fatalf("create session %s: %v", sd.session, err)
+		}
+		if _, err := s.AddObservation(store.AddObservationParams{
+			SessionID: sd.session,
+			Type:      "decision",
+			Title:     sd.title,
+			Content:   sd.content,
+			Project:   sd.project,
+			Scope:     "project",
+		}); err != nil {
+			t.Fatalf("add observation %s: %v", sd.project, err)
+		}
+	}
+}
+
+func TestHandleSearchAllProjectsReturnsResultsFromEveryProject(t *testing.T) {
+	s := newMCPTestStore(t)
+	seedCrossProjectMemories(t, s)
+
+	search := handleSearch(s, MCPConfig{}, NewSessionActivity(10*time.Minute))
+	req := mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"query":        "auth middleware",
+		"all_projects": true,
+		"limit":        5.0,
+	}}}
+
+	res, err := search(context.Background(), req)
+	if err != nil {
+		t.Fatalf("search handler error: %v", err)
+	}
+	if res.IsError {
+		t.Fatalf("unexpected search error: %s", callResultText(t, res))
+	}
+
+	text := callResultText(t, res)
+	if !strings.Contains(text, "alpha") {
+		t.Fatalf("expected result from alpha, got: %s", text)
+	}
+	if !strings.Contains(text, "beta") {
+		t.Fatalf("expected result from beta, got: %s", text)
+	}
+
+	// Envelope must reflect cross-project search, not a single resolved project.
+	var envelope map[string]any
+	if err := json.Unmarshal([]byte(text), &envelope); err != nil {
+		t.Fatalf("envelope is not JSON: %v\n%s", err, text)
+	}
+	if got := envelope["project_source"]; got != project.SourceAllProjects {
+		t.Fatalf("project_source = %v; want %q", got, project.SourceAllProjects)
+	}
+	if got := envelope["project"]; got != "" {
+		t.Fatalf("project = %v; want empty string for cross-project search", got)
+	}
+}
+
+func TestHandleSearchAllProjectsOverridesProjectArg(t *testing.T) {
+	s := newMCPTestStore(t)
+	seedCrossProjectMemories(t, s)
+
+	search := handleSearch(s, MCPConfig{}, NewSessionActivity(10*time.Minute))
+	// Pass both project="alpha" and all_projects=true: all_projects must win.
+	req := mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"query":        "auth middleware",
+		"project":      "alpha",
+		"all_projects": true,
+		"limit":        5.0,
+	}}}
+
+	res, err := search(context.Background(), req)
+	if err != nil {
+		t.Fatalf("search handler error: %v", err)
+	}
+	if res.IsError {
+		t.Fatalf("unexpected search error: %s", callResultText(t, res))
+	}
+
+	text := callResultText(t, res)
+	if !strings.Contains(text, "beta") {
+		t.Fatalf("expected result from beta even when project=alpha was supplied; got: %s", text)
+	}
+}
+
+func TestHandleSearchWithoutAllProjectsStillScopesToCurrentProject(t *testing.T) {
+	s := newMCPTestStore(t)
+	seedCrossProjectMemories(t, s)
+
+	search := handleSearch(s, MCPConfig{}, NewSessionActivity(10*time.Minute))
+	// Default behavior: project="alpha", no all_projects flag → only alpha matches.
+	req := mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"query":   "auth middleware",
+		"project": "alpha",
+		"limit":   5.0,
+	}}}
+
+	res, err := search(context.Background(), req)
+	if err != nil {
+		t.Fatalf("search handler error: %v", err)
+	}
+	if res.IsError {
+		t.Fatalf("unexpected search error: %s", callResultText(t, res))
+	}
+
+	text := callResultText(t, res)
+	if !strings.Contains(text, "alpha") {
+		t.Fatalf("expected result from alpha, got: %s", text)
+	}
+	if strings.Contains(text, "beta") {
+		t.Fatalf("beta result should not leak into a scoped search; got: %s", text)
+	}
+}
+

internal/project/detect.go

@@ -40,6 +40,7 @@ const (
 	SourceUserSelectedAfterAmbiguousProject = "user_selected_after_ambiguous_project"
 	SourceRequestBody                       = "request_body" // REQ-414: project came from the request body (server-side, no filesystem path)
 	SourceConfig                            = "config"       // derived from .engram/config.json project_name
+	SourceAllProjects                       = "all_projects" // caller asked for cross-project search (no single project resolved)
 )
 
 // noiseSet lists directory names that are skipped during child-repo scanning.