Version: 0.9.74.dev.260505

后端： 1.阶段 6 memory 服务化 CP1-CP3 落地 - 新增 cmd/memory 独立进程入口，落地 services/memory dao/rpc/sv 与 memory zrpc pb - 将 memory.extract.requested outbox 消费与 memory worker 迁入 cmd/memory，单体 worker 不再消费 memory outbox - 新增 gateway/client/memory、shared/contracts/memory 和 shared/ports memory port - 将 /api/v1/memory/items* HTTP 管理面切到 memory zrpc，gateway 只保留鉴权、限流、幂等、参数绑定和响应透传 - 新增 memory Retrieve RPC，并将 agent 主链路 memory reader 切到 memory zrpc 读取 - 补充 agent memory RPC reader 适配器，保留注入侧 observer / metrics 观测能力 - 保留旧 backend/memory 核心实现作为迁移期复用与回退面，cmd/memory 内部继续复用既有 Module / ReadService 逻辑 - 补充 memory.rpc 示例配置，更新单体 outbox 发布边界与 memory handler 注释口径
2026-05-05 13:52:49 +08:00
parent fd327f845b
commit e1819c5653
19 changed files with 1688 additions and 110 deletions
--- a/backend/services/memory/dao/connect.go
+++ b/backend/services/memory/dao/connect.go
@@ -0,0 +1,89 @@
+package dao
+
+import (
+	"context"
+	"fmt"
+
+	outboxinfra "github.com/LoveLosita/smartflow/backend/infra/outbox"
+	coremodel "github.com/LoveLosita/smartflow/backend/model"
+	"github.com/go-redis/redis/v8"
+	"github.com/spf13/viper"
+	"gorm.io/driver/mysql"
+	"gorm.io/gorm"
+)
+
+// OpenDBFromConfig 创建 memory 服务自己的数据库句柄。
+//
+// 职责边界：
+// 1. 只迁移 memory_items / memory_jobs / memory_audit_logs / memory_user_settings 以及 memory 服务自己的 outbox 表；
+// 2. 不迁移 agent、task、schedule、active-scheduler、notification 等跨域表，避免独立进程越权管理别的领域；
+// 3. 返回的 *gorm.DB 供 memory 服务内部 repo、worker 和 outbox consumer 复用。
+func OpenDBFromConfig() (*gorm.DB, error) {
+	host := viper.GetString("database.host")
+	port := viper.GetString("database.port")
+	user := viper.GetString("database.user")
+	password := viper.GetString("database.password")
+	dbname := viper.GetString("database.dbname")
+
+	dsn := fmt.Sprintf(
+		"%s:%s@tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local",
+		user, password, host, port, dbname,
+	)
+
+	// 1. 先按统一配置建立 MySQL 连接；若连接失败，独立 memory 进程直接 fail fast。
+	db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
+	if err != nil {
+		return nil, err
+	}
+
+	// 2. 只迁移 memory 自有表，明确与 agent/task/schedule 等跨域模型隔离。
+	if err = db.AutoMigrate(
+		&coremodel.MemoryItem{},
+		&coremodel.MemoryJob{},
+		&coremodel.MemoryAuditLog{},
+		&coremodel.MemoryUserSetting{},
+	); err != nil {
+		return nil, fmt.Errorf("auto migrate memory tables failed: %w", err)
+	}
+
+	// 3. 再迁移 memory 服务自己的 outbox 物理表，让独立服务可以单独发布与消费 memory 事件。
+	if err = autoMigrateMemoryOutboxTable(db); err != nil {
+		return nil, err
+	}
+	return db, nil
+}
+
+// OpenRedisFromConfig 创建 memory 服务自己的 Redis 句柄。
+//
+// 职责边界：
+// 1. 只负责初始化 memory 独立进程所需的 Redis client；
+// 2. 不创建、不预热、不清理任何 memory 业务 key；
+// 3. Ping 失败直接返回 error，让入口在缓存、锁或幂等依赖异常时尽早暴露问题。
+func OpenRedisFromConfig() (*redis.Client, error) {
+	client := redis.NewClient(&redis.Options{
+		Addr:     viper.GetString("redis.host") + ":" + viper.GetString("redis.port"),
+		Password: viper.GetString("redis.password"),
+		DB:       0,
+	})
+	if _, err := client.Ping(context.Background()).Result(); err != nil {
+		return nil, err
+	}
+	return client, nil
+}
+
+// autoMigrateMemoryOutboxTable 只迁移 memory 服务自己的 outbox 物理表。
+//
+// 职责边界：
+// 1. 只负责 service catalog 中 memory 对应的 outbox 表，不硬编码别的服务表名；
+// 2. 共享 AgentOutboxMessage 结构作为表结构模板，但物理表仍归 memory 服务所有；
+// 3. 若后续 outbox 表名调整，只改 service catalog，不在这里散落配置。
+func autoMigrateMemoryOutboxTable(db *gorm.DB) error {
+	cfg, ok := outboxinfra.ResolveServiceConfig(outboxinfra.ServiceMemory)
+	if !ok {
+		return fmt.Errorf("resolve memory outbox config failed")
+	}
+	if err := db.Table(cfg.TableName).AutoMigrate(&coremodel.AgentOutboxMessage{}); err != nil {
+		return fmt.Errorf("auto migrate memory outbox table failed for %s (%s): %w", cfg.Name, cfg.TableName, err)
+	}
+	return nil
+}
--- a/backend/services/memory/rpc/errors.go
+++ b/backend/services/memory/rpc/errors.go
@@ -0,0 +1,74 @@
+package rpc
+
+import (
+	"errors"
+	"log"
+	"strings"
+
+	"github.com/LoveLosita/smartflow/backend/respond"
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+var (
+	errMemoryServiceNotReady = errors.New("memory service dependency not initialized")
+)
+
+const memoryErrorDomain = "smartflow.memory"
+
+// grpcErrorFromServiceError 负责把 memory 内部错误转换为 gRPC status。
+//
+// 职责边界：
+// 1. respond.Response 保留项目内部 status/info，供 gateway 反解；
+// 2. 未分类错误只暴露通用内部错误，详细信息留在服务日志；
+// 3. 不在 RPC 层重判业务规则，业务语义仍由 memory.Module 决定。
+func grpcErrorFromServiceError(err error) error {
+	if err == nil {
+		return nil
+	}
+	var resp respond.Response
+	if errors.As(err, &resp) {
+		return grpcErrorFromResponse(resp)
+	}
+	log.Printf("memory rpc internal error: %v", err)
+	return status.Error(codes.Internal, "memory service internal error")
+}
+
+func grpcErrorFromResponse(resp respond.Response) error {
+	code := grpcCodeFromRespondStatus(resp.Status)
+	message := strings.TrimSpace(resp.Info)
+	if message == "" {
+		message = strings.TrimSpace(resp.Status)
+	}
+	st := status.New(code, message)
+	detail := &errdetails.ErrorInfo{
+		Domain: memoryErrorDomain,
+		Reason: resp.Status,
+		Metadata: map[string]string{
+			"info": resp.Info,
+		},
+	}
+	withDetails, err := st.WithDetails(detail)
+	if err != nil {
+		return st.Err()
+	}
+	return withDetails.Err()
+}
+
+func grpcCodeFromRespondStatus(statusValue string) codes.Code {
+	switch strings.TrimSpace(statusValue) {
+	case respond.MissingToken.Status, respond.InvalidToken.Status, respond.InvalidClaims.Status,
+		respond.ErrUnauthorized.Status, respond.WrongTokenType.Status, respond.UserLoggedOut.Status:
+		return codes.Unauthenticated
+	case respond.MemoryItemNotFound.Status:
+		return codes.NotFound
+	case respond.MissingParam.Status, respond.WrongParamType.Status, respond.ParamTooLong.Status,
+		respond.WrongUserID.Status, respond.MemoryInvalidType.Status, respond.MemoryInvalidContent.Status:
+		return codes.InvalidArgument
+	}
+	if strings.HasPrefix(strings.TrimSpace(statusValue), "5") {
+		return codes.Internal
+	}
+	return codes.InvalidArgument
+}
--- a/backend/services/memory/rpc/handler.go
+++ b/backend/services/memory/rpc/handler.go
@@ -0,0 +1,136 @@
+package rpc
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/LoveLosita/smartflow/backend/respond"
+	"github.com/LoveLosita/smartflow/backend/services/memory/rpc/pb"
+	memorysv "github.com/LoveLosita/smartflow/backend/services/memory/sv"
+	memorycontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/memory"
+)
+
+type Handler struct {
+	pb.UnimplementedMemoryServer
+	svc *memorysv.Service
+}
+
+func NewHandler(svc *memorysv.Service) *Handler {
+	return &Handler{svc: svc}
+}
+
+// Ping 供调用方在启动期确认 memory zrpc 已可用。
+func (h *Handler) Ping(ctx context.Context, req *pb.StatusResponse) (*pb.StatusResponse, error) {
+	if err := h.ensureReady(req); err != nil {
+		return nil, err
+	}
+	if err := h.svc.Ping(ctx); err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.StatusResponse{}, nil
+}
+
+func (h *Handler) Retrieve(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	if err := h.ensureReady(req); err != nil {
+		return nil, err
+	}
+	var contractReq memorycontracts.RetrieveRequest
+	if err := json.Unmarshal(req.PayloadJson, &contractReq); err != nil {
+		return nil, grpcErrorFromServiceError(respond.WrongParamType)
+	}
+	data, err := h.svc.Retrieve(ctx, contractReq)
+	return jsonResponse(data, err)
+}
+
+func (h *Handler) ListItems(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	if err := h.ensureReady(req); err != nil {
+		return nil, err
+	}
+	var contractReq memorycontracts.ListItemsRequest
+	if err := json.Unmarshal(req.PayloadJson, &contractReq); err != nil {
+		return nil, grpcErrorFromServiceError(respond.WrongParamType)
+	}
+	data, err := h.svc.ListItems(ctx, contractReq)
+	return jsonResponse(data, err)
+}
+
+func (h *Handler) GetItem(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	if err := h.ensureReady(req); err != nil {
+		return nil, err
+	}
+	var contractReq memorycontracts.GetItemRequest
+	if err := json.Unmarshal(req.PayloadJson, &contractReq); err != nil {
+		return nil, grpcErrorFromServiceError(respond.WrongParamType)
+	}
+	data, err := h.svc.GetItem(ctx, contractReq)
+	return jsonResponse(data, err)
+}
+
+func (h *Handler) CreateItem(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	if err := h.ensureReady(req); err != nil {
+		return nil, err
+	}
+	var contractReq memorycontracts.CreateItemRequest
+	if err := json.Unmarshal(req.PayloadJson, &contractReq); err != nil {
+		return nil, grpcErrorFromServiceError(respond.WrongParamType)
+	}
+	data, err := h.svc.CreateItem(ctx, contractReq)
+	return jsonResponse(data, err)
+}
+
+func (h *Handler) UpdateItem(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	if err := h.ensureReady(req); err != nil {
+		return nil, err
+	}
+	var contractReq memorycontracts.UpdateItemRequest
+	if err := json.Unmarshal(req.PayloadJson, &contractReq); err != nil {
+		return nil, grpcErrorFromServiceError(respond.WrongParamType)
+	}
+	data, err := h.svc.UpdateItem(ctx, contractReq)
+	return jsonResponse(data, err)
+}
+
+func (h *Handler) DeleteItem(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	if err := h.ensureReady(req); err != nil {
+		return nil, err
+	}
+	var contractReq memorycontracts.DeleteItemRequest
+	if err := json.Unmarshal(req.PayloadJson, &contractReq); err != nil {
+		return nil, grpcErrorFromServiceError(respond.WrongParamType)
+	}
+	data, err := h.svc.DeleteItem(ctx, contractReq)
+	return jsonResponse(data, err)
+}
+
+func (h *Handler) RestoreItem(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	if err := h.ensureReady(req); err != nil {
+		return nil, err
+	}
+	var contractReq memorycontracts.RestoreItemRequest
+	if err := json.Unmarshal(req.PayloadJson, &contractReq); err != nil {
+		return nil, grpcErrorFromServiceError(respond.WrongParamType)
+	}
+	data, err := h.svc.RestoreItem(ctx, contractReq)
+	return jsonResponse(data, err)
+}
+
+func (h *Handler) ensureReady(req any) error {
+	if h == nil || h.svc == nil {
+		return grpcErrorFromServiceError(errMemoryServiceNotReady)
+	}
+	if req == nil {
+		return grpcErrorFromServiceError(respond.MissingParam)
+	}
+	return nil
+}
+
+func jsonResponse(value any, err error) (*pb.JSONResponse, error) {
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	raw, err := json.Marshal(value)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.JSONResponse{DataJson: raw}, nil
+}
--- a/backend/services/memory/rpc/memory.proto
+++ b/backend/services/memory/rpc/memory.proto
@@ -0,0 +1,27 @@
+syntax = "proto3";
+
+package smartflow.memory;
+
+option go_package = "github.com/LoveLosita/smartflow/backend/services/memory/rpc/pb";
+
+service Memory {
+  rpc Ping(StatusResponse) returns (StatusResponse);
+  rpc Retrieve(JSONRequest) returns (JSONResponse);
+  rpc ListItems(JSONRequest) returns (JSONResponse);
+  rpc GetItem(JSONRequest) returns (JSONResponse);
+  rpc CreateItem(JSONRequest) returns (JSONResponse);
+  rpc UpdateItem(JSONRequest) returns (JSONResponse);
+  rpc DeleteItem(JSONRequest) returns (JSONResponse);
+  rpc RestoreItem(JSONRequest) returns (JSONResponse);
+}
+
+message JSONRequest {
+  bytes payload_json = 1;
+}
+
+message JSONResponse {
+  bytes data_json = 1;
+}
+
+message StatusResponse {
+}
--- a/backend/services/memory/rpc/pb/memory.pb.go
+++ b/backend/services/memory/rpc/pb/memory.pb.go
@@ -0,0 +1,39 @@
+package pb
+
+import proto "github.com/golang/protobuf/proto"
+
+var _ = proto.Marshal
+
+const _ = proto.ProtoPackageIsVersion3
+
+type JSONRequest struct {
+	PayloadJson          []byte   `protobuf:"bytes,1,opt,name=payload_json,json=payloadJson,proto3" json:"payload_json,omitempty"`
+	XXX_NoUnkeyedLiteral struct{} `json:"-"`
+	XXX_unrecognized     []byte   `json:"-"`
+	XXX_sizecache        int32    `json:"-"`
+}
+
+func (m *JSONRequest) Reset()         { *m = JSONRequest{} }
+func (m *JSONRequest) String() string { return proto.CompactTextString(m) }
+func (*JSONRequest) ProtoMessage()    {}
+
+type JSONResponse struct {
+	DataJson             []byte   `protobuf:"bytes,1,opt,name=data_json,json=dataJson,proto3" json:"data_json,omitempty"`
+	XXX_NoUnkeyedLiteral struct{} `json:"-"`
+	XXX_unrecognized     []byte   `json:"-"`
+	XXX_sizecache        int32    `json:"-"`
+}
+
+func (m *JSONResponse) Reset()         { *m = JSONResponse{} }
+func (m *JSONResponse) String() string { return proto.CompactTextString(m) }
+func (*JSONResponse) ProtoMessage()    {}
+
+type StatusResponse struct {
+	XXX_NoUnkeyedLiteral struct{} `json:"-"`
+	XXX_unrecognized     []byte   `json:"-"`
+	XXX_sizecache        int32    `json:"-"`
+}
+
+func (m *StatusResponse) Reset()         { *m = StatusResponse{} }
+func (m *StatusResponse) String() string { return proto.CompactTextString(m) }
+func (*StatusResponse) ProtoMessage()    {}
--- a/backend/services/memory/rpc/pb/memory_grpc.pb.go
+++ b/backend/services/memory/rpc/pb/memory_grpc.pb.go
@@ -0,0 +1,181 @@
+package pb
+
+import (
+	context "context"
+
+	grpc "google.golang.org/grpc"
+	codes "google.golang.org/grpc/codes"
+	status "google.golang.org/grpc/status"
+)
+
+const (
+	Memory_Ping_FullMethodName        = "/smartflow.memory.Memory/Ping"
+	Memory_Retrieve_FullMethodName    = "/smartflow.memory.Memory/Retrieve"
+	Memory_ListItems_FullMethodName   = "/smartflow.memory.Memory/ListItems"
+	Memory_GetItem_FullMethodName     = "/smartflow.memory.Memory/GetItem"
+	Memory_CreateItem_FullMethodName  = "/smartflow.memory.Memory/CreateItem"
+	Memory_UpdateItem_FullMethodName  = "/smartflow.memory.Memory/UpdateItem"
+	Memory_DeleteItem_FullMethodName  = "/smartflow.memory.Memory/DeleteItem"
+	Memory_RestoreItem_FullMethodName = "/smartflow.memory.Memory/RestoreItem"
+)
+
+type MemoryClient interface {
+	Ping(ctx context.Context, in *StatusResponse, opts ...grpc.CallOption) (*StatusResponse, error)
+	Retrieve(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+	ListItems(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+	GetItem(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+	CreateItem(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+	UpdateItem(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+	DeleteItem(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+	RestoreItem(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+}
+
+type memoryClient struct {
+	cc grpc.ClientConnInterface
+}
+
+func NewMemoryClient(cc grpc.ClientConnInterface) MemoryClient {
+	return &memoryClient{cc}
+}
+
+func (c *memoryClient) Ping(ctx context.Context, in *StatusResponse, opts ...grpc.CallOption) (*StatusResponse, error) {
+	out := new(StatusResponse)
+	err := c.cc.Invoke(ctx, Memory_Ping_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *memoryClient) Retrieve(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Memory_Retrieve_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *memoryClient) ListItems(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Memory_ListItems_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *memoryClient) GetItem(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Memory_GetItem_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *memoryClient) CreateItem(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Memory_CreateItem_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *memoryClient) UpdateItem(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Memory_UpdateItem_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *memoryClient) DeleteItem(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Memory_DeleteItem_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *memoryClient) RestoreItem(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Memory_RestoreItem_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+type MemoryServer interface {
+	Ping(context.Context, *StatusResponse) (*StatusResponse, error)
+	Retrieve(context.Context, *JSONRequest) (*JSONResponse, error)
+	ListItems(context.Context, *JSONRequest) (*JSONResponse, error)
+	GetItem(context.Context, *JSONRequest) (*JSONResponse, error)
+	CreateItem(context.Context, *JSONRequest) (*JSONResponse, error)
+	UpdateItem(context.Context, *JSONRequest) (*JSONResponse, error)
+	DeleteItem(context.Context, *JSONRequest) (*JSONResponse, error)
+	RestoreItem(context.Context, *JSONRequest) (*JSONResponse, error)
+}
+
+type UnimplementedMemoryServer struct{}
+
+func (UnimplementedMemoryServer) Ping(context.Context, *StatusResponse) (*StatusResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method Ping not implemented")
+}
+func (UnimplementedMemoryServer) Retrieve(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method Retrieve not implemented")
+}
+func (UnimplementedMemoryServer) ListItems(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ListItems not implemented")
+}
+func (UnimplementedMemoryServer) GetItem(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method GetItem not implemented")
+}
+func (UnimplementedMemoryServer) CreateItem(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method CreateItem not implemented")
+}
+func (UnimplementedMemoryServer) UpdateItem(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method UpdateItem not implemented")
+}
+func (UnimplementedMemoryServer) DeleteItem(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method DeleteItem not implemented")
+}
+func (UnimplementedMemoryServer) RestoreItem(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method RestoreItem not implemented")
+}
+
+func RegisterMemoryServer(s grpc.ServiceRegistrar, srv MemoryServer) {
+	s.RegisterService(&Memory_ServiceDesc, srv)
+}
+
+func _Memory_Ping_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(StatusResponse)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(MemoryServer).Ping(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: Memory_Ping_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(MemoryServer).Ping(ctx, req.(*StatusResponse))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _Memory_JSON_Handler(fullMethod string, invoke func(MemoryServer, context.Context, *JSONRequest) (*JSONResponse, error)) grpc.MethodHandler {
+	return func(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+		in := new(JSONRequest)
+		if err := dec(in); err != nil {
+			return nil, err
+		}
+		if interceptor == nil {
+			return invoke(srv.(MemoryServer), ctx, in)
+		}
+		info := &grpc.UnaryServerInfo{Server: srv, FullMethod: fullMethod}
+		handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+			return invoke(srv.(MemoryServer), ctx, req.(*JSONRequest))
+		}
+		return interceptor(ctx, in, info, handler)
+	}
+}
+
+var Memory_ServiceDesc = grpc.ServiceDesc{
+	ServiceName: "smartflow.memory.Memory",
+	HandlerType: (*MemoryServer)(nil),
+	Methods: []grpc.MethodDesc{
+		{MethodName: "Ping", Handler: _Memory_Ping_Handler},
+		{MethodName: "Retrieve", Handler: _Memory_JSON_Handler(Memory_Retrieve_FullMethodName, MemoryServer.Retrieve)},
+		{MethodName: "ListItems", Handler: _Memory_JSON_Handler(Memory_ListItems_FullMethodName, MemoryServer.ListItems)},
+		{MethodName: "GetItem", Handler: _Memory_JSON_Handler(Memory_GetItem_FullMethodName, MemoryServer.GetItem)},
+		{MethodName: "CreateItem", Handler: _Memory_JSON_Handler(Memory_CreateItem_FullMethodName, MemoryServer.CreateItem)},
+		{MethodName: "UpdateItem", Handler: _Memory_JSON_Handler(Memory_UpdateItem_FullMethodName, MemoryServer.UpdateItem)},
+		{MethodName: "DeleteItem", Handler: _Memory_JSON_Handler(Memory_DeleteItem_FullMethodName, MemoryServer.DeleteItem)},
+		{MethodName: "RestoreItem", Handler: _Memory_JSON_Handler(Memory_RestoreItem_FullMethodName, MemoryServer.RestoreItem)},
+	},
+	Streams:  []grpc.StreamDesc{},
+	Metadata: "services/memory/rpc/memory.proto",
+}
--- a/backend/services/memory/rpc/server.go
+++ b/backend/services/memory/rpc/server.go
@@ -0,0 +1,60 @@
+package rpc
+
+import (
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/services/memory/rpc/pb"
+	memorysv "github.com/LoveLosita/smartflow/backend/services/memory/sv"
+	"github.com/zeromicro/go-zero/core/service"
+	"github.com/zeromicro/go-zero/zrpc"
+	"google.golang.org/grpc"
+)
+
+const (
+	defaultListenOn = "0.0.0.0:9088"
+	defaultTimeout  = 6 * time.Second
+)
+
+type ServerOptions struct {
+	ListenOn string
+	Timeout  time.Duration
+	Service  *memorysv.Service
+}
+
+// NewServer 创建 memory zrpc 服务端。
+//
+// 职责边界：
+// 1. 只负责 zrpc server 配置与 gRPC handler 注册；
+// 2. 不创建数据库、LLM、RAG、outbox 或 worker，它们由 cmd/memory 管理；
+// 3. 返回 listenOn 供进程入口打印启动日志。
+func NewServer(opts ServerOptions) (*zrpc.RpcServer, string, error) {
+	if opts.Service == nil {
+		return nil, "", errors.New("memory service dependency not initialized")
+	}
+
+	listenOn := strings.TrimSpace(opts.ListenOn)
+	if listenOn == "" {
+		listenOn = defaultListenOn
+	}
+	timeout := opts.Timeout
+	if timeout <= 0 {
+		timeout = defaultTimeout
+	}
+
+	server, err := zrpc.NewServer(zrpc.RpcServerConf{
+		ServiceConf: service.ServiceConf{
+			Name: "memory.rpc",
+			Mode: service.DevMode,
+		},
+		ListenOn: listenOn,
+		Timeout:  int64(timeout / time.Millisecond),
+	}, func(grpcServer *grpc.Server) {
+		pb.RegisterMemoryServer(grpcServer, NewHandler(opts.Service))
+	})
+	if err != nil {
+		return nil, "", err
+	}
+	return server, listenOn, nil
+}
--- a/backend/services/memory/sv/service.go
+++ b/backend/services/memory/sv/service.go
@@ -0,0 +1,297 @@
+package sv
+
+import (
+	"context"
+	"errors"
+	"log"
+
+	kafkabus "github.com/LoveLosita/smartflow/backend/infra/kafka"
+	outboxinfra "github.com/LoveLosita/smartflow/backend/infra/outbox"
+	memorymodule "github.com/LoveLosita/smartflow/backend/memory"
+	memorymodel "github.com/LoveLosita/smartflow/backend/memory/model"
+	coremodel "github.com/LoveLosita/smartflow/backend/model"
+	eventsvc "github.com/LoveLosita/smartflow/backend/service/events"
+	memorycontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/memory"
+)
+
+// Service 是 memory 独立进程的服务门面。
+//
+// 职责边界：
+// 1. 负责持有现有 memory.Module，复用 repo / service / worker / orchestrator 核心逻辑；
+// 2. 负责把 memory.extract.requested 注册到 memory 服务自己的 outbox consumer；
+// 3. 负责承接 CP2 后 gateway memory 管理流量，但不负责 HTTP 参数绑定、鉴权或幂等。
+type Service struct {
+	module   *memorymodule.Module
+	eventBus *outboxinfra.EventBus
+}
+
+// Options 描述 memory 服务启动所需依赖。
+type Options struct {
+	Module      *memorymodule.Module
+	OutboxRepo  *outboxinfra.Repository
+	KafkaConfig kafkabus.Config
+}
+
+// NewService 组装 memory 独立服务。
+//
+// 步骤化说明：
+// 1. 先校验 Module，保证 memory repo / worker / orchestrator 已由启动层完成装配；
+// 2. 再登记 memory.extract.requested -> memory 的服务归属，避免 outbox 路由回落到 agent；
+// 3. 最后在 Kafka 开启时创建 memory 服务自己的 EventBus 并注册消费 handler。
+func NewService(opts Options) (*Service, error) {
+	if opts.Module == nil {
+		return nil, errors.New("memory module dependency not initialized")
+	}
+
+	if err := outboxinfra.RegisterEventService(eventsvc.EventTypeMemoryExtractRequested, outboxinfra.ServiceMemory); err != nil {
+		return nil, err
+	}
+
+	var eventBus *outboxinfra.EventBus
+	if opts.OutboxRepo != nil {
+		bus, err := outboxinfra.NewEventBus(opts.OutboxRepo, opts.KafkaConfig)
+		if err != nil {
+			return nil, err
+		}
+		eventBus = bus
+		if eventBus != nil {
+			if err := eventsvc.RegisterMemoryExtractRequestedHandler(eventBus, opts.OutboxRepo, opts.Module); err != nil {
+				return nil, err
+			}
+		}
+	}
+
+	return &Service{
+		module:   opts.Module,
+		eventBus: eventBus,
+	}, nil
+}
+
+// Ping 用于 zrpc 启动期健康检查。
+//
+// 返回语义：
+// 1. nil 表示 memory Module 已完成装配；
+// 2. error 表示服务依赖缺失，调用方应认为 memory 服务不可用。
+func (s *Service) Ping(context.Context) error {
+	if s == nil || s.module == nil {
+		return errors.New("memory service dependency not initialized")
+	}
+	return nil
+}
+
+// Retrieve 读取 agent 主链路后续可注入 prompt 的候选记忆。
+//
+// 职责边界：
+// 1. 只把跨进程契约转成既有 memory.Module 的读取请求，避免重写召回、门控和降级逻辑；
+// 2. 不负责 prompt 拼装、Redis 预取缓存和主链路失败降级，这些仍留在 agent 服务侧；
+// 3. 返回字段保持与 ItemView 一致，保证 CP3 只改变进程边界，不改变注入内容语义。
+func (s *Service) Retrieve(ctx context.Context, req memorycontracts.RetrieveRequest) ([]memorycontracts.ItemDTO, error) {
+	if err := s.ensureModule(); err != nil {
+		return nil, err
+	}
+	items, err := s.module.Retrieve(ctx, memorymodel.RetrieveRequest{
+		Query:          req.Query,
+		UserID:         req.UserID,
+		ConversationID: req.ConversationID,
+		AssistantID:    req.AssistantID,
+		RunID:          req.RunID,
+		MemoryTypes:    append([]string(nil), req.MemoryTypes...),
+		Limit:          req.Limit,
+		Now:            req.Now,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return toItemDTOs(items), nil
+}
+
+// ListItems 查询当前用户的记忆管理列表。
+//
+// 职责边界：
+// 1. 只把跨进程契约转成现有 memory.Module 请求，复用旧管理逻辑；
+// 2. 不在服务门面重做 limit/status/type 等业务规则，避免 CP2 改坏既有语义；
+// 3. 返回稳定 ItemView，保持 gateway 切流前后的 JSON 字段一致。
+func (s *Service) ListItems(ctx context.Context, req memorycontracts.ListItemsRequest) ([]memorycontracts.ItemView, error) {
+	if err := s.ensureModule(); err != nil {
+		return nil, err
+	}
+	items, err := s.module.ListItems(ctx, memorymodel.ListItemsRequest{
+		UserID:         req.UserID,
+		ConversationID: req.ConversationID,
+		Statuses:       append([]string(nil), req.Statuses...),
+		MemoryTypes:    append([]string(nil), req.MemoryTypes...),
+		Limit:          req.Limit,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return toItemViews(items), nil
+}
+
+// GetItem 返回当前用户自己的单条记忆详情。
+func (s *Service) GetItem(ctx context.Context, req memorycontracts.GetItemRequest) (*memorycontracts.ItemView, error) {
+	if err := s.ensureModule(); err != nil {
+		return nil, err
+	}
+	item, err := s.module.GetItem(ctx, coremodel.MemoryGetItemRequest{
+		UserID:   req.UserID,
+		MemoryID: req.MemoryID,
+	})
+	return toItemViewPtr(item), err
+}
+
+// CreateItem 手动新增一条用户记忆，并沿用既有审计与向量同步逻辑。
+func (s *Service) CreateItem(ctx context.Context, req memorycontracts.CreateItemRequest) (*memorycontracts.ItemView, error) {
+	if err := s.ensureModule(); err != nil {
+		return nil, err
+	}
+	item, err := s.module.CreateItem(ctx, coremodel.MemoryCreateItemRequest{
+		UserID:           req.UserID,
+		ConversationID:   req.ConversationID,
+		AssistantID:      req.AssistantID,
+		RunID:            req.RunID,
+		MemoryType:       req.MemoryType,
+		Title:            req.Title,
+		Content:          req.Content,
+		Confidence:       req.Confidence,
+		Importance:       req.Importance,
+		SensitivityLevel: req.SensitivityLevel,
+		IsExplicit:       req.IsExplicit,
+		TTLAt:            req.TTLAt,
+		Reason:           req.Reason,
+		OperatorType:     req.OperatorType,
+	})
+	return toItemViewPtr(item), err
+}
+
+// UpdateItem 手动修改一条用户记忆，并沿用既有审计与向量同步逻辑。
+func (s *Service) UpdateItem(ctx context.Context, req memorycontracts.UpdateItemRequest) (*memorycontracts.ItemView, error) {
+	if err := s.ensureModule(); err != nil {
+		return nil, err
+	}
+	item, err := s.module.UpdateItem(ctx, coremodel.MemoryUpdateItemRequest{
+		UserID:           req.UserID,
+		MemoryID:         req.MemoryID,
+		MemoryType:       req.MemoryType,
+		Title:            req.Title,
+		Content:          req.Content,
+		Confidence:       req.Confidence,
+		Importance:       req.Importance,
+		SensitivityLevel: req.SensitivityLevel,
+		IsExplicit:       req.IsExplicit,
+		TTLAt:            req.TTLAt,
+		ClearTTL:         req.ClearTTL,
+		Reason:           req.Reason,
+		OperatorType:     req.OperatorType,
+	})
+	return toItemViewPtr(item), err
+}
+
+// DeleteItem 软删除一条记忆，返回删除后的条目视图。
+func (s *Service) DeleteItem(ctx context.Context, req memorycontracts.DeleteItemRequest) (*memorycontracts.ItemView, error) {
+	if err := s.ensureModule(); err != nil {
+		return nil, err
+	}
+	item, err := s.module.DeleteItem(ctx, coremodel.MemoryDeleteItemRequest{
+		UserID:       req.UserID,
+		MemoryID:     req.MemoryID,
+		Reason:       req.Reason,
+		OperatorType: req.OperatorType,
+	})
+	return toItemViewPtr(item), err
+}
+
+// RestoreItem 恢复一条 deleted/archived 记忆，返回恢复后的条目视图。
+func (s *Service) RestoreItem(ctx context.Context, req memorycontracts.RestoreItemRequest) (*memorycontracts.ItemView, error) {
+	if err := s.ensureModule(); err != nil {
+		return nil, err
+	}
+	item, err := s.module.RestoreItem(ctx, coremodel.MemoryRestoreItemRequest{
+		UserID:       req.UserID,
+		MemoryID:     req.MemoryID,
+		Reason:       req.Reason,
+		OperatorType: req.OperatorType,
+	})
+	return toItemViewPtr(item), err
+}
+
+// StartWorkers 启动 memory 服务拥有的后台生命周期。
+//
+// 步骤化说明：
+// 1. 先启动 memory outbox relay / consumer，让 memory.extract.requested 可以被转成 memory_jobs；
+// 2. 再启动 memory worker 轮询 memory_jobs，执行抽取、审计与向量同步；
+// 3. Kafka 关闭时 eventBus 为空，只启动本地 worker，保留无 Kafka 环境下的降级能力。
+func (s *Service) StartWorkers(ctx context.Context) {
+	if s == nil {
+		return
+	}
+	if s.eventBus != nil {
+		s.eventBus.Start(ctx)
+		log.Println("Memory outbox consumer started")
+	} else {
+		log.Println("Memory outbox consumer is disabled")
+	}
+	if s.module != nil {
+		s.module.StartWorker(ctx)
+	}
+}
+
+// Close 关闭 memory 服务持有的外部资源。
+func (s *Service) Close() {
+	if s == nil || s.eventBus == nil {
+		return
+	}
+	s.eventBus.Close()
+}
+
+func (s *Service) ensureModule() error {
+	if s == nil || s.module == nil {
+		return errors.New("memory service dependency not initialized")
+	}
+	return nil
+}
+
+func toItemViews(items []memorymodel.ItemDTO) []memorycontracts.ItemView {
+	if len(items) == 0 {
+		return nil
+	}
+	result := make([]memorycontracts.ItemView, 0, len(items))
+	for _, item := range items {
+		result = append(result, toItemView(item))
+	}
+	return result
+}
+
+func toItemDTOs(items []memorymodel.ItemDTO) []memorycontracts.ItemDTO {
+	return toItemViews(items)
+}
+
+func toItemViewPtr(item *memorymodel.ItemDTO) *memorycontracts.ItemView {
+	if item == nil {
+		return nil
+	}
+	view := toItemView(*item)
+	return &view
+}
+
+func toItemView(item memorymodel.ItemDTO) memorycontracts.ItemView {
+	return memorycontracts.ItemView{
+		ID:               item.ID,
+		UserID:           item.UserID,
+		ConversationID:   item.ConversationID,
+		AssistantID:      item.AssistantID,
+		RunID:            item.RunID,
+		MemoryType:       item.MemoryType,
+		Title:            item.Title,
+		Content:          item.Content,
+		ContentHash:      item.ContentHash,
+		Confidence:       item.Confidence,
+		Importance:       item.Importance,
+		SensitivityLevel: item.SensitivityLevel,
+		IsExplicit:       item.IsExplicit,
+		Status:           item.Status,
+		TTLAt:            item.TTLAt,
+		CreatedAt:        item.CreatedAt,
+		UpdatedAt:        item.UpdatedAt,
+	}
+}