feat(store): add recall tracking and promoted observations endpoint

Add read-side instrumentation to observations: recall_count and
last_recalled_at columns track how often each observation is retrieved
via Search and GetObservation. Frequently recalled observations can be
queried through a new /promoted HTTP endpoint and mem_promoted MCP tool.

- Add recall_count and last_recalled_at to observations schema
- Increment recall_count on Search() and GetObservation() (fire-and-forget)
- Split GetObservation into public (with recall) and private (without)
  to prevent Timeline navigation from inflating counts
- Add PromotedObservations() store method with configurable threshold
- Add GET /promoted HTTP endpoint with project/scope/min_recalls/limit params
- Add mem_promoted MCP tool to agent profile (deferred loading)
- Add 4 tests covering recall increment and promotion filtering

Closes #95

Author: sergiomarquezdev

internal/mcp/mcp.go

@@ -6,8 +6,8 @@
 //
 // Tool profiles allow agents to load only the tools they need:
 //
-//	engram mcp                    → all 14 tools (default)
-//	engram mcp --tools=agent      → 11 tools agents actually use (per skill files)
+//	engram mcp                    → all 15 tools (default)
+//	engram mcp --tools=agent      → 12 tools agents actually use (per skill files)
 //	engram mcp --tools=admin      → 3 tools for TUI/CLI (delete, stats, timeline)
 //	engram mcp --tools=agent,admin → combine profiles
 //	engram mcp --tools=mem_save,mem_search → individual tool names
@@ -56,6 +56,7 @@ var ProfileAgent = map[string]bool{
 	"mem_capture_passive":   true, // extract learnings from text — referenced in Gemini/Codex protocol
 	"mem_save_prompt":       true, // save user prompts
 	"mem_update":            true, // update observation by ID — skills say "use mem_update when you have an exact ID to correct"
+	"mem_promoted":          true, // frequently recalled observations — surface important context at session start
 }
 
 // ProfileAdmin contains tools for TUI, dashboards, and manual curation
@@ -575,6 +576,34 @@ Duplicates are automatically detected and skipped — safe to call multiple time
 			handleCapturePassive(s),
 		)
 	}
+
+	// ─── mem_promoted (profile: agent, deferred) ────────────────────────
+	if shouldRegister("mem_promoted", allowlist) {
+		srv.AddTool(
+			mcp.NewTool("mem_promoted",
+				mcp.WithDescription("Get frequently recalled observations that have proven their value through repeated access. Use at session start to surface the most important context."),
+				mcp.WithDeferLoading(true),
+				mcp.WithTitleAnnotation("Get Promoted Memories"),
+				mcp.WithReadOnlyHintAnnotation(true),
+				mcp.WithDestructiveHintAnnotation(false),
+				mcp.WithIdempotentHintAnnotation(true),
+				mcp.WithOpenWorldHintAnnotation(false),
+				mcp.WithString("project",
+					mcp.Description("Filter by project name"),
+				),
+				mcp.WithString("scope",
+					mcp.Description("Filter by scope: project (default) or personal"),
+				),
+				mcp.WithNumber("min_recalls",
+					mcp.Description("Minimum recall count threshold (default: 5)"),
+				),
+				mcp.WithNumber("limit",
+					mcp.Description("Max results (default: 7)"),
+				),
+			),
+			handlePromoted(s),
+		)
+	}
 }
 
 // ─── Tool Handlers ───────────────────────────────────────────────────────────
@@ -1021,6 +1050,40 @@ func handleCapturePassive(s *store.Store) server.ToolHandlerFunc {
 	}
 }
 
+func handlePromoted(s *store.Store) server.ToolHandlerFunc {
+	return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+		project, _ := req.GetArguments()["project"].(string)
+		scope, _ := req.GetArguments()["scope"].(string)
+		minRecalls := intArg(req, "min_recalls", 5)
+		limit := intArg(req, "limit", 7)
+
+		results, err := s.PromotedObservations(project, scope, minRecalls, limit)
+		if err != nil {
+			return mcp.NewToolResultError("Failed to fetch promoted memories: " + err.Error()), nil
+		}
+
+		if len(results) == 0 {
+			return mcp.NewToolResultText("No promoted memories found."), nil
+		}
+
+		var b strings.Builder
+		fmt.Fprintf(&b, "Found %d promoted memories:\n\n", len(results))
+		for i, r := range results {
+			projectStr := ""
+			if r.Project != nil {
+				projectStr = fmt.Sprintf(" | project: %s", *r.Project)
+			}
+			preview := truncate(r.Content, 300)
+			fmt.Fprintf(&b, "[%d] #%d (%s) — %s [recalled %d times]\n    %s\n    %s%s | scope: %s\n\n",
+				i+1, r.ID, r.Type, r.Title, r.RecallCount,
+				preview,
+				r.CreatedAt, projectStr, r.Scope)
+		}
+
+		return mcp.NewToolResultText(b.String()), nil
+	}
+}
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 // defaultSessionID returns a project-scoped default session ID.

internal/mcp/mcp_test.go

@@ -929,7 +929,8 @@ func TestResolveToolsAgentProfile(t *testing.T) {
 		"mem_save", "mem_search", "mem_context", "mem_session_summary",
 		"mem_session_start", "mem_session_end", "mem_get_observation",
 		"mem_suggest_topic_key", "mem_capture_passive", "mem_save_prompt",
-		"mem_update", // skills explicitly say "use mem_update when you have an exact ID to correct"
+		"mem_update",   // skills explicitly say "use mem_update when you have an exact ID to correct"
+		"mem_promoted", // frequently recalled observations — surface important context at session start
 	}
 	for _, tool := range expectedTools {
 		if !result[tool] {
@@ -974,12 +975,12 @@ func TestResolveToolsCombinedProfiles(t *testing.T) {
 		t.Fatal("expected non-nil allowlist for combined profiles")
 	}
 
-	// Should have all 14 tools
+	// Should have all 15 tools
 	allTools := []string{
 		"mem_save", "mem_search", "mem_context", "mem_session_summary",
 		"mem_session_start", "mem_session_end", "mem_get_observation",
 		"mem_suggest_topic_key", "mem_capture_passive", "mem_save_prompt",
-		"mem_update", "mem_delete", "mem_stats", "mem_timeline",
+		"mem_update", "mem_promoted", "mem_delete", "mem_stats", "mem_timeline",
 	}
 	for _, tool := range allTools {
 		if !result[tool] {
@@ -1164,7 +1165,7 @@ func TestNewServerWithToolsNilRegistersAll(t *testing.T) {
 		"mem_save", "mem_search", "mem_context", "mem_session_summary",
 		"mem_session_start", "mem_session_end", "mem_get_observation",
 		"mem_suggest_topic_key", "mem_capture_passive", "mem_save_prompt",
-		"mem_update", "mem_delete", "mem_stats", "mem_timeline",
+		"mem_update", "mem_promoted", "mem_delete", "mem_stats", "mem_timeline",
 	}
 
 	for _, name := range allTools {
@@ -1203,14 +1204,14 @@ func TestNewServerBackwardsCompatible(t *testing.T) {
 	srv := NewServer(s)
 	tools := srv.ListTools()
 
-	// 11 agent + 3 admin = 14 total
-	if len(tools) != 14 {
-		t.Errorf("NewServer should register all 14 tools, got %d", len(tools))
+	// 12 agent + 3 admin = 15 total
+	if len(tools) != 15 {
+		t.Errorf("NewServer should register all 15 tools, got %d", len(tools))
 	}
 }
 
 func TestProfileConsistency(t *testing.T) {
-	// Verify that agent + admin = all 14 tools
+	// Verify that agent + admin = all 15 tools
 	combined := make(map[string]bool)
 	for tool := range ProfileAgent {
 		combined[tool] = true
@@ -1219,8 +1220,8 @@ func TestProfileConsistency(t *testing.T) {
 		combined[tool] = true
 	}
 
-	if len(combined) != 14 {
-		t.Errorf("agent + admin should cover all 14 tools, got %d", len(combined))
+	if len(combined) != 15 {
+		t.Errorf("agent + admin should cover all 15 tools, got %d", len(combined))
 	}
 
 	// Verify no overlap between profiles

internal/server/server.go

@@ -131,6 +131,9 @@ func (s *Server) routes() {
 	// Stats
 	s.mux.HandleFunc("GET /stats", s.handleStats)
 
+	// Promoted (frequently recalled)
+	s.mux.HandleFunc("GET /promoted", s.handlePromoted)
+
 	// Project migration
 	s.mux.HandleFunc("POST /projects/migrate", s.handleMigrateProject)
 
@@ -493,6 +496,21 @@ func (s *Server) handleStats(w http.ResponseWriter, r *http.Request) {
 	jsonResponse(w, http.StatusOK, stats)
 }
 
+func (s *Server) handlePromoted(w http.ResponseWriter, r *http.Request) {
+	project := r.URL.Query().Get("project")
+	scope := r.URL.Query().Get("scope")
+	minRecalls := queryInt(r, "min_recalls", 5)
+	limit := queryInt(r, "limit", 7)
+
+	obs, err := s.store.PromotedObservations(project, scope, minRecalls, limit)
+	if err != nil {
+		jsonError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+
+	jsonResponse(w, http.StatusOK, obs)
+}
+
 // ─── Sync Status ─────────────────────────────────────────────────────────────
 
 func (s *Server) handleSyncStatus(w http.ResponseWriter, r *http.Request) {