Add lazy memory health recommendations

Author: rschardosin

docs/architecture/api-studio.md

@@ -56,9 +56,9 @@ The API is organized by domain:
 | **Settings** | `GET /settings`, `PUT /settings` | `settings_handlers.go` |
 | **Tools** | `GET /tools`, `GET /tools/cache` | `tools_handlers.go` |
 | **AI Chat** | `POST /ai-chat`, `GET /ai-chat/stream` | `ai_chat_handlers.go` |
-| **Memory diagnostics** | `GET /memories/map`, `POST /memories/consolidate/preview`, `POST /memories/consolidate/apply` | `memory_map.go`, `memory_consolidation.go` |
+| **Memory health** | `GET /memories/health`, `GET /memories/map`, `POST /memories/consolidate/preview`, `POST /memories/consolidate/apply` | `memory_health.go`, `memory_map.go`, `memory_consolidation.go` |
 
-The memory consolidation endpoints are platform-only and tenant-scoped. They draft and upsert structured scenario cards through the existing memory stores; they do not connect directly to tenant databases and they do not delete source memories.
+The memory health and consolidation endpoints are platform-only and tenant-scoped. `GET /memories/health` evaluates recommendations lazily when the UI is opened and reuses fresh results for five days; it does not run on a scheduler. Consolidation drafts and upserts structured scenario cards through the existing memory stores; it does not connect directly to tenant databases and it does not delete source memories.
 
 ### SSE Chat Streaming
 
@@ -124,7 +124,8 @@ MCP tools are cached with background refresh to avoid slow MCP server queries on
 | `pkg/api/mcp_handlers.go` | MCP server management and inspector |
 | `pkg/api/sandbox_handlers.go` | Sandbox initialization, templates, proxy |
 | `pkg/api/ai_chat_handlers.go` | Dedicated AI assistant for Studio UI |
-| `pkg/api/memory_map.go` | Memory Map diagnostics for duplicate/scattered/risky memories |
+| `pkg/api/memory_health.go` | Lazy Memory Health recommendations with a five-day freshness window |
+| `pkg/api/memory_map.go` | Advanced Memory Map diagnostics for duplicate/scattered/risky memories |
 | `pkg/api/memory_consolidation.go` | Scenario-card preview/apply endpoints for controlled consolidation |
 | `web/src/components/` | React components (37+ files) |
 | `web/src/api/` | API client functions for the frontend |

docs/architecture/memory.md

@@ -197,24 +197,32 @@ Implementation details:
 
 The key invariant is that Astonish should save **how to do the thing efficiently**, not a transcript of exploratory dead ends. Temporary outages, timeouts, rate limits, and “X did not work” observations may appear only as conditional cautions that require re-verification before they change behavior.
 
-### Memory Map Diagnostics and Consolidation
+### Memory Health Recommendations and Advanced Map
 
-Platform mode exposes `GET /api/memories/map` as a diagnostic report over the current user's visible personal, team, and org memories. The Studio Knowledge Browser surfaces this as the **Memory Map** tab.
+Platform mode exposes `GET /api/memories/health` as the product-facing memory organization surface. It evaluates the current user's visible personal, team, and org memories lazily when the Knowledge Browser's **Memory Health** tab is opened. There is no background schedule: a cached evaluation is reused for five days when the memory snapshot has not changed, and the next UI visit after the TTL triggers a fresh evaluation. Users can also force a refresh with **Reanalyze**.
 
-The report groups likely related memory chunks by a canonical topic key and flags conditions that make memory feel scattered or unsafe:
+Memory Health returns reviewable recommendations, not automatic writes:
+
+- create a scenario card from related raw memories
+- update an existing scenario card with new raw source memories
+- review a card that still carries temporary-failure or trial/error wording
+
+Each recommendation contains the proposed card, target scope, source memory IDs, and the diagnostic flags that explain why it was suggested. Applying a recommendation uses the same scenario-card upsert endpoint as manual consolidation; source memories are retained as provenance.
+
+`GET /api/memories/map` remains available as the advanced diagnostic report behind the Memory Health UI. It groups likely related memory chunks by a canonical topic key and flags conditions that make memory feel scattered or unsafe:
 
 - duplicate risk: multiple memories appear to cover the same topic
 - scattered topic: related memories are spread across scopes or categories
 - transient failure risk: a memory uses outage/timeout/flaky language that should not become a permanent avoidance rule
 - trial/error risk: a memory appears to preserve exploratory failed attempts instead of the shortest successful path
 - scenario card: the group already contains a structured card, so raw rows should be treated as provenance or incremental evidence
 
-The Memory Map also provides controlled consolidation endpoints:
+The consolidation endpoints remain the write boundary:
 
 - `POST /api/memories/consolidate/preview` drafts a scenario card from a selected group without saving.
 - `POST /api/memories/consolidate/apply` saves or merges the edited card into the selected personal, team, or org scope.
 
-Both endpoints resolve stores through the tenant router and current authenticated context. They do not connect directly to tenant databases and they do not delete raw memories.
+Both endpoints resolve stores through the tenant router and current authenticated context. They do not connect directly to tenant databases and they do not delete raw memories. Memory Health recommendations are operational metadata, not agent knowledge, and are not stored as retrievable memories.
 
 ### BM25 Implementation
 

docs/website/docs/agent/memory.md

@@ -75,12 +75,14 @@ This helps the agent reuse the efficient path it learned instead of replaying tr
 
 ## Managing Memory in Studio
 
-Studio provides a visual interface for memory management:
+Studio provides a visual interface for memory management. The main organization surface is **Memory Health**: when opened, Astonish checks whether the visible memories need consolidation, deduplication, or review. The check is lazy and on demand — there is no scheduled background job. If a recent evaluation is still fresh, Studio reuses it; after five days, the next visit runs a new evaluation.
 
 - Browse all memory entries with search and filtering
 - View memory content, tags, and metadata
-- Use **Memory Map** to identify duplicate, scattered, or risky memories
-- Draft and save scenario cards from Memory Map groups
+- Use **Memory Health** to review suggested organization improvements
+- Reanalyze memory on demand; otherwise fresh evaluations are reused for five days
+- Draft and save scenario cards from recommendations
+- Open the advanced **Memory Map** only when you need low-level diagnostics
 - Publish personal memories to your team by merging them into scenario cards when possible
 - Promote team memories to org level (admin) by merging them into org scenario cards when possible
 - Delete or edit memory entries

pkg/api/handlers.go

@@ -1325,6 +1325,7 @@ func RegisterRoutes(router *mux.Router, svc *store.Services, backend store.Platf
 
 	// Memory sharing endpoints (platform mode)
 	router.HandleFunc("/api/memories/map", MemoryMapHandler).Methods("GET")
+	router.HandleFunc("/api/memories/health", MemoryHealthHandler).Methods("GET")
 	router.HandleFunc("/api/memories/consolidate/preview", MemoryConsolidationPreviewHandler).Methods("POST")
 	router.HandleFunc("/api/memories/consolidate/apply", MemoryConsolidationApplyHandler).Methods("POST")
 	router.HandleFunc("/api/memories/search", MemorySearchCrossTierHandler).Methods("POST")