Version: 0.9.23.dev.260416

后端： 1. Memory 管理面 API 落地（“我的记忆”增删改查 + 恢复） - 补齐 List/Get/Create/Update/Delete/Restore 的 handler、请求模型与返回视图 - 注册 `/api/v1/memory/items*` 路由并接入 MemoryHandler - 新增 memory item not found / invalid memory type / invalid memory content 三类管理面错误码 2. Memory Module / Service / Repo 扩展为“可管理 + 可治理”门面 - 新增 NewModuleWithObserve / ObserveDeps，导出 GetItem / CreateItem / UpdateItem / DeleteItem / RestoreItem / RunDedupCleanup / MemoryObserver / MemoryMetrics - 新增手动新增、修改、恢复能力；删除链路切到 SoftDeleteByID；所有管理动作统一事务内写 audit，并桥接向量同步与管理面观测 - 补齐 CreateItemFields / UpdateItemFields、单条 Create、管理侧字段更新、软删/恢复，以及 dedup 扫描/归档所需 repo 能力 - 审计操作补齐 archive / restore 3. Memory 读侧与注入侧观测补齐 - HybridRetrieve 返回 telemetry，统一记录 pinned hit / semantic hit / dedup drop / degraded / RAG fallback，并上报读取命中、去重丢弃、RAG 降级指标 - AgentService 持有 memory observer / metrics；injectMemoryContext 对读取失败、空注入、成功注入补齐结构化日志与注入计数 4. Worker / 决策 / 向量同步链路治理增强 - 召回结果显式携带 fallbackMode；hash 精确命中、rag→mysql 降级、最终动作统一写入决策观测 - 接入 vectorSyncer / observer / metrics；为 job 重试、任务成功/失败、决策分布与 fallback 补齐打点；向量 upsert/delete 统一改走公共 Syncer，并收敛 parseMemoryID 解析逻辑 5. 启动层接入 Memory 观测依赖 - 启动时创建 LoggerObserver + MetricsRegistry，并通过 NewModuleWithObserve 注入 memory 模块前端：无仓库：无
2026-04-16 19:34:32 +08:00
parent a1b2ffedb8
commit fad3aed30a
23 changed files with 2527 additions and 121 deletions
--- a/backend/memory/service/manage_service.go
+++ b/backend/memory/service/manage_service.go
@@ -7,15 +7,20 @@ import (
 	"time"

 	memorymodel "github.com/LoveLosita/smartflow/backend/memory/model"
+	memoryobserve "github.com/LoveLosita/smartflow/backend/memory/observe"
 	memoryrepo "github.com/LoveLosita/smartflow/backend/memory/repo"
 	memoryutils "github.com/LoveLosita/smartflow/backend/memory/utils"
+	memoryvectorsync "github.com/LoveLosita/smartflow/backend/memory/vectorsync"
 	"github.com/LoveLosita/smartflow/backend/model"
+	"github.com/LoveLosita/smartflow/backend/respond"
 	"gorm.io/gorm"
 )

 const (
-	defaultManageListLimit = 20
-	maxManageListLimit     = 100
+	defaultManageListLimit  = 20
+	maxManageListLimit      = 100
+	defaultManualConfidence = 0.95
+	defaultManualImportance = 0.90
 )

 // ManageService 负责 memory 模块内部的管理面能力。
@@ -29,6 +34,9 @@ type ManageService struct {
 	itemRepo     *memoryrepo.ItemRepo
 	auditRepo    *memoryrepo.AuditRepo
 	settingsRepo *memoryrepo.SettingsRepo
+	vectorSyncer *memoryvectorsync.Syncer
+	observer     memoryobserve.Observer
+	metrics      memoryobserve.MetricsRecorder
 }

 func NewManageService(
@@ -36,12 +44,24 @@ func NewManageService(
 	itemRepo *memoryrepo.ItemRepo,
 	auditRepo *memoryrepo.AuditRepo,
 	settingsRepo *memoryrepo.SettingsRepo,
+	vectorSyncer *memoryvectorsync.Syncer,
+	observer memoryobserve.Observer,
+	metrics memoryobserve.MetricsRecorder,
 ) *ManageService {
+	if observer == nil {
+		observer = memoryobserve.NewNopObserver()
+	}
+	if metrics == nil {
+		metrics = memoryobserve.NewNopMetrics()
+	}
 	return &ManageService{
 		db:           db,
 		itemRepo:     itemRepo,
 		auditRepo:    auditRepo,
 		settingsRepo: settingsRepo,
+		vectorSyncer: vectorSyncer,
+		observer:     observer,
+		metrics:      metrics,
 	}
 }

@@ -77,18 +97,152 @@ func (s *ManageService) ListItems(ctx context.Context, req memorymodel.ListItems
 	return toItemDTOs(items), nil
 }

+// GetItem 返回“当前用户自己的某条记忆”详情。
+func (s *ManageService) GetItem(ctx context.Context, req model.MemoryGetItemRequest) (*memorymodel.ItemDTO, error) {
+	if s == nil || s.itemRepo == nil {
+		return nil, errors.New("memory manage service is nil")
+	}
+	if req.UserID <= 0 {
+		return nil, respond.WrongUserID
+	}
+	if req.MemoryID <= 0 {
+		return nil, respond.WrongParamType
+	}
+
+	item, err := s.itemRepo.GetByIDForUser(ctx, req.UserID, req.MemoryID)
+	if err != nil {
+		return nil, translateManageError(err)
+	}
+	dto := toItemDTO(*item)
+	return &dto, nil
+}
+
+// CreateItem 手动新增一条用户记忆，并补审计与向量同步桥接。
+func (s *ManageService) CreateItem(ctx context.Context, req model.MemoryCreateItemRequest) (*memorymodel.ItemDTO, error) {
+	if s == nil || s.db == nil || s.itemRepo == nil || s.auditRepo == nil {
+		return nil, errors.New("memory manage service is not initialized")
+	}
+	if req.UserID <= 0 {
+		return nil, respond.WrongUserID
+	}
+
+	fields, err := buildCreateItemFields(req)
+	if err != nil {
+		s.recordManageAction(ctx, "create", req.UserID, 0, fields.MemoryType, false, err)
+		return nil, err
+	}
+
+	var createdItem model.MemoryItem
+	err = s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		itemRepo := s.itemRepo.WithTx(tx)
+		auditRepo := s.auditRepo.WithTx(tx)
+
+		created, createErr := itemRepo.Create(ctx, fields)
+		if createErr != nil {
+			return createErr
+		}
+		createdItem = *created
+
+		audit := memoryutils.BuildItemAuditLog(
+			createdItem.ID,
+			createdItem.UserID,
+			memoryutils.AuditOperationCreate,
+			memoryutils.NormalizeOperatorType(req.OperatorType),
+			normalizeManageReason(req.Reason, "用户手动新增记忆"),
+			nil,
+			&createdItem,
+		)
+		return auditRepo.Create(ctx, audit)
+	})
+	if err != nil {
+		err = translateManageError(err)
+		s.recordManageAction(ctx, "create", req.UserID, 0, fields.MemoryType, false, err)
+		return nil, err
+	}
+
+	s.vectorSyncer.Upsert(ctx, "", []model.MemoryItem{createdItem})
+	s.recordManageAction(ctx, "create", req.UserID, createdItem.ID, createdItem.MemoryType, true, nil)
+	dto := toItemDTO(createdItem)
+	return &dto, nil
+}
+
+// UpdateItem 手动修改一条用户记忆，并补审计与向量重同步桥接。
+func (s *ManageService) UpdateItem(ctx context.Context, req model.MemoryUpdateItemRequest) (*memorymodel.ItemDTO, error) {
+	if s == nil || s.db == nil || s.itemRepo == nil || s.auditRepo == nil {
+		return nil, errors.New("memory manage service is not initialized")
+	}
+	if req.UserID <= 0 {
+		return nil, respond.WrongUserID
+	}
+	if req.MemoryID <= 0 {
+		return nil, respond.WrongParamType
+	}
+
+	var updatedItem model.MemoryItem
+	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		itemRepo := s.itemRepo.WithTx(tx)
+		auditRepo := s.auditRepo.WithTx(tx)
+
+		current, getErr := itemRepo.GetByIDForUser(ctx, req.UserID, req.MemoryID)
+		if getErr != nil {
+			return getErr
+		}
+
+		fields, afterItem, buildErr := buildUpdateItemFields(req, *current)
+		if buildErr != nil {
+			return buildErr
+		}
+		now := time.Now()
+		afterItem.UpdatedAt = &now
+		afterItem.VectorStatus = "pending"
+
+		if updateErr := itemRepo.UpdateManagedFieldsByIDAt(ctx, req.UserID, req.MemoryID, fields, now); updateErr != nil {
+			return updateErr
+		}
+
+		audit := memoryutils.BuildItemAuditLog(
+			current.ID,
+			current.UserID,
+			memoryutils.AuditOperationUpdate,
+			memoryutils.NormalizeOperatorType(req.OperatorType),
+			normalizeManageReason(req.Reason, "用户手动修改记忆"),
+			current,
+			&afterItem,
+		)
+		if auditErr := auditRepo.Create(ctx, audit); auditErr != nil {
+			return auditErr
+		}
+
+		updatedItem = afterItem
+		return nil
+	})
+	if err != nil {
+		err = translateManageError(err)
+		s.recordManageAction(ctx, "update", req.UserID, req.MemoryID, resolveUpdateMemoryType(req), false, err)
+		return nil, err
+	}
+
+	s.vectorSyncer.Upsert(ctx, "", []model.MemoryItem{updatedItem})
+	s.recordManageAction(ctx, "update", req.UserID, updatedItem.ID, updatedItem.MemoryType, true, nil)
+	dto := toItemDTO(updatedItem)
+	return &dto, nil
+}
+
 // DeleteItem 软删除一条记忆，并补写审计日志。
 //
 // 步骤化说明：
 // 1. 先在事务里读取当前条目快照，确保审计前镜像和实际删除对象一致；
 // 2. 若该条目已是 deleted，则直接按幂等语义返回，避免重复写多条删除审计；
 // 3. 状态更新成功后再写 audit log，保证“有删除就有审计”，失败时整笔事务回滚。
-func (s *ManageService) DeleteItem(ctx context.Context, req memorymodel.DeleteItemRequest) (*memorymodel.ItemDTO, error) {
+func (s *ManageService) DeleteItem(ctx context.Context, req model.MemoryDeleteItemRequest) (*memorymodel.ItemDTO, error) {
 	if s == nil || s.db == nil || s.itemRepo == nil || s.auditRepo == nil {
 		return nil, errors.New("memory manage service is not initialized")
 	}
-	if req.UserID <= 0 || req.MemoryID <= 0 {
-		return nil, nil
+	if req.UserID <= 0 {
+		return nil, respond.WrongUserID
+	}
+	if req.MemoryID <= 0 {
+		return nil, respond.WrongParamType
 	}

 	now := time.Now()
@@ -113,8 +267,9 @@ func (s *ManageService) DeleteItem(ctx context.Context, req memorymodel.DeleteIt
 		after := before
 		after.Status = model.MemoryItemStatusDeleted
 		after.UpdatedAt = &now
+		after.VectorStatus = "pending"

-		if err = itemRepo.UpdateStatusByIDAt(ctx, req.UserID, req.MemoryID, model.MemoryItemStatusDeleted, now); err != nil {
+		if err = itemRepo.SoftDeleteByID(ctx, req.UserID, req.MemoryID); err != nil {
 			return err
 		}

@@ -135,16 +290,87 @@ func (s *ManageService) DeleteItem(ctx context.Context, req memorymodel.DeleteIt
 		return nil
 	})
 	if err != nil {
+		err = translateManageError(err)
+		s.recordManageAction(ctx, "delete", req.UserID, req.MemoryID, "", false, err)
 		return nil, err
 	}
 	if deletedItem.ID <= 0 {
 		return nil, nil
 	}

+	if deletedItem.Status == model.MemoryItemStatusDeleted {
+		s.vectorSyncer.Delete(ctx, "", []int64{deletedItem.ID})
+	}
+	s.recordManageAction(ctx, "delete", req.UserID, deletedItem.ID, deletedItem.MemoryType, true, nil)
 	result := toItemDTO(deletedItem)
 	return &result, nil
 }

+// RestoreItem 把 archived/deleted 记忆恢复为 active，并补审计与向量同步桥接。
+func (s *ManageService) RestoreItem(ctx context.Context, req model.MemoryRestoreItemRequest) (*memorymodel.ItemDTO, error) {
+	if s == nil || s.db == nil || s.itemRepo == nil || s.auditRepo == nil {
+		return nil, errors.New("memory manage service is not initialized")
+	}
+	if req.UserID <= 0 {
+		return nil, respond.WrongUserID
+	}
+	if req.MemoryID <= 0 {
+		return nil, respond.WrongParamType
+	}
+
+	var restoredItem model.MemoryItem
+	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		itemRepo := s.itemRepo.WithTx(tx)
+		auditRepo := s.auditRepo.WithTx(tx)
+
+		current, getErr := itemRepo.GetByIDForUser(ctx, req.UserID, req.MemoryID)
+		if getErr != nil {
+			return getErr
+		}
+		if current.Status == model.MemoryItemStatusActive {
+			restoredItem = *current
+			return nil
+		}
+
+		now := time.Now()
+		before := *current
+		after := before
+		after.Status = model.MemoryItemStatusActive
+		after.UpdatedAt = &now
+		after.VectorStatus = "pending"
+
+		if restoreErr := itemRepo.RestoreByIDAt(ctx, req.UserID, req.MemoryID, now); restoreErr != nil {
+			return restoreErr
+		}
+
+		audit := memoryutils.BuildItemAuditLog(
+			before.ID,
+			before.UserID,
+			memoryutils.AuditOperationRestore,
+			memoryutils.NormalizeOperatorType(req.OperatorType),
+			normalizeManageReason(req.Reason, "用户恢复记忆"),
+			&before,
+			&after,
+		)
+		if auditErr := auditRepo.Create(ctx, audit); auditErr != nil {
+			return auditErr
+		}
+
+		restoredItem = after
+		return nil
+	})
+	if err != nil {
+		err = translateManageError(err)
+		s.recordManageAction(ctx, "restore", req.UserID, req.MemoryID, "", false, err)
+		return nil, err
+	}
+
+	s.vectorSyncer.Upsert(ctx, "", []model.MemoryItem{restoredItem})
+	s.recordManageAction(ctx, "restore", req.UserID, restoredItem.ID, restoredItem.MemoryType, true, nil)
+	dto := toItemDTO(restoredItem)
+	return &dto, nil
+}
+
 // GetUserSetting 返回用户当前生效的记忆开关。
 //
 // 返回语义：
@@ -201,3 +427,233 @@ func normalizeDeleteReason(reason string) string {
 	}
 	return reason
 }
+
+func normalizeManageReason(reason string, fallback string) string {
+	reason = strings.TrimSpace(reason)
+	if reason == "" {
+		return fallback
+	}
+	return reason
+}
+
+func translateManageError(err error) error {
+	switch {
+	case err == nil:
+		return nil
+	case errors.Is(err, gorm.ErrRecordNotFound):
+		return respond.MemoryItemNotFound
+	default:
+		return err
+	}
+}
+
+func buildCreateItemFields(req model.MemoryCreateItemRequest) (memorymodel.CreateItemFields, error) {
+	memoryType, err := normalizeManagedMemoryType(req.MemoryType)
+	if err != nil {
+		return memorymodel.CreateItemFields{}, err
+	}
+	content, normalizedContent, err := normalizeManagedContent(req.Content)
+	if err != nil {
+		return memorymodel.CreateItemFields{}, err
+	}
+
+	title := normalizeManagedTitle(req.Title, content)
+	return memorymodel.CreateItemFields{
+		UserID:            req.UserID,
+		ConversationID:    strings.TrimSpace(req.ConversationID),
+		AssistantID:       strings.TrimSpace(req.AssistantID),
+		RunID:             strings.TrimSpace(req.RunID),
+		MemoryType:        memoryType,
+		Title:             title,
+		Content:           content,
+		NormalizedContent: normalizedContent,
+		ContentHash:       memoryutils.HashContent(memoryType, normalizedContent),
+		Confidence:        normalizeManageScore(req.Confidence, defaultManualConfidence),
+		Importance:        normalizeManageScore(req.Importance, defaultManualImportance),
+		SensitivityLevel:  normalizeManageSensitivity(req.SensitivityLevel, 0),
+		IsExplicit:        normalizeManageBool(req.IsExplicit, true),
+		Status:            model.MemoryItemStatusActive,
+		TTLAt:             req.TTLAt,
+		VectorStatus:      "pending",
+	}, nil
+}
+
+func buildUpdateItemFields(
+	req model.MemoryUpdateItemRequest,
+	current model.MemoryItem,
+) (memorymodel.UpdateItemFields, model.MemoryItem, error) {
+	memoryType := current.MemoryType
+	if req.MemoryType != nil {
+		normalizedType, err := normalizeManagedMemoryType(*req.MemoryType)
+		if err != nil {
+			return memorymodel.UpdateItemFields{}, model.MemoryItem{}, err
+		}
+		memoryType = normalizedType
+	}
+
+	content := current.Content
+	if req.Content != nil {
+		normalizedContentValue, _, err := normalizeManagedContent(*req.Content)
+		if err != nil {
+			return memorymodel.UpdateItemFields{}, model.MemoryItem{}, err
+		}
+		content = normalizedContentValue
+	}
+	normalizedContent := normalizeContentForHash(content)
+	if normalizedContent == "" {
+		return memorymodel.UpdateItemFields{}, model.MemoryItem{}, respond.MemoryInvalidContent
+	}
+
+	title := current.Title
+	if req.Title != nil {
+		title = normalizeManagedTitle(*req.Title, content)
+	}
+	ttlAt := current.TTLAt
+	if req.ClearTTL {
+		ttlAt = nil
+	} else if req.TTLAt != nil {
+		ttlAt = req.TTLAt
+	}
+
+	fields := memorymodel.UpdateItemFields{
+		MemoryType:        memoryType,
+		Title:             title,
+		Content:           content,
+		NormalizedContent: normalizedContent,
+		ContentHash:       memoryutils.HashContent(memoryType, normalizedContent),
+		Confidence:        normalizeManageScore(req.Confidence, current.Confidence),
+		Importance:        normalizeManageScore(req.Importance, current.Importance),
+		SensitivityLevel:  normalizeManageSensitivity(req.SensitivityLevel, current.SensitivityLevel),
+		IsExplicit:        normalizeManageBool(req.IsExplicit, current.IsExplicit),
+		TTLAt:             ttlAt,
+	}
+
+	after := current
+	after.MemoryType = fields.MemoryType
+	after.Title = fields.Title
+	after.Content = fields.Content
+	after.NormalizedContent = strPtr(fields.NormalizedContent)
+	after.ContentHash = strPtr(fields.ContentHash)
+	after.Confidence = fields.Confidence
+	after.Importance = fields.Importance
+	after.SensitivityLevel = fields.SensitivityLevel
+	after.IsExplicit = fields.IsExplicit
+	after.TTLAt = fields.TTLAt
+	return fields, after, nil
+}
+
+func normalizeManagedMemoryType(raw string) (string, error) {
+	normalized := memorymodel.NormalizeMemoryType(raw)
+	if normalized == "" {
+		return "", respond.MemoryInvalidType
+	}
+	return normalized, nil
+}
+
+func normalizeManagedContent(raw string) (string, string, error) {
+	content := strings.TrimSpace(raw)
+	if content == "" {
+		return "", "", respond.MemoryInvalidContent
+	}
+	normalized := normalizeContentForHash(content)
+	if normalized == "" {
+		return "", "", respond.MemoryInvalidContent
+	}
+	return content, normalized, nil
+}
+
+func normalizeManagedTitle(raw string, content string) string {
+	title := strings.TrimSpace(raw)
+	if title != "" {
+		return title
+	}
+	content = strings.TrimSpace(content)
+	if content == "" {
+		return "未命名记忆"
+	}
+	runes := []rune(content)
+	if len(runes) > 24 {
+		return string(runes[:24])
+	}
+	return content
+}
+
+func normalizeManageScore(value *float64, defaultValue float64) float64 {
+	if value == nil {
+		return clamp01(defaultValue)
+	}
+	return clamp01(*value)
+}
+
+func normalizeManageSensitivity(value *int, defaultValue int) int {
+	if value == nil {
+		return defaultValue
+	}
+	if *value < 0 {
+		return defaultValue
+	}
+	return *value
+}
+
+func normalizeManageBool(value *bool, defaultValue bool) bool {
+	if value == nil {
+		return defaultValue
+	}
+	return *value
+}
+
+func resolveUpdateMemoryType(req model.MemoryUpdateItemRequest) string {
+	if req.MemoryType == nil {
+		return ""
+	}
+	return strings.TrimSpace(*req.MemoryType)
+}
+
+func strPtr(value string) *string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return nil
+	}
+	result := value
+	return &result
+}
+
+func (s *ManageService) recordManageAction(
+	ctx context.Context,
+	operation string,
+	userID int,
+	memoryID int64,
+	memoryType string,
+	success bool,
+	err error,
+) {
+	if s == nil {
+		return
+	}
+
+	status := "success"
+	level := memoryobserve.LevelInfo
+	if !success || err != nil {
+		status = "error"
+		level = memoryobserve.LevelWarn
+	}
+
+	s.metrics.AddCounter(memoryobserve.MetricManageTotal, 1, map[string]string{
+		"operation": strings.TrimSpace(operation),
+		"status":    status,
+	})
+	s.observer.Observe(ctx, memoryobserve.Event{
+		Level:     level,
+		Component: memoryobserve.ComponentManage,
+		Operation: memoryobserve.OperationManage,
+		Fields: map[string]any{
+			"user_id":     userID,
+			"memory_id":   memoryID,
+			"action":      strings.TrimSpace(operation),
+			"memory_type": strings.TrimSpace(memoryType),
+			"success":     success && err == nil,
+			"error":       err,
+			"error_code":  memoryobserve.ClassifyError(err),
+		},
+	})
+}
--- a/backend/memory/service/read_service.go
+++ b/backend/memory/service/read_service.go
@@ -10,6 +10,7 @@ import (

 	infrarag "github.com/LoveLosita/smartflow/backend/infra/rag"
 	memorymodel "github.com/LoveLosita/smartflow/backend/memory/model"
+	memoryobserve "github.com/LoveLosita/smartflow/backend/memory/observe"
 	memoryrepo "github.com/LoveLosita/smartflow/backend/memory/repo"
 	memoryutils "github.com/LoveLosita/smartflow/backend/memory/utils"
 	"github.com/LoveLosita/smartflow/backend/model"
@@ -31,6 +32,26 @@ type ReadService struct {
 	settingsRepo *memoryrepo.SettingsRepo
 	ragRuntime   infrarag.Runtime
 	cfg          memorymodel.Config
+	observer     memoryobserve.Observer
+	metrics      memoryobserve.MetricsRecorder
+}
+
+type retrieveTelemetry struct {
+	ReadMode         string
+	QueryLen         int
+	LegacyHitCount   int
+	PinnedHitCount   int
+	SemanticHitCount int
+	DedupDropCount   int
+	FinalCount       int
+	Degraded         bool
+	RAGFallbackUsed  bool
+}
+
+type semanticRetrieveTelemetry struct {
+	HitCount        int
+	Degraded        bool
+	RAGFallbackUsed bool
 }

 func NewReadService(
@@ -38,12 +59,22 @@ func NewReadService(
 	settingsRepo *memoryrepo.SettingsRepo,
 	ragRuntime infrarag.Runtime,
 	cfg memorymodel.Config,
+	observer memoryobserve.Observer,
+	metrics memoryobserve.MetricsRecorder,
 ) *ReadService {
+	if observer == nil {
+		observer = memoryobserve.NewNopObserver()
+	}
+	if metrics == nil {
+		metrics = memoryobserve.NewNopMetrics()
+	}
 	return &ReadService{
 		itemRepo:     itemRepo,
 		settingsRepo: settingsRepo,
 		ragRuntime:   ragRuntime,
 		cfg:          cfg,
+		observer:     observer,
+		metrics:      metrics,
 	}
 }

@@ -60,9 +91,14 @@ func (s *ReadService) Retrieve(ctx context.Context, req memorymodel.RetrieveRequ
 	if now.IsZero() {
 		now = time.Now()
 	}
+	telemetry := retrieveTelemetry{
+		ReadMode: s.cfg.EffectiveReadMode(),
+		QueryLen: len(strings.TrimSpace(req.Query)),
+	}

 	setting, err := s.settingsRepo.GetByUserID(ctx, req.UserID)
 	if err != nil {
+		s.recordRetrieve(ctx, req, telemetry, err)
 		return nil, err
 	}
 	effectiveSetting := memoryutils.EffectiveUserSetting(setting, req.UserID)
@@ -72,16 +108,29 @@ func (s *ReadService) Retrieve(ctx context.Context, req memorymodel.RetrieveRequ

 	limit := normalizeLimit(req.Limit, defaultRetrieveLimit, maxRetrieveLimit)
 	if s.cfg.EffectiveReadMode() == memorymodel.MemoryReadModeHybrid {
-		return s.HybridRetrieve(ctx, req, effectiveSetting, limit, now)
+		items, hybridTelemetry, hybridErr := s.HybridRetrieve(ctx, req, effectiveSetting, limit, now)
+		hybridTelemetry.ReadMode = memorymodel.MemoryReadModeHybrid
+		hybridTelemetry.QueryLen = telemetry.QueryLen
+		s.recordRetrieve(ctx, req, hybridTelemetry, hybridErr)
+		return items, hybridErr
 	}
 	if s.cfg.RAGEnabled && s.ragRuntime != nil && strings.TrimSpace(req.Query) != "" {
 		items, ragErr := s.retrieveByRAG(ctx, req, effectiveSetting, limit, now)
 		if ragErr == nil && len(items) > 0 {
+			telemetry.SemanticHitCount = len(items)
+			telemetry.FinalCount = len(items)
+			s.recordRetrieve(ctx, req, telemetry, nil)
 			return items, nil
 		}
+		telemetry.Degraded = true
+		telemetry.RAGFallbackUsed = true
 	}

-	return s.retrieveByLegacy(ctx, req, limit, now, effectiveSetting)
+	items, legacyErr := s.retrieveByLegacy(ctx, req, limit, now, effectiveSetting)
+	telemetry.LegacyHitCount = len(items)
+	telemetry.FinalCount = len(items)
+	s.recordRetrieve(ctx, req, telemetry, legacyErr)
+	return items, legacyErr
 }

 func (s *ReadService) retrieveByLegacy(
@@ -180,6 +229,58 @@ func normalizeRetrieveMemoryTypes(raw []string) []string {
 	}
 }

+func (s *ReadService) recordRetrieve(
+	ctx context.Context,
+	req memorymodel.RetrieveRequest,
+	telemetry retrieveTelemetry,
+	err error,
+) {
+	if s == nil {
+		return
+	}
+
+	level := memoryobserve.LevelInfo
+	if err != nil {
+		level = memoryobserve.LevelWarn
+	}
+	s.observer.Observe(ctx, memoryobserve.Event{
+		Level:     level,
+		Component: memoryobserve.ComponentRead,
+		Operation: memoryobserve.OperationRetrieve,
+		Fields: map[string]any{
+			"user_id":            req.UserID,
+			"read_mode":          telemetry.ReadMode,
+			"query_len":          telemetry.QueryLen,
+			"legacy_hit_count":   telemetry.LegacyHitCount,
+			"pinned_hit_count":   telemetry.PinnedHitCount,
+			"semantic_hit_count": telemetry.SemanticHitCount,
+			"dedup_drop_count":   telemetry.DedupDropCount,
+			"final_count":        telemetry.FinalCount,
+			"degraded":           telemetry.Degraded,
+			"rag_fallback_used":  telemetry.RAGFallbackUsed,
+			"success":            err == nil,
+			"error":              err,
+			"error_code":         memoryobserve.ClassifyError(err),
+		},
+	})
+
+	if telemetry.FinalCount > 0 {
+		s.metrics.AddCounter(memoryobserve.MetricRetrieveHitTotal, int64(telemetry.FinalCount), map[string]string{
+			"read_mode": strings.TrimSpace(telemetry.ReadMode),
+		})
+	}
+	if telemetry.DedupDropCount > 0 {
+		s.metrics.AddCounter(memoryobserve.MetricRetrieveDedupDropTotal, int64(telemetry.DedupDropCount), map[string]string{
+			"read_mode": strings.TrimSpace(telemetry.ReadMode),
+		})
+	}
+	if telemetry.RAGFallbackUsed {
+		s.metrics.AddCounter(memoryobserve.MetricRAGFallbackTotal, 1, map[string]string{
+			"read_mode": strings.TrimSpace(telemetry.ReadMode),
+		})
+	}
+}
+
 // scoreRetrievedItem 计算 legacy 读链路的确定性排序分数。
 //
 // 说明：
--- a/backend/memory/service/retrieve_merge.go
+++ b/backend/memory/service/retrieve_merge.go
@@ -23,41 +23,50 @@ func (s *ReadService) HybridRetrieve(
 	effectiveSetting model.MemoryUserSetting,
 	limit int,
 	now time.Time,
-) ([]memorymodel.ItemDTO, error) {
+) ([]memorymodel.ItemDTO, retrieveTelemetry, error) {
+	telemetry := retrieveTelemetry{}
 	if s == nil || s.itemRepo == nil {
-		return nil, nil
+		return nil, telemetry, nil
 	}
 	if !effectiveSetting.MemoryEnabled {
-		return nil, nil
+		return nil, telemetry, nil
 	}

 	pinnedItems, err := s.retrievePinnedCandidates(ctx, req, effectiveSetting, now)
 	if err != nil {
-		return nil, err
+		return nil, telemetry, err
 	}
-	semanticItems, err := s.retrieveSemanticCandidates(ctx, req, effectiveSetting, limit, now)
+	telemetry.PinnedHitCount = len(pinnedItems)
+
+	semanticItems, semanticTelemetry, err := s.retrieveSemanticCandidates(ctx, req, effectiveSetting, limit, now)
 	if err != nil {
-		return nil, err
+		return nil, telemetry, err
 	}
+	telemetry.SemanticHitCount = len(semanticItems)
+	telemetry.Degraded = semanticTelemetry.Degraded
+	telemetry.RAGFallbackUsed = semanticTelemetry.RAGFallbackUsed

 	merged := make([]memorymodel.ItemDTO, 0, len(pinnedItems)+len(semanticItems))
 	merged = append(merged, pinnedItems...)
 	merged = append(merged, semanticItems...)
 	if len(merged) == 0 {
-		return nil, nil
+		return nil, telemetry, nil
 	}

+	beforeDedupCount := len(merged)
 	merged = dedupByID(merged)
 	merged = dedupByHash(merged)
 	merged = dedupByText(merged)
+	telemetry.DedupDropCount = beforeDedupCount - len(merged)
 	merged = RankItems(merged, now)
 	merged = applyTypeBudget(merged, s.cfg)
 	if len(merged) == 0 {
-		return nil, nil
+		return nil, telemetry, nil
 	}
+	telemetry.FinalCount = len(merged)

 	_ = s.itemRepo.TouchLastAccessAt(ctx, collectItemDTOIDs(merged), now)
-	return merged, nil
+	return merged, telemetry, nil
 }

 func (s *ReadService) retrievePinnedCandidates(
@@ -81,20 +90,26 @@ func (s *ReadService) retrieveSemanticCandidates(
 	effectiveSetting model.MemoryUserSetting,
 	limit int,
 	now time.Time,
-) ([]memorymodel.ItemDTO, error) {
+) ([]memorymodel.ItemDTO, semanticRetrieveTelemetry, error) {
+	telemetry := semanticRetrieveTelemetry{}
 	queryText := strings.TrimSpace(req.Query)
 	if queryText == "" {
-		return nil, nil
+		return nil, telemetry, nil
 	}

 	candidateLimit := hybridSemanticTopK(s.cfg, limit)
 	if s.cfg.RAGEnabled && s.ragRuntime != nil {
 		items, err := s.retrieveSemanticCandidatesByRAG(ctx, req, effectiveSetting, candidateLimit, now)
 		if shouldReturnSemanticRAGResult(items, err) {
-			return items, nil
+			telemetry.HitCount = len(items)
+			return items, telemetry, nil
 		}
+		telemetry.Degraded = true
+		telemetry.RAGFallbackUsed = true
 	}
-	return s.retrieveSemanticCandidatesByMySQL(ctx, req, effectiveSetting, candidateLimit, now)
+	items, err := s.retrieveSemanticCandidatesByMySQL(ctx, req, effectiveSetting, candidateLimit, now)
+	telemetry.HitCount = len(items)
+	return items, telemetry, err
 }

 func (s *ReadService) retrieveSemanticCandidatesByRAG(