feat(memory): implement caching layer for memory operations (#98)

Add comprehensive caching layer for the Agent Memory System:

- HotMemoryCache: LRU cache for frequently accessed memories
  - Python 3.12 type parameter syntax
  - Thread-safe operations with RLock
  - TTL-based expiration
  - Access count tracking for hot memory identification
  - Scoped invalidation by type, scope, or pattern

- EmbeddingCache: Cache embeddings by content hash
  - Content-hash based deduplication
  - Optional Redis backing for persistence
  - LRU eviction with configurable max size
  - CachedEmbeddingGenerator wrapper for transparent caching

- CacheManager: Unified cache management
  - Coordinates hot cache, embedding cache, and retrieval cache
  - Centralized invalidation across all caches
  - Aggregated statistics and hit rate tracking
  - Automatic cleanup scheduling
  - Cache warmup support

Performance targets:
- Cache hit rate > 80% for hot memories
- Cache operations < 1ms (memory), < 5ms (Redis)

83 new tests with comprehensive coverage.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

backend/app/alembic/versions/0005_add_memory_system_tables.py

@@ -0,0 +1,494 @@
+"""Add Agent Memory System tables
+
+Revision ID: 0005
+Revises: 0004
+Create Date: 2025-01-05
+
+This migration creates the Agent Memory System tables:
+- working_memory: Key-value storage with TTL for active sessions
+- episodes: Experiential memories from task executions
+- facts: Semantic knowledge triples with confidence scores
+- procedures: Learned skills and procedures
+- memory_consolidation_log: Tracks consolidation jobs
+
+See Issue #88: Database Schema & Storage Layer
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "0005"
+down_revision: str | None = "0004"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Create Agent Memory System tables."""
+
+    # =========================================================================
+    # Create ENUM types for memory system
+    # =========================================================================
+
+    # Scope type enum
+    scope_type_enum = postgresql.ENUM(
+        "global",
+        "project",
+        "agent_type",
+        "agent_instance",
+        "session",
+        name="scope_type",
+        create_type=False,
+    )
+    scope_type_enum.create(op.get_bind(), checkfirst=True)
+
+    # Episode outcome enum
+    episode_outcome_enum = postgresql.ENUM(
+        "success",
+        "failure",
+        "partial",
+        name="episode_outcome",
+        create_type=False,
+    )
+    episode_outcome_enum.create(op.get_bind(), checkfirst=True)
+
+    # Consolidation type enum
+    consolidation_type_enum = postgresql.ENUM(
+        "working_to_episodic",
+        "episodic_to_semantic",
+        "episodic_to_procedural",
+        "pruning",
+        name="consolidation_type",
+        create_type=False,
+    )
+    consolidation_type_enum.create(op.get_bind(), checkfirst=True)
+
+    # Consolidation status enum
+    consolidation_status_enum = postgresql.ENUM(
+        "pending",
+        "running",
+        "completed",
+        "failed",
+        name="consolidation_status",
+        create_type=False,
+    )
+    consolidation_status_enum.create(op.get_bind(), checkfirst=True)
+
+    # =========================================================================
+    # Create working_memory table
+    # Key-value storage with TTL for active sessions
+    # =========================================================================
+    op.create_table(
+        "working_memory",
+        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column(
+            "scope_type",
+            scope_type_enum,
+            nullable=False,
+        ),
+        sa.Column("scope_id", sa.String(255), nullable=False),
+        sa.Column("key", sa.String(255), nullable=False),
+        sa.Column("value", postgresql.JSONB(astext_type=sa.Text()), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+    # Working memory indexes
+    op.create_index(
+        "ix_working_memory_scope_type",
+        "working_memory",
+        ["scope_type"],
+    )
+    op.create_index(
+        "ix_working_memory_scope_id",
+        "working_memory",
+        ["scope_id"],
+    )
+    op.create_index(
+        "ix_working_memory_scope_key",
+        "working_memory",
+        ["scope_type", "scope_id", "key"],
+        unique=True,
+    )
+    op.create_index(
+        "ix_working_memory_expires",
+        "working_memory",
+        ["expires_at"],
+    )
+    op.create_index(
+        "ix_working_memory_scope_list",
+        "working_memory",
+        ["scope_type", "scope_id"],
+    )
+
+    # =========================================================================
+    # Create episodes table
+    # Experiential memories from task executions
+    # =========================================================================
+    op.create_table(
+        "episodes",
+        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("agent_instance_id", postgresql.UUID(as_uuid=True), nullable=True),
+        sa.Column("agent_type_id", postgresql.UUID(as_uuid=True), nullable=True),
+        sa.Column("session_id", sa.String(255), nullable=False),
+        sa.Column("task_type", sa.String(100), nullable=False),
+        sa.Column("task_description", sa.Text(), nullable=False),
+        sa.Column(
+            "actions",
+            postgresql.JSONB(astext_type=sa.Text()),
+            nullable=False,
+            server_default="[]",
+        ),
+        sa.Column("context_summary", sa.Text(), nullable=False),
+        sa.Column(
+            "outcome",
+            episode_outcome_enum,
+            nullable=False,
+        ),
+        sa.Column("outcome_details", sa.Text(), nullable=True),
+        sa.Column("duration_seconds", sa.Float(), nullable=False, server_default="0.0"),
+        sa.Column("tokens_used", sa.BigInteger(), nullable=False, server_default="0"),
+        sa.Column(
+            "lessons_learned",
+            postgresql.JSONB(astext_type=sa.Text()),
+            nullable=False,
+            server_default="[]",
+        ),
+        sa.Column("importance_score", sa.Float(), nullable=False, server_default="0.5"),
+        # Vector embedding - using TEXT as fallback, will be VECTOR(1536) when pgvector is available
+        sa.Column("embedding", sa.Text(), nullable=True),
+        sa.Column("occurred_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.ForeignKeyConstraint(
+            ["project_id"],
+            ["projects.id"],
+            name="fk_episodes_project",
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["agent_instance_id"],
+            ["agent_instances.id"],
+            name="fk_episodes_agent_instance",
+            ondelete="SET NULL",
+        ),
+        sa.ForeignKeyConstraint(
+            ["agent_type_id"],
+            ["agent_types.id"],
+            name="fk_episodes_agent_type",
+            ondelete="SET NULL",
+        ),
+    )
+
+    # Episode indexes
+    op.create_index("ix_episodes_project_id", "episodes", ["project_id"])
+    op.create_index("ix_episodes_agent_instance_id", "episodes", ["agent_instance_id"])
+    op.create_index("ix_episodes_agent_type_id", "episodes", ["agent_type_id"])
+    op.create_index("ix_episodes_session_id", "episodes", ["session_id"])
+    op.create_index("ix_episodes_task_type", "episodes", ["task_type"])
+    op.create_index("ix_episodes_outcome", "episodes", ["outcome"])
+    op.create_index("ix_episodes_importance_score", "episodes", ["importance_score"])
+    op.create_index("ix_episodes_occurred_at", "episodes", ["occurred_at"])
+    op.create_index("ix_episodes_project_task", "episodes", ["project_id", "task_type"])
+    op.create_index(
+        "ix_episodes_project_outcome", "episodes", ["project_id", "outcome"]
+    )
+    op.create_index(
+        "ix_episodes_agent_task", "episodes", ["agent_instance_id", "task_type"]
+    )
+    op.create_index(
+        "ix_episodes_project_time", "episodes", ["project_id", "occurred_at"]
+    )
+    op.create_index(
+        "ix_episodes_importance_time",
+        "episodes",
+        ["importance_score", "occurred_at"],
+    )
+
+    # =========================================================================
+    # Create facts table
+    # Semantic knowledge triples with confidence scores
+    # =========================================================================
+    op.create_table(
+        "facts",
+        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column(
+            "project_id", postgresql.UUID(as_uuid=True), nullable=True
+        ),  # NULL for global facts
+        sa.Column("subject", sa.String(500), nullable=False),
+        sa.Column("predicate", sa.String(255), nullable=False),
+        sa.Column("object", sa.Text(), nullable=False),
+        sa.Column("confidence", sa.Float(), nullable=False, server_default="0.8"),
+        sa.Column(
+            "source_episode_ids",
+            postgresql.ARRAY(postgresql.UUID(as_uuid=True)),
+            nullable=False,
+            server_default="{}",
+        ),
+        sa.Column("first_learned", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("last_reinforced", sa.DateTime(timezone=True), nullable=False),
+        sa.Column(
+            "reinforcement_count", sa.Integer(), nullable=False, server_default="1"
+        ),
+        # Vector embedding
+        sa.Column("embedding", sa.Text(), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.ForeignKeyConstraint(
+            ["project_id"],
+            ["projects.id"],
+            name="fk_facts_project",
+            ondelete="CASCADE",
+        ),
+    )
+
+    # Fact indexes
+    op.create_index("ix_facts_project_id", "facts", ["project_id"])
+    op.create_index("ix_facts_subject", "facts", ["subject"])
+    op.create_index("ix_facts_predicate", "facts", ["predicate"])
+    op.create_index("ix_facts_confidence", "facts", ["confidence"])
+    op.create_index("ix_facts_subject_predicate", "facts", ["subject", "predicate"])
+    op.create_index("ix_facts_project_subject", "facts", ["project_id", "subject"])
+    op.create_index(
+        "ix_facts_confidence_time", "facts", ["confidence", "last_reinforced"]
+    )
+    # Unique constraint for triples within project scope
+    op.create_index(
+        "ix_facts_unique_triple",
+        "facts",
+        ["project_id", "subject", "predicate", "object"],
+        unique=True,
+        postgresql_where=sa.text("project_id IS NOT NULL"),
+    )
+
+    # =========================================================================
+    # Create procedures table
+    # Learned skills and procedures
+    # =========================================================================
+    op.create_table(
+        "procedures",
+        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=True),
+        sa.Column("agent_type_id", postgresql.UUID(as_uuid=True), nullable=True),
+        sa.Column("name", sa.String(255), nullable=False),
+        sa.Column("trigger_pattern", sa.Text(), nullable=False),
+        sa.Column(
+            "steps",
+            postgresql.JSONB(astext_type=sa.Text()),
+            nullable=False,
+            server_default="[]",
+        ),
+        sa.Column("success_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("failure_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("last_used", sa.DateTime(timezone=True), nullable=True),
+        # Vector embedding
+        sa.Column("embedding", sa.Text(), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.ForeignKeyConstraint(
+            ["project_id"],
+            ["projects.id"],
+            name="fk_procedures_project",
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["agent_type_id"],
+            ["agent_types.id"],
+            name="fk_procedures_agent_type",
+            ondelete="SET NULL",
+        ),
+    )
+
+    # Procedure indexes
+    op.create_index("ix_procedures_project_id", "procedures", ["project_id"])
+    op.create_index("ix_procedures_agent_type_id", "procedures", ["agent_type_id"])
+    op.create_index("ix_procedures_name", "procedures", ["name"])
+    op.create_index("ix_procedures_last_used", "procedures", ["last_used"])
+    op.create_index(
+        "ix_procedures_unique_name",
+        "procedures",
+        ["project_id", "agent_type_id", "name"],
+        unique=True,
+    )
+    op.create_index("ix_procedures_project_name", "procedures", ["project_id", "name"])
+    # Note: agent_type_id already indexed via ix_procedures_agent_type_id (line 354)
+    op.create_index(
+        "ix_procedures_success_rate",
+        "procedures",
+        ["success_count", "failure_count"],
+    )
+
+    # =========================================================================
+    # Add check constraints for data integrity
+    # =========================================================================
+
+    # Episode constraints
+    op.create_check_constraint(
+        "ck_episodes_importance_range",
+        "episodes",
+        "importance_score >= 0.0 AND importance_score <= 1.0",
+    )
+    op.create_check_constraint(
+        "ck_episodes_duration_positive",
+        "episodes",
+        "duration_seconds >= 0.0",
+    )
+    op.create_check_constraint(
+        "ck_episodes_tokens_positive",
+        "episodes",
+        "tokens_used >= 0",
+    )
+
+    # Fact constraints
+    op.create_check_constraint(
+        "ck_facts_confidence_range",
+        "facts",
+        "confidence >= 0.0 AND confidence <= 1.0",
+    )
+
+    # Procedure constraints
+    op.create_check_constraint(
+        "ck_procedures_success_positive",
+        "procedures",
+        "success_count >= 0",
+    )
+    op.create_check_constraint(
+        "ck_procedures_failure_positive",
+        "procedures",
+        "failure_count >= 0",
+    )
+
+    # =========================================================================
+    # Create memory_consolidation_log table
+    # Tracks consolidation jobs
+    # =========================================================================
+    op.create_table(
+        "memory_consolidation_log",
+        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column(
+            "consolidation_type",
+            consolidation_type_enum,
+            nullable=False,
+        ),
+        sa.Column("source_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("result_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("started_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("completed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "status",
+            consolidation_status_enum,
+            nullable=False,
+            server_default="pending",
+        ),
+        sa.Column("error", sa.Text(), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+    # Consolidation log indexes
+    op.create_index(
+        "ix_consolidation_type",
+        "memory_consolidation_log",
+        ["consolidation_type"],
+    )
+    op.create_index(
+        "ix_consolidation_status",
+        "memory_consolidation_log",
+        ["status"],
+    )
+    op.create_index(
+        "ix_consolidation_type_status",
+        "memory_consolidation_log",
+        ["consolidation_type", "status"],
+    )
+    op.create_index(
+        "ix_consolidation_started",
+        "memory_consolidation_log",
+        ["started_at"],
+    )
+
+
+def downgrade() -> None:
+    """Drop Agent Memory System tables."""
+
+    # Drop check constraints first
+    op.drop_constraint("ck_procedures_failure_positive", "procedures", type_="check")
+    op.drop_constraint("ck_procedures_success_positive", "procedures", type_="check")
+    op.drop_constraint("ck_facts_confidence_range", "facts", type_="check")
+    op.drop_constraint("ck_episodes_tokens_positive", "episodes", type_="check")
+    op.drop_constraint("ck_episodes_duration_positive", "episodes", type_="check")
+    op.drop_constraint("ck_episodes_importance_range", "episodes", type_="check")
+
+    # Drop tables in reverse order (dependencies first)
+    op.drop_table("memory_consolidation_log")
+    op.drop_table("procedures")
+    op.drop_table("facts")
+    op.drop_table("episodes")
+    op.drop_table("working_memory")
+
+    # Drop ENUM types
+    op.execute("DROP TYPE IF EXISTS consolidation_status")
+    op.execute("DROP TYPE IF EXISTS consolidation_type")
+    op.execute("DROP TYPE IF EXISTS episode_outcome")
+    op.execute("DROP TYPE IF EXISTS scope_type")

backend/app/models/__init__.py

@@ -8,6 +8,19 @@ from app.core.database import Base
 
 from .base import TimestampMixin, UUIDMixin
 
+# Memory system models
+from .memory import (
+    ConsolidationStatus,
+    ConsolidationType,
+    Episode,
+    EpisodeOutcome,
+    Fact,
+    MemoryConsolidationLog,
+    Procedure,
+    ScopeType,
+    WorkingMemory,
+)
+
 # OAuth models (client mode - authenticate via Google/GitHub)
 from .oauth_account import OAuthAccount
 
@@ -37,7 +50,14 @@ __all__ = [
     "AgentInstance",
     "AgentType",
     "Base",
+    # Memory models
+    "ConsolidationStatus",
+    "ConsolidationType",
+    "Episode",
+    "EpisodeOutcome",
+    "Fact",
     "Issue",
+    "MemoryConsolidationLog",
     "OAuthAccount",
     "OAuthAuthorizationCode",
     "OAuthClient",
@@ -46,11 +66,14 @@ __all__ = [
     "OAuthState",
     "Organization",
     "OrganizationRole",
+    "Procedure",
     "Project",
+    "ScopeType",
     "Sprint",
     "TimestampMixin",
     "UUIDMixin",
     "User",
     "UserOrganization",
     "UserSession",
+    "WorkingMemory",
 ]

backend/app/models/memory/__init__.py

@@ -0,0 +1,32 @@
+# app/models/memory/__init__.py
+"""
+Memory System Database Models.
+
+Provides SQLAlchemy models for the Agent Memory System:
+- WorkingMemory: Key-value storage with TTL
+- Episode: Experiential memories
+- Fact: Semantic knowledge triples
+- Procedure: Learned skills
+- MemoryConsolidationLog: Consolidation job tracking
+"""
+
+from .consolidation import MemoryConsolidationLog
+from .enums import ConsolidationStatus, ConsolidationType, EpisodeOutcome, ScopeType
+from .episode import Episode
+from .fact import Fact
+from .procedure import Procedure
+from .working_memory import WorkingMemory
+
+__all__ = [
+    # Enums
+    "ConsolidationStatus",
+    "ConsolidationType",
+    # Models
+    "Episode",
+    "EpisodeOutcome",
+    "Fact",
+    "MemoryConsolidationLog",
+    "Procedure",
+    "ScopeType",
+    "WorkingMemory",
+]

backend/app/models/memory/consolidation.py

@@ -0,0 +1,72 @@
+# app/models/memory/consolidation.py
+"""
+Memory Consolidation Log database model.
+
+Tracks memory consolidation jobs that transfer knowledge
+between memory tiers.
+"""
+
+from sqlalchemy import Column, DateTime, Enum, Index, Integer, Text
+
+from app.models.base import Base, TimestampMixin, UUIDMixin
+
+from .enums import ConsolidationStatus, ConsolidationType
+
+
+class MemoryConsolidationLog(Base, UUIDMixin, TimestampMixin):
+    """
+    Memory consolidation job log.
+
+    Tracks consolidation operations:
+    - Working -> Episodic (session end)
+    - Episodic -> Semantic (fact extraction)
+    - Episodic -> Procedural (procedure learning)
+    - Pruning (removing low-value memories)
+    """
+
+    __tablename__ = "memory_consolidation_log"
+
+    # Consolidation type
+    consolidation_type: Column[ConsolidationType] = Column(
+        Enum(ConsolidationType),
+        nullable=False,
+        index=True,
+    )
+
+    # Counts
+    source_count = Column(Integer, nullable=False, default=0)
+    result_count = Column(Integer, nullable=False, default=0)
+
+    # Timing
+    started_at = Column(DateTime(timezone=True), nullable=False)
+    completed_at = Column(DateTime(timezone=True), nullable=True)
+
+    # Status
+    status: Column[ConsolidationStatus] = Column(
+        Enum(ConsolidationStatus),
+        nullable=False,
+        default=ConsolidationStatus.PENDING,
+        index=True,
+    )
+
+    # Error details if failed
+    error = Column(Text, nullable=True)
+
+    __table_args__ = (
+        # Query patterns
+        Index("ix_consolidation_type_status", "consolidation_type", "status"),
+        Index("ix_consolidation_started", "started_at"),
+    )
+
+    @property
+    def duration_seconds(self) -> float | None:
+        """Calculate duration of the consolidation job."""
+        if self.completed_at is None or self.started_at is None:
+            return None
+        return (self.completed_at - self.started_at).total_seconds()
+
+    def __repr__(self) -> str:
+        return (
+            f"<MemoryConsolidationLog {self.id} "
+            f"type={self.consolidation_type.value} status={self.status.value}>"
+        )

backend/app/models/memory/enums.py

@@ -0,0 +1,73 @@
+# app/models/memory/enums.py
+"""
+Enums for Memory System database models.
+
+These enums define the database-level constraints for memory types
+and scoping levels.
+"""
+
+from enum import Enum as PyEnum
+
+
+class ScopeType(str, PyEnum):
+    """
+    Memory scope levels matching the memory service types.
+
+    GLOBAL: System-wide memories accessible by all
+    PROJECT: Project-scoped memories
+    AGENT_TYPE: Type-specific memories (shared by instances of same type)
+    AGENT_INSTANCE: Instance-specific memories
+    SESSION: Session-scoped ephemeral memories
+    """
+
+    GLOBAL = "global"
+    PROJECT = "project"
+    AGENT_TYPE = "agent_type"
+    AGENT_INSTANCE = "agent_instance"
+    SESSION = "session"
+
+
+class EpisodeOutcome(str, PyEnum):
+    """
+    Outcome of an episode (task execution).
+
+    SUCCESS: Task completed successfully
+    FAILURE: Task failed
+    PARTIAL: Task partially completed
+    """
+
+    SUCCESS = "success"
+    FAILURE = "failure"
+    PARTIAL = "partial"
+
+
+class ConsolidationType(str, PyEnum):
+    """
+    Types of memory consolidation operations.
+
+    WORKING_TO_EPISODIC: Transfer session state to episodic
+    EPISODIC_TO_SEMANTIC: Extract facts from episodes
+    EPISODIC_TO_PROCEDURAL: Extract procedures from episodes
+    PRUNING: Remove low-value memories
+    """
+
+    WORKING_TO_EPISODIC = "working_to_episodic"
+    EPISODIC_TO_SEMANTIC = "episodic_to_semantic"
+    EPISODIC_TO_PROCEDURAL = "episodic_to_procedural"
+    PRUNING = "pruning"
+
+
+class ConsolidationStatus(str, PyEnum):
+    """
+    Status of a consolidation job.
+
+    PENDING: Job is queued
+    RUNNING: Job is currently executing
+    COMPLETED: Job finished successfully
+    FAILED: Job failed with errors
+    """
+
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"

backend/app/models/memory/episode.py

@@ -0,0 +1,139 @@
+# app/models/memory/episode.py
+"""
+Episode database model.
+
+Stores experiential memories - records of past task executions
+with context, actions, outcomes, and lessons learned.
+"""
+
+from sqlalchemy import (
+    BigInteger,
+    CheckConstraint,
+    Column,
+    DateTime,
+    Enum,
+    Float,
+    ForeignKey,
+    Index,
+    String,
+    Text,
+)
+from sqlalchemy.dialects.postgresql import (
+    JSONB,
+    UUID as PGUUID,
+)
+from sqlalchemy.orm import relationship
+
+from app.models.base import Base, TimestampMixin, UUIDMixin
+
+from .enums import EpisodeOutcome
+
+# Import pgvector type - will be available after migration enables extension
+try:
+    from pgvector.sqlalchemy import Vector  # type: ignore[import-not-found]
+except ImportError:
+    # Fallback for environments without pgvector
+    Vector = None
+
+
+class Episode(Base, UUIDMixin, TimestampMixin):
+    """
+    Episodic memory model.
+
+    Records experiential memories from agent task execution:
+    - What task was performed
+    - What actions were taken
+    - What was the outcome
+    - What lessons were learned
+    """
+
+    __tablename__ = "episodes"
+
+    # Foreign keys
+    project_id = Column(
+        PGUUID(as_uuid=True),
+        ForeignKey("projects.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+
+    agent_instance_id = Column(
+        PGUUID(as_uuid=True),
+        ForeignKey("agent_instances.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
+
+    agent_type_id = Column(
+        PGUUID(as_uuid=True),
+        ForeignKey("agent_types.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
+
+    # Session reference
+    session_id = Column(String(255), nullable=False, index=True)
+
+    # Task information
+    task_type = Column(String(100), nullable=False, index=True)
+    task_description = Column(Text, nullable=False)
+
+    # Actions taken (list of action dictionaries)
+    actions = Column(JSONB, default=list, nullable=False)
+
+    # Context summary
+    context_summary = Column(Text, nullable=False)
+
+    # Outcome
+    outcome: Column[EpisodeOutcome] = Column(
+        Enum(EpisodeOutcome),
+        nullable=False,
+        index=True,
+    )
+    outcome_details = Column(Text, nullable=True)
+
+    # Metrics
+    duration_seconds = Column(Float, nullable=False, default=0.0)
+    tokens_used = Column(BigInteger, nullable=False, default=0)
+
+    # Learning
+    lessons_learned = Column(JSONB, default=list, nullable=False)
+    importance_score = Column(Float, nullable=False, default=0.5, index=True)
+
+    # Vector embedding for semantic search
+    # Using 1536 dimensions for OpenAI text-embedding-3-small
+    embedding = Column(Vector(1536) if Vector else Text, nullable=True)
+
+    # When the episode occurred
+    occurred_at = Column(DateTime(timezone=True), nullable=False, index=True)
+
+    # Relationships
+    project = relationship("Project", foreign_keys=[project_id])
+    agent_instance = relationship("AgentInstance", foreign_keys=[agent_instance_id])
+    agent_type = relationship("AgentType", foreign_keys=[agent_type_id])
+
+    __table_args__ = (
+        # Primary query patterns
+        Index("ix_episodes_project_task", "project_id", "task_type"),
+        Index("ix_episodes_project_outcome", "project_id", "outcome"),
+        Index("ix_episodes_agent_task", "agent_instance_id", "task_type"),
+        Index("ix_episodes_project_time", "project_id", "occurred_at"),
+        # For importance-based pruning
+        Index("ix_episodes_importance_time", "importance_score", "occurred_at"),
+        # Data integrity constraints
+        CheckConstraint(
+            "importance_score >= 0.0 AND importance_score <= 1.0",
+            name="ck_episodes_importance_range",
+        ),
+        CheckConstraint(
+            "duration_seconds >= 0.0",
+            name="ck_episodes_duration_positive",
+        ),
+        CheckConstraint(
+            "tokens_used >= 0",
+            name="ck_episodes_tokens_positive",
+        ),
+    )
+
+    def __repr__(self) -> str:
+        return f"<Episode {self.id} task={self.task_type} outcome={self.outcome.value}>"

backend/app/models/memory/fact.py

@@ -0,0 +1,110 @@
+# app/models/memory/fact.py
+"""
+Fact database model.
+
+Stores semantic memories - learned facts in subject-predicate-object
+triple format with confidence scores and source tracking.
+"""
+
+from sqlalchemy import (
+    CheckConstraint,
+    Column,
+    DateTime,
+    Float,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    text,
+)
+from sqlalchemy.dialects.postgresql import (
+    ARRAY,
+    UUID as PGUUID,
+)
+from sqlalchemy.orm import relationship
+
+from app.models.base import Base, TimestampMixin, UUIDMixin
+
+# Import pgvector type
+try:
+    from pgvector.sqlalchemy import Vector  # type: ignore[import-not-found]
+except ImportError:
+    Vector = None
+
+
+class Fact(Base, UUIDMixin, TimestampMixin):
+    """
+    Semantic memory model.
+
+    Stores learned facts as subject-predicate-object triples:
+    - "FastAPI" - "uses" - "Starlette framework"
+    - "Project Alpha" - "requires" - "OAuth authentication"
+
+    Facts have confidence scores that decay over time and can be
+    reinforced when the same fact is learned again.
+    """
+
+    __tablename__ = "facts"
+
+    # Scoping: project_id is NULL for global facts
+    project_id = Column(
+        PGUUID(as_uuid=True),
+        ForeignKey("projects.id", ondelete="CASCADE"),
+        nullable=True,
+        index=True,
+    )
+
+    # Triple format
+    subject = Column(String(500), nullable=False, index=True)
+    predicate = Column(String(255), nullable=False, index=True)
+    object = Column(Text, nullable=False)
+
+    # Confidence score (0.0 to 1.0)
+    confidence = Column(Float, nullable=False, default=0.8, index=True)
+
+    # Source tracking: which episodes contributed to this fact
+    source_episode_ids: Column[list] = Column(
+        ARRAY(PGUUID(as_uuid=True)), default=list, nullable=False
+    )
+
+    # Learning history
+    first_learned = Column(DateTime(timezone=True), nullable=False)
+    last_reinforced = Column(DateTime(timezone=True), nullable=False)
+    reinforcement_count = Column(Integer, nullable=False, default=1)
+
+    # Vector embedding for semantic search
+    embedding = Column(Vector(1536) if Vector else Text, nullable=True)
+
+    # Relationships
+    project = relationship("Project", foreign_keys=[project_id])
+
+    __table_args__ = (
+        # Unique constraint on triple within project scope
+        Index(
+            "ix_facts_unique_triple",
+            "project_id",
+            "subject",
+            "predicate",
+            "object",
+            unique=True,
+            postgresql_where=text("project_id IS NOT NULL"),
+        ),
+        # Query patterns
+        Index("ix_facts_subject_predicate", "subject", "predicate"),
+        Index("ix_facts_project_subject", "project_id", "subject"),
+        Index("ix_facts_confidence_time", "confidence", "last_reinforced"),
+        # For finding facts by entity (subject or object)
+        Index("ix_facts_subject", "subject"),
+        # Data integrity constraints
+        CheckConstraint(
+            "confidence >= 0.0 AND confidence <= 1.0",
+            name="ck_facts_confidence_range",
+        ),
+    )
+
+    def __repr__(self) -> str:
+        return (
+            f"<Fact {self.id} '{self.subject}' - '{self.predicate}' - "
+            f"'{self.object[:50]}...' conf={self.confidence:.2f}>"
+        )

backend/app/models/memory/procedure.py

@@ -0,0 +1,129 @@
+# app/models/memory/procedure.py
+"""
+Procedure database model.
+
+Stores procedural memories - learned skills and procedures
+derived from successful task execution patterns.
+"""
+
+from sqlalchemy import (
+    CheckConstraint,
+    Column,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+)
+from sqlalchemy.dialects.postgresql import (
+    JSONB,
+    UUID as PGUUID,
+)
+from sqlalchemy.orm import relationship
+
+from app.models.base import Base, TimestampMixin, UUIDMixin
+
+# Import pgvector type
+try:
+    from pgvector.sqlalchemy import Vector  # type: ignore[import-not-found]
+except ImportError:
+    Vector = None
+
+
+class Procedure(Base, UUIDMixin, TimestampMixin):
+    """
+    Procedural memory model.
+
+    Stores learned procedures (skills) extracted from successful
+    task execution patterns:
+    - Name and trigger pattern for matching
+    - Step-by-step actions
+    - Success/failure tracking
+    """
+
+    __tablename__ = "procedures"
+
+    # Scoping
+    project_id = Column(
+        PGUUID(as_uuid=True),
+        ForeignKey("projects.id", ondelete="CASCADE"),
+        nullable=True,
+        index=True,
+    )
+
+    agent_type_id = Column(
+        PGUUID(as_uuid=True),
+        ForeignKey("agent_types.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
+
+    # Procedure identification
+    name = Column(String(255), nullable=False, index=True)
+    trigger_pattern = Column(Text, nullable=False)
+
+    # Steps as JSON array of step objects
+    # Each step: {order, action, parameters, expected_outcome, fallback_action}
+    steps = Column(JSONB, default=list, nullable=False)
+
+    # Success tracking
+    success_count = Column(Integer, nullable=False, default=0)
+    failure_count = Column(Integer, nullable=False, default=0)
+
+    # Usage tracking
+    last_used = Column(DateTime(timezone=True), nullable=True, index=True)
+
+    # Vector embedding for semantic matching
+    embedding = Column(Vector(1536) if Vector else Text, nullable=True)
+
+    # Relationships
+    project = relationship("Project", foreign_keys=[project_id])
+    agent_type = relationship("AgentType", foreign_keys=[agent_type_id])
+
+    __table_args__ = (
+        # Unique procedure name within scope
+        Index(
+            "ix_procedures_unique_name",
+            "project_id",
+            "agent_type_id",
+            "name",
+            unique=True,
+        ),
+        # Query patterns
+        Index("ix_procedures_project_name", "project_id", "name"),
+        # Note: agent_type_id already has index=True on Column definition
+        # For finding best procedures
+        Index("ix_procedures_success_rate", "success_count", "failure_count"),
+        # Data integrity constraints
+        CheckConstraint(
+            "success_count >= 0",
+            name="ck_procedures_success_positive",
+        ),
+        CheckConstraint(
+            "failure_count >= 0",
+            name="ck_procedures_failure_positive",
+        ),
+    )
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate the success rate of this procedure."""
+        # Snapshot values to avoid race conditions in concurrent access
+        success = self.success_count
+        failure = self.failure_count
+        total = success + failure
+        if total == 0:
+            return 0.0
+        return success / total
+
+    @property
+    def total_uses(self) -> int:
+        """Get total number of times this procedure was used."""
+        # Snapshot values for consistency
+        return self.success_count + self.failure_count
+
+    def __repr__(self) -> str:
+        return (
+            f"<Procedure {self.name} ({self.id}) success_rate={self.success_rate:.2%}>"
+        )

backend/app/models/memory/working_memory.py

@@ -0,0 +1,58 @@
+# app/models/memory/working_memory.py
+"""
+Working Memory database model.
+
+Stores ephemeral key-value data for active sessions with TTL support.
+Used as database backup when Redis is unavailable.
+"""
+
+from sqlalchemy import Column, DateTime, Enum, Index, String
+from sqlalchemy.dialects.postgresql import JSONB
+
+from app.models.base import Base, TimestampMixin, UUIDMixin
+
+from .enums import ScopeType
+
+
+class WorkingMemory(Base, UUIDMixin, TimestampMixin):
+    """
+    Working memory storage table.
+
+    Provides database-backed working memory as fallback when
+    Redis is unavailable. Supports TTL-based expiration.
+    """
+
+    __tablename__ = "working_memory"
+
+    # Scoping
+    scope_type: Column[ScopeType] = Column(
+        Enum(ScopeType),
+        nullable=False,
+        index=True,
+    )
+    scope_id = Column(String(255), nullable=False, index=True)
+
+    # Key-value storage
+    key = Column(String(255), nullable=False)
+    value = Column(JSONB, nullable=False)
+
+    # TTL support
+    expires_at = Column(DateTime(timezone=True), nullable=True, index=True)
+
+    __table_args__ = (
+        # Primary lookup: scope + key
+        Index(
+            "ix_working_memory_scope_key",
+            "scope_type",
+            "scope_id",
+            "key",
+            unique=True,
+        ),
+        # For cleanup of expired entries
+        Index("ix_working_memory_expires", "expires_at"),
+        # For listing all keys in a scope
+        Index("ix_working_memory_scope_list", "scope_type", "scope_id"),
+    )
+
+    def __repr__(self) -> str:
+        return f"<WorkingMemory {self.scope_type.value}:{self.scope_id}:{self.key}>"

backend/app/services/context/__init__.py

@@ -114,6 +114,8 @@ from .types import (
     ContextType,
     ConversationContext,
     KnowledgeContext,
+    MemoryContext,
+    MemorySubtype,
     MessageRole,
     SystemContext,
     TaskComplexity,
@@ -149,6 +151,8 @@ __all__ = [
     "FormattingError",
     "InvalidContextError",
     "KnowledgeContext",
+    "MemoryContext",
+    "MemorySubtype",
     "MessageRole",
     "ModelAdapter",
     "OpenAIAdapter",

backend/app/services/context/budget/allocator.py

@@ -30,6 +30,7 @@ class TokenBudget:
     knowledge: int = 0
     conversation: int = 0
     tools: int = 0
+    memory: int = 0  # Agent memory (working, episodic, semantic, procedural)
     response_reserve: int = 0
     buffer: int = 0
 
@@ -60,6 +61,7 @@ class TokenBudget:
             "knowledge": self.knowledge,
             "conversation": self.conversation,
             "tool": self.tools,
+            "memory": self.memory,
         }
         return allocation_map.get(context_type, 0)
 
@@ -211,6 +213,7 @@ class TokenBudget:
                 "knowledge": self.knowledge,
                 "conversation": self.conversation,
                 "tools": self.tools,
+                "memory": self.memory,
                 "response_reserve": self.response_reserve,
                 "buffer": self.buffer,
             },
@@ -264,9 +267,10 @@ class BudgetAllocator:
             total=total_tokens,
             system=int(total_tokens * alloc.get("system", 0.05)),
             task=int(total_tokens * alloc.get("task", 0.10)),
-            knowledge=int(total_tokens * alloc.get("knowledge", 0.40)),
-            conversation=int(total_tokens * alloc.get("conversation", 0.20)),
+            knowledge=int(total_tokens * alloc.get("knowledge", 0.30)),
+            conversation=int(total_tokens * alloc.get("conversation", 0.15)),
             tools=int(total_tokens * alloc.get("tools", 0.05)),
+            memory=int(total_tokens * alloc.get("memory", 0.15)),
             response_reserve=int(total_tokens * alloc.get("response", 0.15)),
             buffer=int(total_tokens * alloc.get("buffer", 0.05)),
         )
@@ -317,6 +321,8 @@ class BudgetAllocator:
             budget.conversation = max(0, budget.conversation + actual_adjustment)
         elif context_type == "tool":
             budget.tools = max(0, budget.tools + actual_adjustment)
+        elif context_type == "memory":
+            budget.memory = max(0, budget.memory + actual_adjustment)
 
         return budget
 
@@ -338,7 +344,7 @@ class BudgetAllocator:
             Rebalanced budget
         """
         if prioritize is None:
-            prioritize = [ContextType.KNOWLEDGE, ContextType.TASK, ContextType.SYSTEM]
+            prioritize = [ContextType.KNOWLEDGE, ContextType.MEMORY, ContextType.TASK, ContextType.SYSTEM]
 
         # Calculate unused tokens per type
         unused: dict[str, int] = {}

backend/app/services/context/engine.py

@@ -7,6 +7,7 @@ Provides a high-level API for assembling optimized context for LLM requests.
 
 import logging
 from typing import TYPE_CHECKING, Any
+from uuid import UUID
 
 from .assembly import ContextPipeline
 from .budget import BudgetAllocator, TokenBudget, TokenCalculator
@@ -20,6 +21,7 @@ from .types import (
     BaseContext,
     ConversationContext,
     KnowledgeContext,
+    MemoryContext,
     MessageRole,
     SystemContext,
     TaskContext,
@@ -30,6 +32,7 @@ if TYPE_CHECKING:
     from redis.asyncio import Redis
 
     from app.services.mcp.client_manager import MCPClientManager
+    from app.services.memory.integration import MemoryContextSource
 
 logger = logging.getLogger(__name__)
 
@@ -64,6 +67,7 @@ class ContextEngine:
         mcp_manager: "MCPClientManager | None" = None,
         redis: "Redis | None" = None,
         settings: ContextSettings | None = None,
+        memory_source: "MemoryContextSource | None" = None,
     ) -> None:
         """
         Initialize the context engine.
@@ -72,9 +76,11 @@ class ContextEngine:
             mcp_manager: MCP client manager for LLM Gateway/Knowledge Base
             redis: Redis connection for caching
             settings: Context settings
+            memory_source: Optional memory context source for agent memory
         """
         self._mcp = mcp_manager
         self._settings = settings or get_context_settings()
+        self._memory_source = memory_source
 
         # Initialize components
         self._calculator = TokenCalculator(mcp_manager=mcp_manager)
@@ -115,6 +121,15 @@ class ContextEngine:
         """
         self._cache.set_redis(redis)
 
+    def set_memory_source(self, memory_source: "MemoryContextSource") -> None:
+        """
+        Set memory context source for agent memory integration.
+
+        Args:
+            memory_source: Memory context source
+        """
+        self._memory_source = memory_source
+
     async def assemble_context(
         self,
         project_id: str,
@@ -126,6 +141,10 @@ class ContextEngine:
         task_description: str | None = None,
         knowledge_query: str | None = None,
         knowledge_limit: int = 10,
+        memory_query: str | None = None,
+        memory_limit: int = 20,
+        session_id: str | None = None,
+        agent_type_id: str | None = None,
         conversation_history: list[dict[str, str]] | None = None,
         tool_results: list[dict[str, Any]] | None = None,
         custom_contexts: list[BaseContext] | None = None,
@@ -151,6 +170,10 @@ class ContextEngine:
             task_description: Current task description
             knowledge_query: Query for knowledge base search
             knowledge_limit: Max number of knowledge results
+            memory_query: Query for agent memory search
+            memory_limit: Max number of memory results
+            session_id: Session ID for working memory access
+            agent_type_id: Agent type ID for procedural memory
             conversation_history: List of {"role": str, "content": str}
             tool_results: List of tool results to include
             custom_contexts: Additional custom contexts
@@ -197,15 +220,27 @@ class ContextEngine:
             )
             contexts.extend(knowledge_contexts)
 
-        # 4. Conversation history
+        # 4. Memory context from Agent Memory System
+        if memory_query and self._memory_source:
+            memory_contexts = await self._fetch_memory(
+                project_id=project_id,
+                agent_id=agent_id,
+                query=memory_query,
+                limit=memory_limit,
+                session_id=session_id,
+                agent_type_id=agent_type_id,
+            )
+            contexts.extend(memory_contexts)
+
+        # 5. Conversation history
         if conversation_history:
             contexts.extend(self._convert_conversation(conversation_history))
 
-        # 5. Tool results
+        # 6. Tool results
         if tool_results:
             contexts.extend(self._convert_tool_results(tool_results))
 
-        # 6. Custom contexts
+        # 7. Custom contexts
         if custom_contexts:
             contexts.extend(custom_contexts)
 
@@ -308,6 +343,65 @@ class ContextEngine:
             logger.warning(f"Failed to fetch knowledge: {e}")
             return []
 
+    async def _fetch_memory(
+        self,
+        project_id: str,
+        agent_id: str,
+        query: str,
+        limit: int = 20,
+        session_id: str | None = None,
+        agent_type_id: str | None = None,
+    ) -> list[MemoryContext]:
+        """
+        Fetch relevant memories from Agent Memory System.
+
+        Args:
+            project_id: Project identifier
+            agent_id: Agent identifier
+            query: Search query
+            limit: Maximum results
+            session_id: Session ID for working memory
+            agent_type_id: Agent type ID for procedural memory
+
+        Returns:
+            List of MemoryContext instances
+        """
+        if not self._memory_source:
+            return []
+
+        try:
+            # Import here to avoid circular imports
+
+            # Configure fetch limits
+            from app.services.memory.integration.context_source import MemoryFetchConfig
+
+            config = MemoryFetchConfig(
+                working_limit=min(limit // 4, 5),
+                episodic_limit=min(limit // 2, 10),
+                semantic_limit=min(limit // 2, 10),
+                procedural_limit=min(limit // 4, 5),
+                include_working=session_id is not None,
+            )
+
+            result = await self._memory_source.fetch_context(
+                query=query,
+                project_id=UUID(project_id),
+                agent_instance_id=UUID(agent_id) if agent_id else None,
+                agent_type_id=UUID(agent_type_id) if agent_type_id else None,
+                session_id=session_id,
+                config=config,
+            )
+
+            logger.debug(
+                f"Fetched {len(result.contexts)} memory contexts for query: {query}, "
+                f"by_type: {result.by_type}"
+            )
+            return result.contexts[:limit]
+
+        except Exception as e:
+            logger.warning(f"Failed to fetch memory: {e}")
+            return []
+
     def _convert_conversation(
         self,
         history: list[dict[str, str]],
@@ -466,6 +560,7 @@ def create_context_engine(
     mcp_manager: "MCPClientManager | None" = None,
     redis: "Redis | None" = None,
     settings: ContextSettings | None = None,
+    memory_source: "MemoryContextSource | None" = None,
 ) -> ContextEngine:
     """
     Create a context engine instance.
@@ -474,6 +569,7 @@ def create_context_engine(
         mcp_manager: MCP client manager
         redis: Redis connection
         settings: Context settings
+        memory_source: Optional memory context source
 
     Returns:
         Configured ContextEngine instance
@@ -482,4 +578,5 @@ def create_context_engine(
         mcp_manager=mcp_manager,
         redis=redis,
         settings=settings,
+        memory_source=memory_source,
     )

backend/app/services/context/types/__init__.py

@@ -15,6 +15,10 @@ from .conversation import (
     MessageRole,
 )
 from .knowledge import KnowledgeContext
+from .memory import (
+    MemoryContext,
+    MemorySubtype,
+)
 from .system import SystemContext
 from .task import (
     TaskComplexity,
@@ -33,6 +37,8 @@ __all__ = [
     "ContextType",
     "ConversationContext",
     "KnowledgeContext",
+    "MemoryContext",
+    "MemorySubtype",
     "MessageRole",
     "SystemContext",
     "TaskComplexity",

backend/app/services/context/types/base.py

@@ -26,6 +26,7 @@ class ContextType(str, Enum):
     KNOWLEDGE = "knowledge"
     CONVERSATION = "conversation"
     TOOL = "tool"
+    MEMORY = "memory"  # Agent memory (working, episodic, semantic, procedural)
 
     @classmethod
     def from_string(cls, value: str) -> "ContextType":

backend/app/services/context/types/memory.py

@@ -0,0 +1,282 @@
+"""
+Memory Context Type.
+
+Represents agent memory as context for LLM requests.
+Includes working, episodic, semantic, and procedural memories.
+"""
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+from .base import BaseContext, ContextPriority, ContextType
+
+
+class MemorySubtype(str, Enum):
+    """Types of agent memory."""
+
+    WORKING = "working"  # Session-scoped temporary data
+    EPISODIC = "episodic"  # Task history and outcomes
+    SEMANTIC = "semantic"  # Facts and knowledge
+    PROCEDURAL = "procedural"  # Learned procedures
+
+
+@dataclass(eq=False)
+class MemoryContext(BaseContext):
+    """
+    Context from agent memory system.
+
+    Memory context represents data retrieved from the agent
+    memory system, including:
+    - Working memory: Current session state
+    - Episodic memory: Past task experiences
+    - Semantic memory: Learned facts and knowledge
+    - Procedural memory: Known procedures and workflows
+
+    Each memory item includes relevance scoring from search.
+    """
+
+    # Memory-specific fields
+    memory_subtype: MemorySubtype = field(default=MemorySubtype.EPISODIC)
+    memory_id: str | None = field(default=None)
+    relevance_score: float = field(default=0.0)
+    importance: float = field(default=0.5)
+    search_query: str = field(default="")
+
+    # Type-specific fields (populated based on memory_subtype)
+    key: str | None = field(default=None)  # For working memory
+    task_type: str | None = field(default=None)  # For episodic
+    outcome: str | None = field(default=None)  # For episodic
+    subject: str | None = field(default=None)  # For semantic
+    predicate: str | None = field(default=None)  # For semantic
+    object_value: str | None = field(default=None)  # For semantic
+    trigger: str | None = field(default=None)  # For procedural
+    success_rate: float | None = field(default=None)  # For procedural
+
+    def get_type(self) -> ContextType:
+        """Return MEMORY context type."""
+        return ContextType.MEMORY
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary with memory-specific fields."""
+        base = super().to_dict()
+        base.update(
+            {
+                "memory_subtype": self.memory_subtype.value,
+                "memory_id": self.memory_id,
+                "relevance_score": self.relevance_score,
+                "importance": self.importance,
+                "search_query": self.search_query,
+                "key": self.key,
+                "task_type": self.task_type,
+                "outcome": self.outcome,
+                "subject": self.subject,
+                "predicate": self.predicate,
+                "object_value": self.object_value,
+                "trigger": self.trigger,
+                "success_rate": self.success_rate,
+            }
+        )
+        return base
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MemoryContext":
+        """Create MemoryContext from dictionary."""
+        return cls(
+            id=data.get("id", ""),
+            content=data["content"],
+            source=data["source"],
+            timestamp=datetime.fromisoformat(data["timestamp"])
+            if isinstance(data.get("timestamp"), str)
+            else data.get("timestamp", datetime.now(UTC)),
+            priority=data.get("priority", ContextPriority.NORMAL.value),
+            metadata=data.get("metadata", {}),
+            memory_subtype=MemorySubtype(data.get("memory_subtype", "episodic")),
+            memory_id=data.get("memory_id"),
+            relevance_score=data.get("relevance_score", 0.0),
+            importance=data.get("importance", 0.5),
+            search_query=data.get("search_query", ""),
+            key=data.get("key"),
+            task_type=data.get("task_type"),
+            outcome=data.get("outcome"),
+            subject=data.get("subject"),
+            predicate=data.get("predicate"),
+            object_value=data.get("object_value"),
+            trigger=data.get("trigger"),
+            success_rate=data.get("success_rate"),
+        )
+
+    @classmethod
+    def from_working_memory(
+        cls,
+        key: str,
+        value: Any,
+        source: str = "working_memory",
+        query: str = "",
+    ) -> "MemoryContext":
+        """
+        Create MemoryContext from working memory entry.
+
+        Args:
+            key: Working memory key
+            value: Value stored at key
+            source: Source identifier
+            query: Search query used
+
+        Returns:
+            MemoryContext instance
+        """
+        return cls(
+            content=str(value),
+            source=source,
+            memory_subtype=MemorySubtype.WORKING,
+            key=key,
+            relevance_score=1.0,  # Working memory is always relevant
+            importance=0.8,  # Higher importance for current session state
+            search_query=query,
+            priority=ContextPriority.HIGH.value,
+        )
+
+    @classmethod
+    def from_episodic_memory(
+        cls,
+        episode: Any,
+        query: str = "",
+    ) -> "MemoryContext":
+        """
+        Create MemoryContext from episodic memory episode.
+
+        Args:
+            episode: Episode object from episodic memory
+            query: Search query used
+
+        Returns:
+            MemoryContext instance
+        """
+        outcome_val = None
+        if hasattr(episode, "outcome") and episode.outcome:
+            outcome_val = (
+                episode.outcome.value
+                if hasattr(episode.outcome, "value")
+                else str(episode.outcome)
+            )
+
+        return cls(
+            content=episode.task_description,
+            source=f"episodic:{episode.id}",
+            memory_subtype=MemorySubtype.EPISODIC,
+            memory_id=str(episode.id),
+            relevance_score=getattr(episode, "importance_score", 0.5),
+            importance=getattr(episode, "importance_score", 0.5),
+            search_query=query,
+            task_type=getattr(episode, "task_type", None),
+            outcome=outcome_val,
+            metadata={
+                "session_id": getattr(episode, "session_id", None),
+                "occurred_at": episode.occurred_at.isoformat()
+                if hasattr(episode, "occurred_at") and episode.occurred_at
+                else None,
+                "lessons_learned": getattr(episode, "lessons_learned", []),
+            },
+        )
+
+    @classmethod
+    def from_semantic_memory(
+        cls,
+        fact: Any,
+        query: str = "",
+    ) -> "MemoryContext":
+        """
+        Create MemoryContext from semantic memory fact.
+
+        Args:
+            fact: Fact object from semantic memory
+            query: Search query used
+
+        Returns:
+            MemoryContext instance
+        """
+        triple = f"{fact.subject} {fact.predicate} {fact.object}"
+        return cls(
+            content=triple,
+            source=f"semantic:{fact.id}",
+            memory_subtype=MemorySubtype.SEMANTIC,
+            memory_id=str(fact.id),
+            relevance_score=getattr(fact, "confidence", 0.5),
+            importance=getattr(fact, "confidence", 0.5),
+            search_query=query,
+            subject=fact.subject,
+            predicate=fact.predicate,
+            object_value=fact.object,
+            priority=ContextPriority.NORMAL.value,
+        )
+
+    @classmethod
+    def from_procedural_memory(
+        cls,
+        procedure: Any,
+        query: str = "",
+    ) -> "MemoryContext":
+        """
+        Create MemoryContext from procedural memory procedure.
+
+        Args:
+            procedure: Procedure object from procedural memory
+            query: Search query used
+
+        Returns:
+            MemoryContext instance
+        """
+        # Format steps as content
+        steps = getattr(procedure, "steps", [])
+        steps_content = "\n".join(
+            f"  {i + 1}. {step.get('action', step) if isinstance(step, dict) else step}"
+            for i, step in enumerate(steps)
+        )
+        content = f"Procedure: {procedure.name}\nTrigger: {procedure.trigger_pattern}\nSteps:\n{steps_content}"
+
+        return cls(
+            content=content,
+            source=f"procedural:{procedure.id}",
+            memory_subtype=MemorySubtype.PROCEDURAL,
+            memory_id=str(procedure.id),
+            relevance_score=getattr(procedure, "success_rate", 0.5),
+            importance=0.7,  # Procedures are moderately important
+            search_query=query,
+            trigger=procedure.trigger_pattern,
+            success_rate=getattr(procedure, "success_rate", None),
+            metadata={
+                "steps_count": len(steps),
+                "execution_count": getattr(procedure, "success_count", 0)
+                + getattr(procedure, "failure_count", 0),
+            },
+        )
+
+    def is_working_memory(self) -> bool:
+        """Check if this is working memory."""
+        return self.memory_subtype == MemorySubtype.WORKING
+
+    def is_episodic_memory(self) -> bool:
+        """Check if this is episodic memory."""
+        return self.memory_subtype == MemorySubtype.EPISODIC
+
+    def is_semantic_memory(self) -> bool:
+        """Check if this is semantic memory."""
+        return self.memory_subtype == MemorySubtype.SEMANTIC
+
+    def is_procedural_memory(self) -> bool:
+        """Check if this is procedural memory."""
+        return self.memory_subtype == MemorySubtype.PROCEDURAL
+
+    def get_formatted_source(self) -> str:
+        """
+        Get a formatted source string for display.
+
+        Returns:
+            Formatted source string
+        """
+        parts = [f"[{self.memory_subtype.value}]", self.source]
+        if self.memory_id:
+            parts.append(f"({self.memory_id[:8]}...)")
+        return " ".join(parts)

backend/app/services/memory/__init__.py

@@ -0,0 +1,138 @@
+"""
+Agent Memory System
+
+Multi-tier cognitive memory for AI agents, providing:
+- Working Memory: Session-scoped ephemeral state (Redis/In-memory)
+- Episodic Memory: Experiential records of past tasks (PostgreSQL)
+- Semantic Memory: Learned facts and knowledge (PostgreSQL + pgvector)
+- Procedural Memory: Learned skills and procedures (PostgreSQL)
+
+Usage:
+    from app.services.memory import (
+        MemoryManager,
+        MemorySettings,
+        get_memory_settings,
+        MemoryType,
+        ScopeLevel,
+    )
+
+    # Create a manager for a session
+    manager = MemoryManager.for_session(
+        session_id="sess-123",
+        project_id=uuid,
+    )
+
+    async with manager:
+        # Working memory
+        await manager.set_working("key", {"data": "value"})
+        value = await manager.get_working("key")
+
+        # Episodic memory
+        episode = await manager.record_episode(episode_data)
+        similar = await manager.search_episodes("query")
+
+        # Semantic memory
+        fact = await manager.store_fact(fact_data)
+        facts = await manager.search_facts("query")
+
+        # Procedural memory
+        procedure = await manager.record_procedure(procedure_data)
+        procedures = await manager.find_procedures("context")
+"""
+
+# Configuration
+from .config import (
+    MemorySettings,
+    get_default_settings,
+    get_memory_settings,
+    reset_memory_settings,
+)
+
+# Exceptions
+from .exceptions import (
+    CheckpointError,
+    EmbeddingError,
+    MemoryCapacityError,
+    MemoryConflictError,
+    MemoryConsolidationError,
+    MemoryError,
+    MemoryExpiredError,
+    MemoryNotFoundError,
+    MemoryRetrievalError,
+    MemoryScopeError,
+    MemorySerializationError,
+    MemoryStorageError,
+)
+
+# Manager
+from .manager import MemoryManager
+
+# Types
+from .types import (
+    ConsolidationStatus,
+    ConsolidationType,
+    Episode,
+    EpisodeCreate,
+    Fact,
+    FactCreate,
+    MemoryItem,
+    MemoryStats,
+    MemoryStore,
+    MemoryType,
+    Outcome,
+    Procedure,
+    ProcedureCreate,
+    RetrievalResult,
+    ScopeContext,
+    ScopeLevel,
+    Step,
+    TaskState,
+    WorkingMemoryItem,
+)
+
+__all__ = [
+    "CheckpointError",
+    "ConsolidationStatus",
+    "ConsolidationType",
+    "EmbeddingError",
+    "Episode",
+    "EpisodeCreate",
+    "Fact",
+    "FactCreate",
+    "MemoryCapacityError",
+    "MemoryConflictError",
+    "MemoryConsolidationError",
+    # Exceptions
+    "MemoryError",
+    "MemoryExpiredError",
+    "MemoryItem",
+    # Manager
+    "MemoryManager",
+    "MemoryNotFoundError",
+    "MemoryRetrievalError",
+    "MemoryScopeError",
+    "MemorySerializationError",
+    # Configuration
+    "MemorySettings",
+    "MemoryStats",
+    "MemoryStorageError",
+    # Types - Abstract
+    "MemoryStore",
+    # Types - Enums
+    "MemoryType",
+    "Outcome",
+    "Procedure",
+    "ProcedureCreate",
+    "RetrievalResult",
+    # Types - Data Classes
+    "ScopeContext",
+    "ScopeLevel",
+    "Step",
+    "TaskState",
+    "WorkingMemoryItem",
+    "get_default_settings",
+    "get_memory_settings",
+    "reset_memory_settings",
+    # MCP Tools - lazy import to avoid circular dependencies
+    # Import directly: from app.services.memory.mcp import MemoryToolService
+]

backend/app/services/memory/cache/__init__.py

@@ -0,0 +1,21 @@
+# app/services/memory/cache/__init__.py
+"""
+Memory Caching Layer.
+
+Provides caching for memory operations:
+- Hot Memory Cache: LRU cache for frequently accessed memories
+- Embedding Cache: Cache embeddings by content hash
+- Cache Manager: Unified cache management with invalidation
+"""
+
+from .cache_manager import CacheManager, CacheStats, get_cache_manager
+from .embedding_cache import EmbeddingCache
+from .hot_cache import HotMemoryCache
+
+__all__ = [
+    "CacheManager",
+    "CacheStats",
+    "EmbeddingCache",
+    "HotMemoryCache",
+    "get_cache_manager",
+]

backend/app/services/memory/cache/cache_manager.py

@@ -0,0 +1,500 @@
+# app/services/memory/cache/cache_manager.py
+"""
+Cache Manager.
+
+Unified cache management for memory operations.
+Coordinates hot cache, embedding cache, and retrieval cache.
+Provides centralized invalidation and statistics.
+"""
+
+import logging
+import threading
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+from uuid import UUID
+
+from app.services.memory.config import get_memory_settings
+
+from .embedding_cache import EmbeddingCache, create_embedding_cache
+from .hot_cache import CacheKey, HotMemoryCache, create_hot_cache
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis
+
+    from app.services.memory.indexing.retrieval import RetrievalCache
+
+logger = logging.getLogger(__name__)
+
+
+def _utcnow() -> datetime:
+    """Get current UTC time as timezone-aware datetime."""
+    return datetime.now(UTC)
+
+
+@dataclass
+class CacheStats:
+    """Aggregated cache statistics."""
+
+    hot_cache: dict[str, Any] = field(default_factory=dict)
+    embedding_cache: dict[str, Any] = field(default_factory=dict)
+    retrieval_cache: dict[str, Any] = field(default_factory=dict)
+    overall_hit_rate: float = 0.0
+    last_cleanup: datetime | None = None
+    cleanup_count: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "hot_cache": self.hot_cache,
+            "embedding_cache": self.embedding_cache,
+            "retrieval_cache": self.retrieval_cache,
+            "overall_hit_rate": self.overall_hit_rate,
+            "last_cleanup": self.last_cleanup.isoformat() if self.last_cleanup else None,
+            "cleanup_count": self.cleanup_count,
+        }
+
+
+class CacheManager:
+    """
+    Unified cache manager for memory operations.
+
+    Provides:
+    - Centralized cache configuration
+    - Coordinated invalidation across caches
+    - Aggregated statistics
+    - Automatic cleanup scheduling
+
+    Performance targets:
+    - Overall cache hit rate > 80%
+    - Cache operations < 1ms (memory), < 5ms (Redis)
+    """
+
+    def __init__(
+        self,
+        hot_cache: HotMemoryCache[Any] | None = None,
+        embedding_cache: EmbeddingCache | None = None,
+        retrieval_cache: "RetrievalCache | None" = None,
+        redis: "Redis | None" = None,
+    ) -> None:
+        """
+        Initialize the cache manager.
+
+        Args:
+            hot_cache: Optional pre-configured hot cache
+            embedding_cache: Optional pre-configured embedding cache
+            retrieval_cache: Optional pre-configured retrieval cache
+            redis: Optional Redis connection for persistence
+        """
+        self._settings = get_memory_settings()
+        self._redis = redis
+        self._enabled = self._settings.cache_enabled
+
+        # Initialize caches
+        if hot_cache:
+            self._hot_cache = hot_cache
+        else:
+            self._hot_cache = create_hot_cache(
+                max_size=self._settings.cache_max_items,
+                default_ttl_seconds=self._settings.cache_ttl_seconds,
+            )
+
+        if embedding_cache:
+            self._embedding_cache = embedding_cache
+        else:
+            self._embedding_cache = create_embedding_cache(
+                max_size=self._settings.cache_max_items,
+                default_ttl_seconds=self._settings.cache_ttl_seconds * 12,  # 1hr for embeddings
+                redis=redis,
+            )
+
+        self._retrieval_cache = retrieval_cache
+
+        # Stats tracking
+        self._last_cleanup: datetime | None = None
+        self._cleanup_count = 0
+        self._lock = threading.RLock()
+
+        logger.info(
+            f"Initialized CacheManager: enabled={self._enabled}, "
+            f"redis={'connected' if redis else 'disabled'}"
+        )
+
+    def set_redis(self, redis: "Redis") -> None:
+        """Set Redis connection for all caches."""
+        self._redis = redis
+        self._embedding_cache.set_redis(redis)
+
+    def set_retrieval_cache(self, cache: "RetrievalCache") -> None:
+        """Set retrieval cache instance."""
+        self._retrieval_cache = cache
+
+    @property
+    def is_enabled(self) -> bool:
+        """Check if caching is enabled."""
+        return self._enabled
+
+    @property
+    def hot_cache(self) -> HotMemoryCache[Any]:
+        """Get the hot memory cache."""
+        return self._hot_cache
+
+    @property
+    def embedding_cache(self) -> EmbeddingCache:
+        """Get the embedding cache."""
+        return self._embedding_cache
+
+    @property
+    def retrieval_cache(self) -> "RetrievalCache | None":
+        """Get the retrieval cache."""
+        return self._retrieval_cache
+
+    # =========================================================================
+    # Hot Memory Cache Operations
+    # =========================================================================
+
+    def get_memory(
+        self,
+        memory_type: str,
+        memory_id: UUID | str,
+        scope: str | None = None,
+    ) -> Any | None:
+        """
+        Get a memory from hot cache.
+
+        Args:
+            memory_type: Type of memory
+            memory_id: Memory ID
+            scope: Optional scope
+
+        Returns:
+            Cached memory or None
+        """
+        if not self._enabled:
+            return None
+        return self._hot_cache.get_by_id(memory_type, memory_id, scope)
+
+    def cache_memory(
+        self,
+        memory_type: str,
+        memory_id: UUID | str,
+        memory: Any,
+        scope: str | None = None,
+        ttl_seconds: float | None = None,
+    ) -> None:
+        """
+        Cache a memory in hot cache.
+
+        Args:
+            memory_type: Type of memory
+            memory_id: Memory ID
+            memory: Memory object
+            scope: Optional scope
+            ttl_seconds: Optional TTL override
+        """
+        if not self._enabled:
+            return
+        self._hot_cache.put_by_id(memory_type, memory_id, memory, scope, ttl_seconds)
+
+    # =========================================================================
+    # Embedding Cache Operations
+    # =========================================================================
+
+    async def get_embedding(
+        self,
+        content: str,
+        model: str = "default",
+    ) -> list[float] | None:
+        """
+        Get a cached embedding.
+
+        Args:
+            content: Content text
+            model: Model name
+
+        Returns:
+            Cached embedding or None
+        """
+        if not self._enabled:
+            return None
+        return await self._embedding_cache.get(content, model)
+
+    async def cache_embedding(
+        self,
+        content: str,
+        embedding: list[float],
+        model: str = "default",
+        ttl_seconds: float | None = None,
+    ) -> str:
+        """
+        Cache an embedding.
+
+        Args:
+            content: Content text
+            embedding: Embedding vector
+            model: Model name
+            ttl_seconds: Optional TTL override
+
+        Returns:
+            Content hash
+        """
+        if not self._enabled:
+            return EmbeddingCache.hash_content(content)
+        return await self._embedding_cache.put(content, embedding, model, ttl_seconds)
+
+    # =========================================================================
+    # Invalidation
+    # =========================================================================
+
+    async def invalidate_memory(
+        self,
+        memory_type: str,
+        memory_id: UUID | str,
+        scope: str | None = None,
+    ) -> int:
+        """
+        Invalidate a memory across all caches.
+
+        Args:
+            memory_type: Type of memory
+            memory_id: Memory ID
+            scope: Optional scope
+
+        Returns:
+            Number of entries invalidated
+        """
+        count = 0
+
+        # Invalidate hot cache
+        if self._hot_cache.invalidate_by_id(memory_type, memory_id, scope):
+            count += 1
+
+        # Invalidate retrieval cache
+        if self._retrieval_cache:
+            uuid_id = UUID(str(memory_id)) if not isinstance(memory_id, UUID) else memory_id
+            count += self._retrieval_cache.invalidate_by_memory(uuid_id)
+
+        logger.debug(f"Invalidated {count} cache entries for {memory_type}:{memory_id}")
+        return count
+
+    async def invalidate_by_type(self, memory_type: str) -> int:
+        """
+        Invalidate all entries of a memory type.
+
+        Args:
+            memory_type: Type of memory
+
+        Returns:
+            Number of entries invalidated
+        """
+        count = self._hot_cache.invalidate_by_type(memory_type)
+
+        if self._retrieval_cache:
+            count += self._retrieval_cache.clear()
+
+        logger.info(f"Invalidated {count} cache entries for type {memory_type}")
+        return count
+
+    async def invalidate_by_scope(self, scope: str) -> int:
+        """
+        Invalidate all entries in a scope.
+
+        Args:
+            scope: Scope to invalidate (e.g., project_id)
+
+        Returns:
+            Number of entries invalidated
+        """
+        count = self._hot_cache.invalidate_by_scope(scope)
+
+        # Retrieval cache doesn't support scope-based invalidation
+        # so we clear it entirely for safety
+        if self._retrieval_cache:
+            count += self._retrieval_cache.clear()
+
+        logger.info(f"Invalidated {count} cache entries for scope {scope}")
+        return count
+
+    async def invalidate_embedding(
+        self,
+        content: str,
+        model: str = "default",
+    ) -> bool:
+        """
+        Invalidate a cached embedding.
+
+        Args:
+            content: Content text
+            model: Model name
+
+        Returns:
+            True if entry was found and removed
+        """
+        return await self._embedding_cache.invalidate(content, model)
+
+    async def clear_all(self) -> int:
+        """
+        Clear all caches.
+
+        Returns:
+            Total number of entries cleared
+        """
+        count = 0
+
+        count += self._hot_cache.clear()
+        count += await self._embedding_cache.clear()
+
+        if self._retrieval_cache:
+            count += self._retrieval_cache.clear()
+
+        logger.info(f"Cleared {count} entries from all caches")
+        return count
+
+    # =========================================================================
+    # Cleanup
+    # =========================================================================
+
+    async def cleanup_expired(self) -> int:
+        """
+        Clean up expired entries from all caches.
+
+        Returns:
+            Number of entries cleaned up
+        """
+        with self._lock:
+            count = 0
+
+            count += self._hot_cache.cleanup_expired()
+            count += self._embedding_cache.cleanup_expired()
+
+            # Retrieval cache doesn't have a cleanup method,
+            # but entries expire on access
+
+            self._last_cleanup = _utcnow()
+            self._cleanup_count += 1
+
+            if count > 0:
+                logger.info(f"Cleaned up {count} expired cache entries")
+
+            return count
+
+    # =========================================================================
+    # Statistics
+    # =========================================================================
+
+    def get_stats(self) -> CacheStats:
+        """
+        Get aggregated cache statistics.
+
+        Returns:
+            CacheStats with all cache metrics
+        """
+        hot_stats = self._hot_cache.get_stats().to_dict()
+        emb_stats = self._embedding_cache.get_stats().to_dict()
+
+        retrieval_stats: dict[str, Any] = {}
+        if self._retrieval_cache:
+            retrieval_stats = self._retrieval_cache.get_stats()
+
+        # Calculate overall hit rate
+        total_hits = hot_stats.get("hits", 0) + emb_stats.get("hits", 0)
+        total_misses = hot_stats.get("misses", 0) + emb_stats.get("misses", 0)
+
+        if retrieval_stats:
+            # Retrieval cache doesn't track hits/misses the same way
+            pass
+
+        total_requests = total_hits + total_misses
+        overall_hit_rate = total_hits / total_requests if total_requests > 0 else 0.0
+
+        return CacheStats(
+            hot_cache=hot_stats,
+            embedding_cache=emb_stats,
+            retrieval_cache=retrieval_stats,
+            overall_hit_rate=overall_hit_rate,
+            last_cleanup=self._last_cleanup,
+            cleanup_count=self._cleanup_count,
+        )
+
+    def get_hot_memories(self, limit: int = 10) -> list[tuple[CacheKey, int]]:
+        """
+        Get the most frequently accessed memories.
+
+        Args:
+            limit: Maximum number to return
+
+        Returns:
+            List of (key, access_count) tuples
+        """
+        return self._hot_cache.get_hot_memories(limit)
+
+    def reset_stats(self) -> None:
+        """Reset all cache statistics."""
+        self._hot_cache.reset_stats()
+        self._embedding_cache.reset_stats()
+
+    # =========================================================================
+    # Warmup
+    # =========================================================================
+
+    async def warmup(
+        self,
+        memories: list[tuple[str, UUID | str, Any]],
+        scope: str | None = None,
+    ) -> int:
+        """
+        Warm up the hot cache with memories.
+
+        Args:
+            memories: List of (memory_type, memory_id, memory) tuples
+            scope: Optional scope for all memories
+
+        Returns:
+            Number of memories cached
+        """
+        if not self._enabled:
+            return 0
+
+        for memory_type, memory_id, memory in memories:
+            self._hot_cache.put_by_id(memory_type, memory_id, memory, scope)
+
+        logger.info(f"Warmed up cache with {len(memories)} memories")
+        return len(memories)
+
+
+# Singleton instance
+_cache_manager: CacheManager | None = None
+_cache_manager_lock = threading.Lock()
+
+
+def get_cache_manager(
+    redis: "Redis | None" = None,
+    reset: bool = False,
+) -> CacheManager:
+    """
+    Get the global CacheManager instance.
+
+    Thread-safe with double-checked locking pattern.
+
+    Args:
+        redis: Optional Redis connection
+        reset: Force create a new instance
+
+    Returns:
+        CacheManager instance
+    """
+    global _cache_manager
+
+    if reset or _cache_manager is None:
+        with _cache_manager_lock:
+            if reset or _cache_manager is None:
+                _cache_manager = CacheManager(redis=redis)
+
+    return _cache_manager
+
+
+def reset_cache_manager() -> None:
+    """Reset the global cache manager instance."""
+    global _cache_manager
+    with _cache_manager_lock:
+        _cache_manager = None

backend/app/services/memory/cache/embedding_cache.py

@@ -0,0 +1,627 @@
+# app/services/memory/cache/embedding_cache.py
+"""
+Embedding Cache.
+
+Caches embeddings by content hash to avoid recomputing.
+Provides significant performance improvement for repeated content.
+"""
+
+import hashlib
+import logging
+import threading
+from collections import OrderedDict
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis
+
+logger = logging.getLogger(__name__)
+
+
+def _utcnow() -> datetime:
+    """Get current UTC time as timezone-aware datetime."""
+    return datetime.now(UTC)
+
+
+@dataclass
+class EmbeddingEntry:
+    """A cached embedding entry."""
+
+    embedding: list[float]
+    content_hash: str
+    model: str
+    created_at: datetime
+    ttl_seconds: float = 3600.0  # 1 hour default
+
+    def is_expired(self) -> bool:
+        """Check if this entry has expired."""
+        age = (_utcnow() - self.created_at).total_seconds()
+        return age > self.ttl_seconds
+
+
+@dataclass
+class EmbeddingCacheStats:
+    """Statistics for the embedding cache."""
+
+    hits: int = 0
+    misses: int = 0
+    evictions: int = 0
+    expirations: int = 0
+    current_size: int = 0
+    max_size: int = 0
+    bytes_saved: int = 0  # Estimated bytes saved by caching
+
+    @property
+    def hit_rate(self) -> float:
+        """Calculate cache hit rate."""
+        total = self.hits + self.misses
+        if total == 0:
+            return 0.0
+        return self.hits / total
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "hits": self.hits,
+            "misses": self.misses,
+            "evictions": self.evictions,
+            "expirations": self.expirations,
+            "current_size": self.current_size,
+            "max_size": self.max_size,
+            "hit_rate": self.hit_rate,
+            "bytes_saved": self.bytes_saved,
+        }
+
+
+class EmbeddingCache:
+    """
+    Cache for embeddings by content hash.
+
+    Features:
+    - Content-hash based deduplication
+    - LRU eviction
+    - TTL-based expiration
+    - Optional Redis backing for persistence
+    - Thread-safe operations
+
+    Performance targets:
+    - Cache hit rate > 90% for repeated content
+    - Get/put operations < 1ms (memory), < 5ms (Redis)
+    """
+
+    def __init__(
+        self,
+        max_size: int = 50000,
+        default_ttl_seconds: float = 3600.0,
+        redis: "Redis | None" = None,
+        redis_prefix: str = "mem:emb",
+    ) -> None:
+        """
+        Initialize the embedding cache.
+
+        Args:
+            max_size: Maximum number of entries in memory cache
+            default_ttl_seconds: Default TTL for entries (1 hour)
+            redis: Optional Redis connection for persistence
+            redis_prefix: Prefix for Redis keys
+        """
+        self._max_size = max_size
+        self._default_ttl = default_ttl_seconds
+        self._cache: OrderedDict[str, EmbeddingEntry] = OrderedDict()
+        self._lock = threading.RLock()
+        self._stats = EmbeddingCacheStats(max_size=max_size)
+        self._redis = redis
+        self._redis_prefix = redis_prefix
+
+        logger.info(
+            f"Initialized EmbeddingCache with max_size={max_size}, "
+            f"ttl={default_ttl_seconds}s, redis={'enabled' if redis else 'disabled'}"
+        )
+
+    def set_redis(self, redis: "Redis") -> None:
+        """Set Redis connection for persistence."""
+        self._redis = redis
+
+    @staticmethod
+    def hash_content(content: str) -> str:
+        """
+        Compute hash of content for cache key.
+
+        Args:
+            content: Content to hash
+
+        Returns:
+            32-character hex hash
+        """
+        return hashlib.sha256(content.encode()).hexdigest()[:32]
+
+    def _cache_key(self, content_hash: str, model: str) -> str:
+        """Build cache key from content hash and model."""
+        return f"{content_hash}:{model}"
+
+    def _redis_key(self, content_hash: str, model: str) -> str:
+        """Build Redis key from content hash and model."""
+        return f"{self._redis_prefix}:{content_hash}:{model}"
+
+    async def get(
+        self,
+        content: str,
+        model: str = "default",
+    ) -> list[float] | None:
+        """
+        Get a cached embedding.
+
+        Args:
+            content: Content text
+            model: Model name
+
+        Returns:
+            Cached embedding or None if not found/expired
+        """
+        content_hash = self.hash_content(content)
+        cache_key = self._cache_key(content_hash, model)
+
+        # Check memory cache first
+        with self._lock:
+            if cache_key in self._cache:
+                entry = self._cache[cache_key]
+                if entry.is_expired():
+                    del self._cache[cache_key]
+                    self._stats.expirations += 1
+                    self._stats.current_size = len(self._cache)
+                else:
+                    # Move to end (most recently used)
+                    self._cache.move_to_end(cache_key)
+                    self._stats.hits += 1
+                    return entry.embedding
+
+        # Check Redis if available
+        if self._redis:
+            try:
+                redis_key = self._redis_key(content_hash, model)
+                data = await self._redis.get(redis_key)
+                if data:
+                    import json
+
+                    embedding = json.loads(data)
+                    # Store in memory cache for faster access
+                    self._put_memory(content_hash, model, embedding)
+                    self._stats.hits += 1
+                    return embedding
+            except Exception as e:
+                logger.warning(f"Redis get error: {e}")
+
+        self._stats.misses += 1
+        return None
+
+    async def get_by_hash(
+        self,
+        content_hash: str,
+        model: str = "default",
+    ) -> list[float] | None:
+        """
+        Get a cached embedding by hash.
+
+        Args:
+            content_hash: Content hash
+            model: Model name
+
+        Returns:
+            Cached embedding or None if not found/expired
+        """
+        cache_key = self._cache_key(content_hash, model)
+
+        with self._lock:
+            if cache_key in self._cache:
+                entry = self._cache[cache_key]
+                if entry.is_expired():
+                    del self._cache[cache_key]
+                    self._stats.expirations += 1
+                    self._stats.current_size = len(self._cache)
+                else:
+                    self._cache.move_to_end(cache_key)
+                    self._stats.hits += 1
+                    return entry.embedding
+
+        # Check Redis
+        if self._redis:
+            try:
+                redis_key = self._redis_key(content_hash, model)
+                data = await self._redis.get(redis_key)
+                if data:
+                    import json
+
+                    embedding = json.loads(data)
+                    self._put_memory(content_hash, model, embedding)
+                    self._stats.hits += 1
+                    return embedding
+            except Exception as e:
+                logger.warning(f"Redis get error: {e}")
+
+        self._stats.misses += 1
+        return None
+
+    async def put(
+        self,
+        content: str,
+        embedding: list[float],
+        model: str = "default",
+        ttl_seconds: float | None = None,
+    ) -> str:
+        """
+        Cache an embedding.
+
+        Args:
+            content: Content text
+            embedding: Embedding vector
+            model: Model name
+            ttl_seconds: Optional TTL override
+
+        Returns:
+            Content hash
+        """
+        content_hash = self.hash_content(content)
+        ttl = ttl_seconds or self._default_ttl
+
+        # Store in memory
+        self._put_memory(content_hash, model, embedding, ttl)
+
+        # Store in Redis if available
+        if self._redis:
+            try:
+                import json
+
+                redis_key = self._redis_key(content_hash, model)
+                await self._redis.setex(
+                    redis_key,
+                    int(ttl),
+                    json.dumps(embedding),
+                )
+            except Exception as e:
+                logger.warning(f"Redis put error: {e}")
+
+        return content_hash
+
+    def _put_memory(
+        self,
+        content_hash: str,
+        model: str,
+        embedding: list[float],
+        ttl_seconds: float | None = None,
+    ) -> None:
+        """Store in memory cache."""
+        with self._lock:
+            # Evict if at capacity
+            self._evict_if_needed()
+
+            cache_key = self._cache_key(content_hash, model)
+            entry = EmbeddingEntry(
+                embedding=embedding,
+                content_hash=content_hash,
+                model=model,
+                created_at=_utcnow(),
+                ttl_seconds=ttl_seconds or self._default_ttl,
+            )
+
+            self._cache[cache_key] = entry
+            self._cache.move_to_end(cache_key)
+            self._stats.current_size = len(self._cache)
+
+    def _evict_if_needed(self) -> None:
+        """Evict entries if cache is at capacity."""
+        while len(self._cache) >= self._max_size:
+            if self._cache:
+                self._cache.popitem(last=False)
+                self._stats.evictions += 1
+
+    async def put_batch(
+        self,
+        items: list[tuple[str, list[float]]],
+        model: str = "default",
+        ttl_seconds: float | None = None,
+    ) -> list[str]:
+        """
+        Cache multiple embeddings.
+
+        Args:
+            items: List of (content, embedding) tuples
+            model: Model name
+            ttl_seconds: Optional TTL override
+
+        Returns:
+            List of content hashes
+        """
+        hashes = []
+        for content, embedding in items:
+            content_hash = await self.put(content, embedding, model, ttl_seconds)
+            hashes.append(content_hash)
+        return hashes
+
+    async def invalidate(
+        self,
+        content: str,
+        model: str = "default",
+    ) -> bool:
+        """
+        Invalidate a cached embedding.
+
+        Args:
+            content: Content text
+            model: Model name
+
+        Returns:
+            True if entry was found and removed
+        """
+        content_hash = self.hash_content(content)
+        return await self.invalidate_by_hash(content_hash, model)
+
+    async def invalidate_by_hash(
+        self,
+        content_hash: str,
+        model: str = "default",
+    ) -> bool:
+        """
+        Invalidate a cached embedding by hash.
+
+        Args:
+            content_hash: Content hash
+            model: Model name
+
+        Returns:
+            True if entry was found and removed
+        """
+        cache_key = self._cache_key(content_hash, model)
+        removed = False
+
+        with self._lock:
+            if cache_key in self._cache:
+                del self._cache[cache_key]
+                self._stats.current_size = len(self._cache)
+                removed = True
+
+        # Remove from Redis
+        if self._redis:
+            try:
+                redis_key = self._redis_key(content_hash, model)
+                await self._redis.delete(redis_key)
+                removed = True
+            except Exception as e:
+                logger.warning(f"Redis delete error: {e}")
+
+        return removed
+
+    async def invalidate_by_model(self, model: str) -> int:
+        """
+        Invalidate all embeddings for a model.
+
+        Args:
+            model: Model name
+
+        Returns:
+            Number of entries invalidated
+        """
+        count = 0
+
+        with self._lock:
+            keys_to_remove = [
+                k for k, v in self._cache.items() if v.model == model
+            ]
+            for key in keys_to_remove:
+                del self._cache[key]
+                count += 1
+
+            self._stats.current_size = len(self._cache)
+
+        # Note: Redis pattern deletion would require SCAN which is expensive
+        # For now, we only clear memory cache for model-based invalidation
+
+        return count
+
+    async def clear(self) -> int:
+        """
+        Clear all cache entries.
+
+        Returns:
+            Number of entries cleared
+        """
+        with self._lock:
+            count = len(self._cache)
+            self._cache.clear()
+            self._stats.current_size = 0
+
+        # Clear Redis entries
+        if self._redis:
+            try:
+                pattern = f"{self._redis_prefix}:*"
+                deleted = 0
+                async for key in self._redis.scan_iter(match=pattern):
+                    await self._redis.delete(key)
+                    deleted += 1
+                count = max(count, deleted)
+            except Exception as e:
+                logger.warning(f"Redis clear error: {e}")
+
+        logger.info(f"Cleared {count} entries from embedding cache")
+        return count
+
+    def cleanup_expired(self) -> int:
+        """
+        Remove all expired entries from memory cache.
+
+        Returns:
+            Number of entries removed
+        """
+        with self._lock:
+            keys_to_remove = [
+                k for k, v in self._cache.items() if v.is_expired()
+            ]
+            for key in keys_to_remove:
+                del self._cache[key]
+                self._stats.expirations += 1
+
+            self._stats.current_size = len(self._cache)
+
+            if keys_to_remove:
+                logger.debug(f"Cleaned up {len(keys_to_remove)} expired embeddings")
+
+            return len(keys_to_remove)
+
+    def get_stats(self) -> EmbeddingCacheStats:
+        """Get cache statistics."""
+        with self._lock:
+            self._stats.current_size = len(self._cache)
+            return self._stats
+
+    def reset_stats(self) -> None:
+        """Reset cache statistics."""
+        with self._lock:
+            self._stats = EmbeddingCacheStats(
+                max_size=self._max_size,
+                current_size=len(self._cache),
+            )
+
+    @property
+    def size(self) -> int:
+        """Get current cache size."""
+        return len(self._cache)
+
+    @property
+    def max_size(self) -> int:
+        """Get maximum cache size."""
+        return self._max_size
+
+
+class CachedEmbeddingGenerator:
+    """
+    Wrapper for embedding generators with caching.
+
+    Wraps an embedding generator to cache results.
+    """
+
+    def __init__(
+        self,
+        generator: Any,
+        cache: EmbeddingCache,
+        model: str = "default",
+    ) -> None:
+        """
+        Initialize the cached embedding generator.
+
+        Args:
+            generator: Underlying embedding generator
+            cache: Embedding cache
+            model: Model name for cache keys
+        """
+        self._generator = generator
+        self._cache = cache
+        self._model = model
+        self._call_count = 0
+        self._cache_hit_count = 0
+
+    async def generate(self, text: str) -> list[float]:
+        """
+        Generate embedding with caching.
+
+        Args:
+            text: Text to embed
+
+        Returns:
+            Embedding vector
+        """
+        self._call_count += 1
+
+        # Check cache first
+        cached = await self._cache.get(text, self._model)
+        if cached is not None:
+            self._cache_hit_count += 1
+            return cached
+
+        # Generate and cache
+        embedding = await self._generator.generate(text)
+        await self._cache.put(text, embedding, self._model)
+
+        return embedding
+
+    async def generate_batch(
+        self,
+        texts: list[str],
+    ) -> list[list[float]]:
+        """
+        Generate embeddings for multiple texts with caching.
+
+        Args:
+            texts: Texts to embed
+
+        Returns:
+            List of embedding vectors
+        """
+        results: list[list[float] | None] = [None] * len(texts)
+        to_generate: list[tuple[int, str]] = []
+
+        # Check cache for each text
+        for i, text in enumerate(texts):
+            cached = await self._cache.get(text, self._model)
+            if cached is not None:
+                results[i] = cached
+                self._cache_hit_count += 1
+            else:
+                to_generate.append((i, text))
+
+        self._call_count += len(texts)
+
+        # Generate missing embeddings
+        if to_generate:
+            if hasattr(self._generator, "generate_batch"):
+                texts_to_gen = [t for _, t in to_generate]
+                embeddings = await self._generator.generate_batch(texts_to_gen)
+
+                for (idx, text), embedding in zip(to_generate, embeddings, strict=True):
+                    results[idx] = embedding
+                    await self._cache.put(text, embedding, self._model)
+            else:
+                # Fallback to individual generation
+                for idx, text in to_generate:
+                    embedding = await self._generator.generate(text)
+                    results[idx] = embedding
+                    await self._cache.put(text, embedding, self._model)
+
+        return results  # type: ignore[return-value]
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get generator statistics."""
+        return {
+            "call_count": self._call_count,
+            "cache_hit_count": self._cache_hit_count,
+            "cache_hit_rate": (
+                self._cache_hit_count / self._call_count
+                if self._call_count > 0
+                else 0.0
+            ),
+            "cache_stats": self._cache.get_stats().to_dict(),
+        }
+
+
+# Factory function
+def create_embedding_cache(
+    max_size: int = 50000,
+    default_ttl_seconds: float = 3600.0,
+    redis: "Redis | None" = None,
+) -> EmbeddingCache:
+    """
+    Create an embedding cache.
+
+    Args:
+        max_size: Maximum number of entries
+        default_ttl_seconds: Default TTL for entries
+        redis: Optional Redis connection
+
+    Returns:
+        Configured EmbeddingCache instance
+    """
+    return EmbeddingCache(
+        max_size=max_size,
+        default_ttl_seconds=default_ttl_seconds,
+        redis=redis,
+    )

backend/app/services/memory/cache/hot_cache.py

@@ -0,0 +1,463 @@
+# app/services/memory/cache/hot_cache.py
+"""
+Hot Memory Cache.
+
+LRU cache for frequently accessed memories.
+Provides fast access to recently used memories without database queries.
+"""
+
+import logging
+import threading
+from collections import OrderedDict
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+from uuid import UUID
+
+logger = logging.getLogger(__name__)
+
+
+def _utcnow() -> datetime:
+    """Get current UTC time as timezone-aware datetime."""
+    return datetime.now(UTC)
+
+
+@dataclass
+class CacheEntry[T]:
+    """A cached memory entry with metadata."""
+
+    value: T
+    created_at: datetime
+    last_accessed_at: datetime
+    access_count: int = 1
+    ttl_seconds: float = 300.0
+
+    def is_expired(self) -> bool:
+        """Check if this entry has expired."""
+        age = (_utcnow() - self.created_at).total_seconds()
+        return age > self.ttl_seconds
+
+    def touch(self) -> None:
+        """Update access time and count."""
+        self.last_accessed_at = _utcnow()
+        self.access_count += 1
+
+
+@dataclass
+class CacheKey:
+    """A structured cache key with components."""
+
+    memory_type: str
+    memory_id: str
+    scope: str | None = None
+
+    def __hash__(self) -> int:
+        return hash((self.memory_type, self.memory_id, self.scope))
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, CacheKey):
+            return False
+        return (
+            self.memory_type == other.memory_type
+            and self.memory_id == other.memory_id
+            and self.scope == other.scope
+        )
+
+    def __str__(self) -> str:
+        if self.scope:
+            return f"{self.memory_type}:{self.scope}:{self.memory_id}"
+        return f"{self.memory_type}:{self.memory_id}"
+
+
+@dataclass
+class HotCacheStats:
+    """Statistics for the hot memory cache."""
+
+    hits: int = 0
+    misses: int = 0
+    evictions: int = 0
+    expirations: int = 0
+    current_size: int = 0
+    max_size: int = 0
+
+    @property
+    def hit_rate(self) -> float:
+        """Calculate cache hit rate."""
+        total = self.hits + self.misses
+        if total == 0:
+            return 0.0
+        return self.hits / total
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "hits": self.hits,
+            "misses": self.misses,
+            "evictions": self.evictions,
+            "expirations": self.expirations,
+            "current_size": self.current_size,
+            "max_size": self.max_size,
+            "hit_rate": self.hit_rate,
+        }
+
+
+class HotMemoryCache[T]:
+    """
+    LRU cache for frequently accessed memories.
+
+    Features:
+    - LRU eviction when capacity is reached
+    - TTL-based expiration
+    - Access count tracking for hot memory identification
+    - Thread-safe operations
+    - Scoped invalidation
+
+    Performance targets:
+    - Cache hit rate > 80% for hot memories
+    - Get/put operations < 1ms
+    """
+
+    def __init__(
+        self,
+        max_size: int = 10000,
+        default_ttl_seconds: float = 300.0,
+    ) -> None:
+        """
+        Initialize the hot memory cache.
+
+        Args:
+            max_size: Maximum number of entries
+            default_ttl_seconds: Default TTL for entries (5 minutes)
+        """
+        self._max_size = max_size
+        self._default_ttl = default_ttl_seconds
+        self._cache: OrderedDict[CacheKey, CacheEntry[T]] = OrderedDict()
+        self._lock = threading.RLock()
+        self._stats = HotCacheStats(max_size=max_size)
+        logger.info(
+            f"Initialized HotMemoryCache with max_size={max_size}, "
+            f"ttl={default_ttl_seconds}s"
+        )
+
+    def get(self, key: CacheKey) -> T | None:
+        """
+        Get a memory from cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value or None if not found/expired
+        """
+        with self._lock:
+            if key not in self._cache:
+                self._stats.misses += 1
+                return None
+
+            entry = self._cache[key]
+
+            # Check expiration
+            if entry.is_expired():
+                del self._cache[key]
+                self._stats.expirations += 1
+                self._stats.misses += 1
+                self._stats.current_size = len(self._cache)
+                return None
+
+            # Move to end (most recently used)
+            self._cache.move_to_end(key)
+            entry.touch()
+
+            self._stats.hits += 1
+            return entry.value
+
+    def get_by_id(
+        self,
+        memory_type: str,
+        memory_id: UUID | str,
+        scope: str | None = None,
+    ) -> T | None:
+        """
+        Get a memory by type and ID.
+
+        Args:
+            memory_type: Type of memory (episodic, semantic, procedural)
+            memory_id: Memory ID
+            scope: Optional scope (project_id, agent_id)
+
+        Returns:
+            Cached value or None if not found/expired
+        """
+        key = CacheKey(
+            memory_type=memory_type,
+            memory_id=str(memory_id),
+            scope=scope,
+        )
+        return self.get(key)
+
+    def put(
+        self,
+        key: CacheKey,
+        value: T,
+        ttl_seconds: float | None = None,
+    ) -> None:
+        """
+        Put a memory into cache.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+            ttl_seconds: Optional TTL override
+        """
+        with self._lock:
+            # Evict if at capacity
+            self._evict_if_needed()
+
+            now = _utcnow()
+            entry = CacheEntry(
+                value=value,
+                created_at=now,
+                last_accessed_at=now,
+                access_count=1,
+                ttl_seconds=ttl_seconds or self._default_ttl,
+            )
+
+            self._cache[key] = entry
+            self._cache.move_to_end(key)
+            self._stats.current_size = len(self._cache)
+
+    def put_by_id(
+        self,
+        memory_type: str,
+        memory_id: UUID | str,
+        value: T,
+        scope: str | None = None,
+        ttl_seconds: float | None = None,
+    ) -> None:
+        """
+        Put a memory by type and ID.
+
+        Args:
+            memory_type: Type of memory
+            memory_id: Memory ID
+            value: Value to cache
+            scope: Optional scope
+            ttl_seconds: Optional TTL override
+        """
+        key = CacheKey(
+            memory_type=memory_type,
+            memory_id=str(memory_id),
+            scope=scope,
+        )
+        self.put(key, value, ttl_seconds)
+
+    def _evict_if_needed(self) -> None:
+        """Evict entries if cache is at capacity."""
+        while len(self._cache) >= self._max_size:
+            # Remove least recently used (first item)
+            if self._cache:
+                self._cache.popitem(last=False)
+                self._stats.evictions += 1
+
+    def invalidate(self, key: CacheKey) -> bool:
+        """
+        Invalidate a specific cache entry.
+
+        Args:
+            key: Cache key to invalidate
+
+        Returns:
+            True if entry was found and removed
+        """
+        with self._lock:
+            if key in self._cache:
+                del self._cache[key]
+                self._stats.current_size = len(self._cache)
+                return True
+            return False
+
+    def invalidate_by_id(
+        self,
+        memory_type: str,
+        memory_id: UUID | str,
+        scope: str | None = None,
+    ) -> bool:
+        """
+        Invalidate a memory by type and ID.
+
+        Args:
+            memory_type: Type of memory
+            memory_id: Memory ID
+            scope: Optional scope
+
+        Returns:
+            True if entry was found and removed
+        """
+        key = CacheKey(
+            memory_type=memory_type,
+            memory_id=str(memory_id),
+            scope=scope,
+        )
+        return self.invalidate(key)
+
+    def invalidate_by_type(self, memory_type: str) -> int:
+        """
+        Invalidate all entries of a memory type.
+
+        Args:
+            memory_type: Type of memory to invalidate
+
+        Returns:
+            Number of entries invalidated
+        """
+        with self._lock:
+            keys_to_remove = [
+                k for k in self._cache.keys() if k.memory_type == memory_type
+            ]
+            for key in keys_to_remove:
+                del self._cache[key]
+
+            self._stats.current_size = len(self._cache)
+            return len(keys_to_remove)
+
+    def invalidate_by_scope(self, scope: str) -> int:
+        """
+        Invalidate all entries in a scope.
+
+        Args:
+            scope: Scope to invalidate (e.g., project_id)
+
+        Returns:
+            Number of entries invalidated
+        """
+        with self._lock:
+            keys_to_remove = [k for k in self._cache.keys() if k.scope == scope]
+            for key in keys_to_remove:
+                del self._cache[key]
+
+            self._stats.current_size = len(self._cache)
+            return len(keys_to_remove)
+
+    def invalidate_pattern(self, pattern: str) -> int:
+        """
+        Invalidate entries matching a pattern.
+
+        Pattern can include * as wildcard.
+
+        Args:
+            pattern: Pattern to match (e.g., "episodic:*")
+
+        Returns:
+            Number of entries invalidated
+        """
+        import fnmatch
+
+        with self._lock:
+            keys_to_remove = [
+                k for k in self._cache.keys() if fnmatch.fnmatch(str(k), pattern)
+            ]
+            for key in keys_to_remove:
+                del self._cache[key]
+
+            self._stats.current_size = len(self._cache)
+            return len(keys_to_remove)
+
+    def clear(self) -> int:
+        """
+        Clear all cache entries.
+
+        Returns:
+            Number of entries cleared
+        """
+        with self._lock:
+            count = len(self._cache)
+            self._cache.clear()
+            self._stats.current_size = 0
+            logger.info(f"Cleared {count} entries from hot cache")
+            return count
+
+    def cleanup_expired(self) -> int:
+        """
+        Remove all expired entries.
+
+        Returns:
+            Number of entries removed
+        """
+        with self._lock:
+            keys_to_remove = [
+                k for k, v in self._cache.items() if v.is_expired()
+            ]
+            for key in keys_to_remove:
+                del self._cache[key]
+                self._stats.expirations += 1
+
+            self._stats.current_size = len(self._cache)
+
+            if keys_to_remove:
+                logger.debug(f"Cleaned up {len(keys_to_remove)} expired entries")
+
+            return len(keys_to_remove)
+
+    def get_hot_memories(self, limit: int = 10) -> list[tuple[CacheKey, int]]:
+        """
+        Get the most frequently accessed memories.
+
+        Args:
+            limit: Maximum number of memories to return
+
+        Returns:
+            List of (key, access_count) tuples sorted by access count
+        """
+        with self._lock:
+            entries = [
+                (k, v.access_count)
+                for k, v in self._cache.items()
+                if not v.is_expired()
+            ]
+            entries.sort(key=lambda x: x[1], reverse=True)
+            return entries[:limit]
+
+    def get_stats(self) -> HotCacheStats:
+        """Get cache statistics."""
+        with self._lock:
+            self._stats.current_size = len(self._cache)
+            return self._stats
+
+    def reset_stats(self) -> None:
+        """Reset cache statistics."""
+        with self._lock:
+            self._stats = HotCacheStats(
+                max_size=self._max_size,
+                current_size=len(self._cache),
+            )
+
+    @property
+    def size(self) -> int:
+        """Get current cache size."""
+        return len(self._cache)
+
+    @property
+    def max_size(self) -> int:
+        """Get maximum cache size."""
+        return self._max_size
+
+
+# Factory function for typed caches
+def create_hot_cache(
+    max_size: int = 10000,
+    default_ttl_seconds: float = 300.0,
+) -> HotMemoryCache[Any]:
+    """
+    Create a hot memory cache.
+
+    Args:
+        max_size: Maximum number of entries
+        default_ttl_seconds: Default TTL for entries
+
+    Returns:
+        Configured HotMemoryCache instance
+    """
+    return HotMemoryCache(
+        max_size=max_size,
+        default_ttl_seconds=default_ttl_seconds,
+    )

backend/app/services/memory/config.py

@@ -0,0 +1,410 @@
+"""
+Memory System Configuration.
+
+Provides Pydantic settings for the Agent Memory System,
+including storage backends, capacity limits, and consolidation policies.
+"""
+
+import threading
+from functools import lru_cache
+from typing import Any
+
+from pydantic import Field, field_validator, model_validator
+from pydantic_settings import BaseSettings
+
+
+class MemorySettings(BaseSettings):
+    """
+    Configuration for the Agent Memory System.
+
+    All settings can be overridden via environment variables
+    with the MEM_ prefix.
+    """
+
+    # Working Memory Settings
+    working_memory_backend: str = Field(
+        default="redis",
+        description="Backend for working memory: 'redis' or 'memory'",
+    )
+    working_memory_default_ttl_seconds: int = Field(
+        default=3600,
+        ge=60,
+        le=86400,
+        description="Default TTL for working memory items (1 hour default)",
+    )
+    working_memory_max_items_per_session: int = Field(
+        default=1000,
+        ge=100,
+        le=100000,
+        description="Maximum items per session in working memory",
+    )
+    working_memory_max_value_size_bytes: int = Field(
+        default=1048576,  # 1MB
+        ge=1024,
+        le=104857600,  # 100MB
+        description="Maximum size of a single value in working memory",
+    )
+    working_memory_checkpoint_enabled: bool = Field(
+        default=True,
+        description="Enable checkpointing for working memory recovery",
+    )
+
+    # Redis Settings (for working memory)
+    redis_url: str = Field(
+        default="redis://localhost:6379/0",
+        description="Redis connection URL",
+    )
+    redis_prefix: str = Field(
+        default="mem",
+        description="Redis key prefix for memory items",
+    )
+    redis_connection_timeout_seconds: int = Field(
+        default=5,
+        ge=1,
+        le=60,
+        description="Redis connection timeout",
+    )
+
+    # Episodic Memory Settings
+    episodic_max_episodes_per_project: int = Field(
+        default=10000,
+        ge=100,
+        le=1000000,
+        description="Maximum episodes to retain per project",
+    )
+    episodic_default_importance: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description="Default importance score for new episodes",
+    )
+    episodic_retention_days: int = Field(
+        default=365,
+        ge=7,
+        le=3650,
+        description="Days to retain episodes before archival",
+    )
+
+    # Semantic Memory Settings
+    semantic_max_facts_per_project: int = Field(
+        default=50000,
+        ge=1000,
+        le=10000000,
+        description="Maximum facts to retain per project",
+    )
+    semantic_confidence_decay_days: int = Field(
+        default=90,
+        ge=7,
+        le=365,
+        description="Days until confidence decays by 50%",
+    )
+    semantic_min_confidence: float = Field(
+        default=0.1,
+        ge=0.0,
+        le=1.0,
+        description="Minimum confidence before fact is pruned",
+    )
+
+    # Procedural Memory Settings
+    procedural_max_procedures_per_project: int = Field(
+        default=1000,
+        ge=10,
+        le=100000,
+        description="Maximum procedures per project",
+    )
+    procedural_min_success_rate: float = Field(
+        default=0.3,
+        ge=0.0,
+        le=1.0,
+        description="Minimum success rate before procedure is pruned",
+    )
+    procedural_min_uses_before_suggest: int = Field(
+        default=3,
+        ge=1,
+        le=100,
+        description="Minimum uses before procedure is suggested",
+    )
+
+    # Embedding Settings
+    embedding_model: str = Field(
+        default="text-embedding-3-small",
+        description="Model to use for embeddings",
+    )
+    embedding_dimensions: int = Field(
+        default=1536,
+        ge=256,
+        le=4096,
+        description="Embedding vector dimensions",
+    )
+    embedding_batch_size: int = Field(
+        default=100,
+        ge=1,
+        le=1000,
+        description="Batch size for embedding generation",
+    )
+    embedding_cache_enabled: bool = Field(
+        default=True,
+        description="Enable caching of embeddings",
+    )
+
+    # Retrieval Settings
+    retrieval_default_limit: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+        description="Default limit for retrieval queries",
+    )
+    retrieval_max_limit: int = Field(
+        default=100,
+        ge=10,
+        le=1000,
+        description="Maximum limit for retrieval queries",
+    )
+    retrieval_min_similarity: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description="Minimum similarity score for retrieval",
+    )
+
+    # Consolidation Settings
+    consolidation_enabled: bool = Field(
+        default=True,
+        description="Enable automatic memory consolidation",
+    )
+    consolidation_batch_size: int = Field(
+        default=100,
+        ge=10,
+        le=1000,
+        description="Batch size for consolidation jobs",
+    )
+    consolidation_schedule_cron: str = Field(
+        default="0 3 * * *",
+        description="Cron expression for nightly consolidation (3 AM)",
+    )
+    consolidation_working_to_episodic_delay_minutes: int = Field(
+        default=30,
+        ge=5,
+        le=1440,
+        description="Minutes after session end before consolidating to episodic",
+    )
+
+    # Pruning Settings
+    pruning_enabled: bool = Field(
+        default=True,
+        description="Enable automatic memory pruning",
+    )
+    pruning_min_age_days: int = Field(
+        default=7,
+        ge=1,
+        le=365,
+        description="Minimum age before memory can be pruned",
+    )
+    pruning_importance_threshold: float = Field(
+        default=0.2,
+        ge=0.0,
+        le=1.0,
+        description="Importance threshold below which memory can be pruned",
+    )
+
+    # Caching Settings
+    cache_enabled: bool = Field(
+        default=True,
+        description="Enable caching for memory retrieval",
+    )
+    cache_ttl_seconds: int = Field(
+        default=300,
+        ge=10,
+        le=3600,
+        description="Cache TTL for retrieval results",
+    )
+    cache_max_items: int = Field(
+        default=10000,
+        ge=100,
+        le=1000000,
+        description="Maximum items in memory cache",
+    )
+
+    # Performance Settings
+    max_retrieval_time_ms: int = Field(
+        default=100,
+        ge=10,
+        le=5000,
+        description="Target maximum retrieval time in milliseconds",
+    )
+    parallel_retrieval: bool = Field(
+        default=True,
+        description="Enable parallel retrieval from multiple memory types",
+    )
+    max_parallel_retrievals: int = Field(
+        default=4,
+        ge=1,
+        le=10,
+        description="Maximum concurrent retrieval operations",
+    )
+
+    @field_validator("working_memory_backend")
+    @classmethod
+    def validate_backend(cls, v: str) -> str:
+        """Validate working memory backend."""
+        valid_backends = {"redis", "memory"}
+        if v not in valid_backends:
+            raise ValueError(f"backend must be one of: {valid_backends}")
+        return v
+
+    @field_validator("embedding_model")
+    @classmethod
+    def validate_embedding_model(cls, v: str) -> str:
+        """Validate embedding model name."""
+        valid_models = {
+            "text-embedding-3-small",
+            "text-embedding-3-large",
+            "text-embedding-ada-002",
+        }
+        if v not in valid_models:
+            raise ValueError(f"embedding_model must be one of: {valid_models}")
+        return v
+
+    @model_validator(mode="after")
+    def validate_limits(self) -> "MemorySettings":
+        """Validate that limits are consistent."""
+        if self.retrieval_default_limit > self.retrieval_max_limit:
+            raise ValueError(
+                f"retrieval_default_limit ({self.retrieval_default_limit}) "
+                f"cannot exceed retrieval_max_limit ({self.retrieval_max_limit})"
+            )
+        return self
+
+    def get_working_memory_config(self) -> dict[str, Any]:
+        """Get working memory configuration as a dictionary."""
+        return {
+            "backend": self.working_memory_backend,
+            "default_ttl_seconds": self.working_memory_default_ttl_seconds,
+            "max_items_per_session": self.working_memory_max_items_per_session,
+            "max_value_size_bytes": self.working_memory_max_value_size_bytes,
+            "checkpoint_enabled": self.working_memory_checkpoint_enabled,
+        }
+
+    def get_redis_config(self) -> dict[str, Any]:
+        """Get Redis configuration as a dictionary."""
+        return {
+            "url": self.redis_url,
+            "prefix": self.redis_prefix,
+            "connection_timeout_seconds": self.redis_connection_timeout_seconds,
+        }
+
+    def get_embedding_config(self) -> dict[str, Any]:
+        """Get embedding configuration as a dictionary."""
+        return {
+            "model": self.embedding_model,
+            "dimensions": self.embedding_dimensions,
+            "batch_size": self.embedding_batch_size,
+            "cache_enabled": self.embedding_cache_enabled,
+        }
+
+    def get_consolidation_config(self) -> dict[str, Any]:
+        """Get consolidation configuration as a dictionary."""
+        return {
+            "enabled": self.consolidation_enabled,
+            "batch_size": self.consolidation_batch_size,
+            "schedule_cron": self.consolidation_schedule_cron,
+            "working_to_episodic_delay_minutes": (
+                self.consolidation_working_to_episodic_delay_minutes
+            ),
+        }
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert settings to dictionary for logging/debugging."""
+        return {
+            "working_memory": self.get_working_memory_config(),
+            "redis": self.get_redis_config(),
+            "episodic": {
+                "max_episodes_per_project": self.episodic_max_episodes_per_project,
+                "default_importance": self.episodic_default_importance,
+                "retention_days": self.episodic_retention_days,
+            },
+            "semantic": {
+                "max_facts_per_project": self.semantic_max_facts_per_project,
+                "confidence_decay_days": self.semantic_confidence_decay_days,
+                "min_confidence": self.semantic_min_confidence,
+            },
+            "procedural": {
+                "max_procedures_per_project": self.procedural_max_procedures_per_project,
+                "min_success_rate": self.procedural_min_success_rate,
+                "min_uses_before_suggest": self.procedural_min_uses_before_suggest,
+            },
+            "embedding": self.get_embedding_config(),
+            "retrieval": {
+                "default_limit": self.retrieval_default_limit,
+                "max_limit": self.retrieval_max_limit,
+                "min_similarity": self.retrieval_min_similarity,
+            },
+            "consolidation": self.get_consolidation_config(),
+            "pruning": {
+                "enabled": self.pruning_enabled,
+                "min_age_days": self.pruning_min_age_days,
+                "importance_threshold": self.pruning_importance_threshold,
+            },
+            "cache": {
+                "enabled": self.cache_enabled,
+                "ttl_seconds": self.cache_ttl_seconds,
+                "max_items": self.cache_max_items,
+            },
+            "performance": {
+                "max_retrieval_time_ms": self.max_retrieval_time_ms,
+                "parallel_retrieval": self.parallel_retrieval,
+                "max_parallel_retrievals": self.max_parallel_retrievals,
+            },
+        }
+
+    model_config = {
+        "env_prefix": "MEM_",
+        "env_file": ".env",
+        "env_file_encoding": "utf-8",
+        "case_sensitive": False,
+        "extra": "ignore",
+    }
+
+
+# Thread-safe singleton pattern
+_settings: MemorySettings | None = None
+_settings_lock = threading.Lock()
+
+
+def get_memory_settings() -> MemorySettings:
+    """
+    Get the global MemorySettings instance.
+
+    Thread-safe with double-checked locking pattern.
+
+    Returns:
+        MemorySettings instance
+    """
+    global _settings
+    if _settings is None:
+        with _settings_lock:
+            if _settings is None:
+                _settings = MemorySettings()
+    return _settings
+
+
+def reset_memory_settings() -> None:
+    """
+    Reset the global settings instance.
+
+    Primarily used for testing.
+    """
+    global _settings
+    with _settings_lock:
+        _settings = None
+
+
+@lru_cache(maxsize=1)
+def get_default_settings() -> MemorySettings:
+    """
+    Get default settings (cached).
+
+    Use this for read-only access to defaults.
+    For mutable access, use get_memory_settings().
+    """
+    return MemorySettings()

backend/app/services/memory/consolidation/__init__.py

@@ -0,0 +1,29 @@
+# app/services/memory/consolidation/__init__.py
+"""
+Memory Consolidation.
+
+Transfers and extracts knowledge between memory tiers:
+- Working -> Episodic (session end)
+- Episodic -> Semantic (learn facts)
+- Episodic -> Procedural (learn procedures)
+
+Also handles memory pruning and importance-based retention.
+"""
+
+from .service import (
+    ConsolidationConfig,
+    ConsolidationResult,
+    MemoryConsolidationService,
+    NightlyConsolidationResult,
+    SessionConsolidationResult,
+    get_consolidation_service,
+)
+
+__all__ = [
+    "ConsolidationConfig",
+    "ConsolidationResult",
+    "MemoryConsolidationService",
+    "NightlyConsolidationResult",
+    "SessionConsolidationResult",
+    "get_consolidation_service",
+]

backend/app/services/memory/consolidation/service.py

@@ -0,0 +1,918 @@
+# app/services/memory/consolidation/service.py
+"""
+Memory Consolidation Service.
+
+Transfers and extracts knowledge between memory tiers:
+- Working -> Episodic (session end)
+- Episodic -> Semantic (learn facts)
+- Episodic -> Procedural (learn procedures)
+
+Also handles memory pruning and importance-based retention.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.services.memory.episodic.memory import EpisodicMemory
+from app.services.memory.procedural.memory import ProceduralMemory
+from app.services.memory.semantic.extraction import FactExtractor, get_fact_extractor
+from app.services.memory.semantic.memory import SemanticMemory
+from app.services.memory.types import (
+    Episode,
+    EpisodeCreate,
+    Outcome,
+    ProcedureCreate,
+    TaskState,
+)
+from app.services.memory.working.memory import WorkingMemory
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ConsolidationConfig:
+    """Configuration for memory consolidation."""
+
+    # Working -> Episodic thresholds
+    min_steps_for_episode: int = 2
+    min_duration_seconds: float = 5.0
+
+    # Episodic -> Semantic thresholds
+    min_confidence_for_fact: float = 0.6
+    max_facts_per_episode: int = 10
+    reinforce_existing_facts: bool = True
+
+    # Episodic -> Procedural thresholds
+    min_episodes_for_procedure: int = 3
+    min_success_rate_for_procedure: float = 0.7
+    min_steps_for_procedure: int = 2
+
+    # Pruning thresholds
+    max_episode_age_days: int = 90
+    min_importance_to_keep: float = 0.2
+    keep_all_failures: bool = True
+    keep_all_with_lessons: bool = True
+
+    # Batch sizes
+    batch_size: int = 100
+
+
+@dataclass
+class ConsolidationResult:
+    """Result of a consolidation operation."""
+
+    source_type: str
+    target_type: str
+    items_processed: int = 0
+    items_created: int = 0
+    items_updated: int = 0
+    items_skipped: int = 0
+    items_pruned: int = 0
+    errors: list[str] = field(default_factory=list)
+    duration_seconds: float = 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "source_type": self.source_type,
+            "target_type": self.target_type,
+            "items_processed": self.items_processed,
+            "items_created": self.items_created,
+            "items_updated": self.items_updated,
+            "items_skipped": self.items_skipped,
+            "items_pruned": self.items_pruned,
+            "errors": self.errors,
+            "duration_seconds": self.duration_seconds,
+        }
+
+
+@dataclass
+class SessionConsolidationResult:
+    """Result of consolidating a session's working memory to episodic."""
+
+    session_id: str
+    episode_created: bool = False
+    episode_id: UUID | None = None
+    scratchpad_entries: int = 0
+    variables_captured: int = 0
+    error: str | None = None
+
+
+@dataclass
+class NightlyConsolidationResult:
+    """Result of nightly consolidation run."""
+
+    started_at: datetime
+    completed_at: datetime | None = None
+    episodic_to_semantic: ConsolidationResult | None = None
+    episodic_to_procedural: ConsolidationResult | None = None
+    pruning: ConsolidationResult | None = None
+    total_episodes_processed: int = 0
+    total_facts_created: int = 0
+    total_procedures_created: int = 0
+    total_pruned: int = 0
+    errors: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "started_at": self.started_at.isoformat(),
+            "completed_at": self.completed_at.isoformat()
+            if self.completed_at
+            else None,
+            "episodic_to_semantic": (
+                self.episodic_to_semantic.to_dict()
+                if self.episodic_to_semantic
+                else None
+            ),
+            "episodic_to_procedural": (
+                self.episodic_to_procedural.to_dict()
+                if self.episodic_to_procedural
+                else None
+            ),
+            "pruning": self.pruning.to_dict() if self.pruning else None,
+            "total_episodes_processed": self.total_episodes_processed,
+            "total_facts_created": self.total_facts_created,
+            "total_procedures_created": self.total_procedures_created,
+            "total_pruned": self.total_pruned,
+            "errors": self.errors,
+        }
+
+
+class MemoryConsolidationService:
+    """
+    Service for consolidating memories between tiers.
+
+    Responsibilities:
+    - Transfer working memory to episodic at session end
+    - Extract facts from episodes to semantic memory
+    - Learn procedures from successful episode patterns
+    - Prune old/low-value memories
+    """
+
+    def __init__(
+        self,
+        session: AsyncSession,
+        config: ConsolidationConfig | None = None,
+        embedding_generator: Any | None = None,
+    ) -> None:
+        """
+        Initialize consolidation service.
+
+        Args:
+            session: Database session
+            config: Consolidation configuration
+            embedding_generator: Optional embedding generator
+        """
+        self._session = session
+        self._config = config or ConsolidationConfig()
+        self._embedding_generator = embedding_generator
+        self._fact_extractor: FactExtractor = get_fact_extractor()
+
+        # Memory services (lazy initialized)
+        self._episodic: EpisodicMemory | None = None
+        self._semantic: SemanticMemory | None = None
+        self._procedural: ProceduralMemory | None = None
+
+    async def _get_episodic(self) -> EpisodicMemory:
+        """Get or create episodic memory service."""
+        if self._episodic is None:
+            self._episodic = await EpisodicMemory.create(
+                self._session, self._embedding_generator
+            )
+        return self._episodic
+
+    async def _get_semantic(self) -> SemanticMemory:
+        """Get or create semantic memory service."""
+        if self._semantic is None:
+            self._semantic = await SemanticMemory.create(
+                self._session, self._embedding_generator
+            )
+        return self._semantic
+
+    async def _get_procedural(self) -> ProceduralMemory:
+        """Get or create procedural memory service."""
+        if self._procedural is None:
+            self._procedural = await ProceduralMemory.create(
+                self._session, self._embedding_generator
+            )
+        return self._procedural
+
+    # =========================================================================
+    # Working -> Episodic Consolidation
+    # =========================================================================
+
+    async def consolidate_session(
+        self,
+        working_memory: WorkingMemory,
+        project_id: UUID,
+        session_id: str,
+        task_type: str = "session_task",
+        agent_instance_id: UUID | None = None,
+        agent_type_id: UUID | None = None,
+    ) -> SessionConsolidationResult:
+        """
+        Consolidate a session's working memory to episodic memory.
+
+        Called at session end to transfer relevant session data
+        into a persistent episode.
+
+        Args:
+            working_memory: The session's working memory
+            project_id: Project ID
+            session_id: Session ID
+            task_type: Type of task performed
+            agent_instance_id: Optional agent instance
+            agent_type_id: Optional agent type
+
+        Returns:
+            SessionConsolidationResult with outcome details
+        """
+        result = SessionConsolidationResult(session_id=session_id)
+
+        try:
+            # Get task state
+            task_state = await working_memory.get_task_state()
+
+            # Check if there's enough content to consolidate
+            if not self._should_consolidate_session(task_state):
+                logger.debug(
+                    f"Skipping consolidation for session {session_id}: insufficient content"
+                )
+                return result
+
+            # Gather scratchpad entries
+            scratchpad = await working_memory.get_scratchpad()
+            result.scratchpad_entries = len(scratchpad)
+
+            # Gather user variables
+            all_data = await working_memory.get_all()
+            result.variables_captured = len(all_data)
+
+            # Determine outcome
+            outcome = self._determine_session_outcome(task_state)
+
+            # Build actions from scratchpad and variables
+            actions = self._build_actions_from_session(scratchpad, all_data, task_state)
+
+            # Build context summary
+            context_summary = self._build_context_summary(task_state, all_data)
+
+            # Extract lessons learned
+            lessons = self._extract_session_lessons(task_state, outcome)
+
+            # Calculate importance
+            importance = self._calculate_session_importance(
+                task_state, outcome, actions
+            )
+
+            # Create episode
+            episode_data = EpisodeCreate(
+                project_id=project_id,
+                session_id=session_id,
+                task_type=task_type,
+                task_description=task_state.description
+                if task_state
+                else "Session task",
+                actions=actions,
+                context_summary=context_summary,
+                outcome=outcome,
+                outcome_details=task_state.status if task_state else "",
+                duration_seconds=self._calculate_duration(task_state),
+                tokens_used=0,  # Would need to track this in working memory
+                lessons_learned=lessons,
+                importance_score=importance,
+                agent_instance_id=agent_instance_id,
+                agent_type_id=agent_type_id,
+            )
+
+            episodic = await self._get_episodic()
+            episode = await episodic.record_episode(episode_data)
+
+            result.episode_created = True
+            result.episode_id = episode.id
+
+            logger.info(
+                f"Consolidated session {session_id} to episode {episode.id} "
+                f"({len(actions)} actions, outcome={outcome.value})"
+            )
+
+        except Exception as e:
+            result.error = str(e)
+            logger.exception(f"Failed to consolidate session {session_id}")
+
+        return result
+
+    def _should_consolidate_session(self, task_state: TaskState | None) -> bool:
+        """Check if session has enough content to consolidate."""
+        if task_state is None:
+            return False
+
+        # Check minimum steps
+        if task_state.current_step < self._config.min_steps_for_episode:
+            return False
+
+        return True
+
+    def _determine_session_outcome(self, task_state: TaskState | None) -> Outcome:
+        """Determine outcome from task state."""
+        if task_state is None:
+            return Outcome.PARTIAL
+
+        status = task_state.status.lower() if task_state.status else ""
+        progress = task_state.progress_percent
+
+        if "success" in status or "complete" in status or progress >= 100:
+            return Outcome.SUCCESS
+        if "fail" in status or "error" in status:
+            return Outcome.FAILURE
+        if progress >= 50:
+            return Outcome.PARTIAL
+        return Outcome.FAILURE
+
+    def _build_actions_from_session(
+        self,
+        scratchpad: list[str],
+        variables: dict[str, Any],
+        task_state: TaskState | None,
+    ) -> list[dict[str, Any]]:
+        """Build action list from session data."""
+        actions: list[dict[str, Any]] = []
+
+        # Add scratchpad entries as actions
+        for i, entry in enumerate(scratchpad):
+            actions.append(
+                {
+                    "step": i + 1,
+                    "type": "reasoning",
+                    "content": entry[:500],  # Truncate long entries
+                }
+            )
+
+        # Add final state
+        if task_state:
+            actions.append(
+                {
+                    "step": len(scratchpad) + 1,
+                    "type": "final_state",
+                    "current_step": task_state.current_step,
+                    "total_steps": task_state.total_steps,
+                    "progress": task_state.progress_percent,
+                    "status": task_state.status,
+                }
+            )
+
+        return actions
+
+    def _build_context_summary(
+        self,
+        task_state: TaskState | None,
+        variables: dict[str, Any],
+    ) -> str:
+        """Build context summary from session data."""
+        parts = []
+
+        if task_state:
+            parts.append(f"Task: {task_state.description}")
+            parts.append(f"Progress: {task_state.progress_percent:.1f}%")
+            parts.append(f"Steps: {task_state.current_step}/{task_state.total_steps}")
+
+        # Include key variables
+        key_vars = {k: v for k, v in variables.items() if len(str(v)) < 100}
+        if key_vars:
+            var_str = ", ".join(f"{k}={v}" for k, v in list(key_vars.items())[:5])
+            parts.append(f"Variables: {var_str}")
+
+        return "; ".join(parts) if parts else "Session completed"
+
+    def _extract_session_lessons(
+        self,
+        task_state: TaskState | None,
+        outcome: Outcome,
+    ) -> list[str]:
+        """Extract lessons from session."""
+        lessons: list[str] = []
+
+        if task_state and task_state.status:
+            if outcome == Outcome.FAILURE:
+                lessons.append(
+                    f"Task failed at step {task_state.current_step}: {task_state.status}"
+                )
+            elif outcome == Outcome.SUCCESS:
+                lessons.append(
+                    f"Successfully completed in {task_state.current_step} steps"
+                )
+
+        return lessons
+
+    def _calculate_session_importance(
+        self,
+        task_state: TaskState | None,
+        outcome: Outcome,
+        actions: list[dict[str, Any]],
+    ) -> float:
+        """Calculate importance score for session."""
+        score = 0.5  # Base score
+
+        # Failures are important to learn from
+        if outcome == Outcome.FAILURE:
+            score += 0.3
+
+        # Many steps means complex task
+        if task_state and task_state.total_steps >= 5:
+            score += 0.1
+
+        # Many actions means detailed reasoning
+        if len(actions) >= 5:
+            score += 0.1
+
+        return min(1.0, score)
+
+    def _calculate_duration(self, task_state: TaskState | None) -> float:
+        """Calculate session duration."""
+        if task_state is None:
+            return 0.0
+
+        if task_state.started_at and task_state.updated_at:
+            delta = task_state.updated_at - task_state.started_at
+            return delta.total_seconds()
+
+        return 0.0
+
+    # =========================================================================
+    # Episodic -> Semantic Consolidation
+    # =========================================================================
+
+    async def consolidate_episodes_to_facts(
+        self,
+        project_id: UUID,
+        since: datetime | None = None,
+        limit: int | None = None,
+    ) -> ConsolidationResult:
+        """
+        Extract facts from episodic memories to semantic memory.
+
+        Args:
+            project_id: Project to consolidate
+            since: Only process episodes since this time
+            limit: Maximum episodes to process
+
+        Returns:
+            ConsolidationResult with extraction statistics
+        """
+        start_time = datetime.now(UTC)
+        result = ConsolidationResult(
+            source_type="episodic",
+            target_type="semantic",
+        )
+
+        try:
+            episodic = await self._get_episodic()
+            semantic = await self._get_semantic()
+
+            # Get episodes to process
+            since_time = since or datetime.now(UTC) - timedelta(days=1)
+            episodes = await episodic.get_recent(
+                project_id,
+                limit=limit or self._config.batch_size,
+                since=since_time,
+            )
+
+            for episode in episodes:
+                result.items_processed += 1
+
+                try:
+                    # Extract facts using the extractor
+                    extracted_facts = self._fact_extractor.extract_from_episode(episode)
+
+                    for extracted_fact in extracted_facts:
+                        if (
+                            extracted_fact.confidence
+                            < self._config.min_confidence_for_fact
+                        ):
+                            result.items_skipped += 1
+                            continue
+
+                        # Create fact (store_fact handles deduplication/reinforcement)
+                        fact_create = extracted_fact.to_fact_create(
+                            project_id=project_id,
+                            source_episode_ids=[episode.id],
+                        )
+
+                        # store_fact automatically reinforces if fact already exists
+                        fact = await semantic.store_fact(fact_create)
+
+                        # Check if this was a new fact or reinforced existing
+                        if fact.reinforcement_count == 1:
+                            result.items_created += 1
+                        else:
+                            result.items_updated += 1
+
+                except Exception as e:
+                    result.errors.append(f"Episode {episode.id}: {e}")
+                    logger.warning(
+                        f"Failed to extract facts from episode {episode.id}: {e}"
+                    )
+
+        except Exception as e:
+            result.errors.append(f"Consolidation failed: {e}")
+            logger.exception("Failed episodic -> semantic consolidation")
+
+        result.duration_seconds = (datetime.now(UTC) - start_time).total_seconds()
+
+        logger.info(
+            f"Episodic -> Semantic consolidation: "
+            f"{result.items_processed} processed, "
+            f"{result.items_created} created, "
+            f"{result.items_updated} reinforced"
+        )
+
+        return result
+
+    # =========================================================================
+    # Episodic -> Procedural Consolidation
+    # =========================================================================
+
+    async def consolidate_episodes_to_procedures(
+        self,
+        project_id: UUID,
+        agent_type_id: UUID | None = None,
+        since: datetime | None = None,
+    ) -> ConsolidationResult:
+        """
+        Learn procedures from patterns in episodic memories.
+
+        Identifies recurring successful patterns and creates/updates
+        procedures to capture them.
+
+        Args:
+            project_id: Project to consolidate
+            agent_type_id: Optional filter by agent type
+            since: Only process episodes since this time
+
+        Returns:
+            ConsolidationResult with procedure statistics
+        """
+        start_time = datetime.now(UTC)
+        result = ConsolidationResult(
+            source_type="episodic",
+            target_type="procedural",
+        )
+
+        try:
+            episodic = await self._get_episodic()
+            procedural = await self._get_procedural()
+
+            # Get successful episodes
+            since_time = since or datetime.now(UTC) - timedelta(days=7)
+            episodes = await episodic.get_by_outcome(
+                project_id,
+                outcome=Outcome.SUCCESS,
+                limit=self._config.batch_size,
+                agent_instance_id=None,  # Get all agent instances
+            )
+
+            # Group by task type
+            task_groups: dict[str, list[Episode]] = {}
+            for episode in episodes:
+                if episode.occurred_at >= since_time:
+                    if episode.task_type not in task_groups:
+                        task_groups[episode.task_type] = []
+                    task_groups[episode.task_type].append(episode)
+
+            result.items_processed = len(episodes)
+
+            # Process each task type group
+            for task_type, group in task_groups.items():
+                if len(group) < self._config.min_episodes_for_procedure:
+                    result.items_skipped += len(group)
+                    continue
+
+                try:
+                    procedure_result = await self._learn_procedure_from_episodes(
+                        procedural,
+                        project_id,
+                        agent_type_id,
+                        task_type,
+                        group,
+                    )
+
+                    if procedure_result == "created":
+                        result.items_created += 1
+                    elif procedure_result == "updated":
+                        result.items_updated += 1
+                    else:
+                        result.items_skipped += 1
+
+                except Exception as e:
+                    result.errors.append(f"Task type '{task_type}': {e}")
+                    logger.warning(f"Failed to learn procedure for '{task_type}': {e}")
+
+        except Exception as e:
+            result.errors.append(f"Consolidation failed: {e}")
+            logger.exception("Failed episodic -> procedural consolidation")
+
+        result.duration_seconds = (datetime.now(UTC) - start_time).total_seconds()
+
+        logger.info(
+            f"Episodic -> Procedural consolidation: "
+            f"{result.items_processed} processed, "
+            f"{result.items_created} created, "
+            f"{result.items_updated} updated"
+        )
+
+        return result
+
+    async def _learn_procedure_from_episodes(
+        self,
+        procedural: ProceduralMemory,
+        project_id: UUID,
+        agent_type_id: UUID | None,
+        task_type: str,
+        episodes: list[Episode],
+    ) -> str:
+        """Learn or update a procedure from a set of episodes."""
+        # Calculate success rate for this pattern
+        success_count = sum(1 for e in episodes if e.outcome == Outcome.SUCCESS)
+        total_count = len(episodes)
+        success_rate = success_count / total_count if total_count > 0 else 0
+
+        if success_rate < self._config.min_success_rate_for_procedure:
+            return "skipped"
+
+        # Extract common steps from episodes
+        steps = self._extract_common_steps(episodes)
+
+        if len(steps) < self._config.min_steps_for_procedure:
+            return "skipped"
+
+        # Check for existing procedure
+        matching = await procedural.find_matching(
+            context=task_type,
+            project_id=project_id,
+            agent_type_id=agent_type_id,
+            limit=1,
+        )
+
+        if matching:
+            # Update existing procedure with new success
+            await procedural.record_outcome(
+                matching[0].id,
+                success=True,
+            )
+            return "updated"
+        else:
+            # Create new procedure
+            # Note: success_count starts at 1 in record_procedure
+            procedure_data = ProcedureCreate(
+                project_id=project_id,
+                agent_type_id=agent_type_id,
+                name=f"Procedure for {task_type}",
+                trigger_pattern=task_type,
+                steps=steps,
+            )
+            await procedural.record_procedure(procedure_data)
+            return "created"
+
+    def _extract_common_steps(self, episodes: list[Episode]) -> list[dict[str, Any]]:
+        """Extract common action steps from multiple episodes."""
+        # Simple heuristic: take the steps from the most successful episode
+        # with the most detailed actions
+
+        best_episode = max(
+            episodes,
+            key=lambda e: (
+                e.outcome == Outcome.SUCCESS,
+                len(e.actions),
+                e.importance_score,
+            ),
+        )
+
+        steps: list[dict[str, Any]] = []
+        for i, action in enumerate(best_episode.actions):
+            step = {
+                "order": i + 1,
+                "action": action.get("type", "action"),
+                "description": action.get("content", str(action))[:500],
+                "parameters": action,
+            }
+            steps.append(step)
+
+        return steps
+
+    # =========================================================================
+    # Memory Pruning
+    # =========================================================================
+
+    async def prune_old_episodes(
+        self,
+        project_id: UUID,
+        max_age_days: int | None = None,
+        min_importance: float | None = None,
+    ) -> ConsolidationResult:
+        """
+        Prune old, low-value episodes.
+
+        Args:
+            project_id: Project to prune
+            max_age_days: Maximum age in days (default from config)
+            min_importance: Minimum importance to keep (default from config)
+
+        Returns:
+            ConsolidationResult with pruning statistics
+        """
+        start_time = datetime.now(UTC)
+        result = ConsolidationResult(
+            source_type="episodic",
+            target_type="pruned",
+        )
+
+        max_age = max_age_days or self._config.max_episode_age_days
+        min_imp = min_importance or self._config.min_importance_to_keep
+        cutoff_date = datetime.now(UTC) - timedelta(days=max_age)
+
+        try:
+            episodic = await self._get_episodic()
+
+            # Get old episodes
+            # Note: In production, this would use a more efficient query
+            all_episodes = await episodic.get_recent(
+                project_id,
+                limit=self._config.batch_size * 10,
+                since=cutoff_date - timedelta(days=365),  # Search past year
+            )
+
+            for episode in all_episodes:
+                result.items_processed += 1
+
+                # Check if should be pruned
+                if not self._should_prune_episode(episode, cutoff_date, min_imp):
+                    result.items_skipped += 1
+                    continue
+
+                try:
+                    deleted = await episodic.delete(episode.id)
+                    if deleted:
+                        result.items_pruned += 1
+                    else:
+                        result.items_skipped += 1
+                except Exception as e:
+                    result.errors.append(f"Episode {episode.id}: {e}")
+
+        except Exception as e:
+            result.errors.append(f"Pruning failed: {e}")
+            logger.exception("Failed episode pruning")
+
+        result.duration_seconds = (datetime.now(UTC) - start_time).total_seconds()
+
+        logger.info(
+            f"Episode pruning: {result.items_processed} processed, "
+            f"{result.items_pruned} pruned"
+        )
+
+        return result
+
+    def _should_prune_episode(
+        self,
+        episode: Episode,
+        cutoff_date: datetime,
+        min_importance: float,
+    ) -> bool:
+        """Determine if an episode should be pruned."""
+        # Keep recent episodes
+        if episode.occurred_at >= cutoff_date:
+            return False
+
+        # Keep failures if configured
+        if self._config.keep_all_failures and episode.outcome == Outcome.FAILURE:
+            return False
+
+        # Keep episodes with lessons if configured
+        if self._config.keep_all_with_lessons and episode.lessons_learned:
+            return False
+
+        # Keep high-importance episodes
+        if episode.importance_score >= min_importance:
+            return False
+
+        return True
+
+    # =========================================================================
+    # Nightly Consolidation
+    # =========================================================================
+
+    async def run_nightly_consolidation(
+        self,
+        project_id: UUID,
+        agent_type_id: UUID | None = None,
+    ) -> NightlyConsolidationResult:
+        """
+        Run full nightly consolidation workflow.
+
+        This includes:
+        1. Extract facts from recent episodes
+        2. Learn procedures from successful patterns
+        3. Prune old, low-value memories
+
+        Args:
+            project_id: Project to consolidate
+            agent_type_id: Optional agent type filter
+
+        Returns:
+            NightlyConsolidationResult with all outcomes
+        """
+        result = NightlyConsolidationResult(started_at=datetime.now(UTC))
+
+        logger.info(f"Starting nightly consolidation for project {project_id}")
+
+        try:
+            # Step 1: Episodic -> Semantic (last 24 hours)
+            since_yesterday = datetime.now(UTC) - timedelta(days=1)
+            result.episodic_to_semantic = await self.consolidate_episodes_to_facts(
+                project_id=project_id,
+                since=since_yesterday,
+            )
+            result.total_facts_created = result.episodic_to_semantic.items_created
+
+            # Step 2: Episodic -> Procedural (last 7 days)
+            since_week = datetime.now(UTC) - timedelta(days=7)
+            result.episodic_to_procedural = (
+                await self.consolidate_episodes_to_procedures(
+                    project_id=project_id,
+                    agent_type_id=agent_type_id,
+                    since=since_week,
+                )
+            )
+            result.total_procedures_created = (
+                result.episodic_to_procedural.items_created
+            )
+
+            # Step 3: Prune old memories
+            result.pruning = await self.prune_old_episodes(project_id=project_id)
+            result.total_pruned = result.pruning.items_pruned
+
+            # Calculate totals
+            result.total_episodes_processed = (
+                result.episodic_to_semantic.items_processed
+                if result.episodic_to_semantic
+                else 0
+            ) + (
+                result.episodic_to_procedural.items_processed
+                if result.episodic_to_procedural
+                else 0
+            )
+
+            # Collect all errors
+            if result.episodic_to_semantic and result.episodic_to_semantic.errors:
+                result.errors.extend(result.episodic_to_semantic.errors)
+            if result.episodic_to_procedural and result.episodic_to_procedural.errors:
+                result.errors.extend(result.episodic_to_procedural.errors)
+            if result.pruning and result.pruning.errors:
+                result.errors.extend(result.pruning.errors)
+
+        except Exception as e:
+            result.errors.append(f"Nightly consolidation failed: {e}")
+            logger.exception("Nightly consolidation failed")
+
+        result.completed_at = datetime.now(UTC)
+
+        duration = (result.completed_at - result.started_at).total_seconds()
+        logger.info(
+            f"Nightly consolidation completed in {duration:.1f}s: "
+            f"{result.total_facts_created} facts, "
+            f"{result.total_procedures_created} procedures, "
+            f"{result.total_pruned} pruned"
+        )
+
+        return result
+
+
+# Singleton instance
+_consolidation_service: MemoryConsolidationService | None = None
+
+
+async def get_consolidation_service(
+    session: AsyncSession,
+    config: ConsolidationConfig | None = None,
+) -> MemoryConsolidationService:
+    """
+    Get or create the memory consolidation service.
+
+    Args:
+        session: Database session
+        config: Optional configuration
+
+    Returns:
+        MemoryConsolidationService instance
+    """
+    global _consolidation_service
+    if _consolidation_service is None:
+        _consolidation_service = MemoryConsolidationService(
+            session=session, config=config
+        )
+    return _consolidation_service

backend/app/services/memory/episodic/__init__.py

@@ -0,0 +1,17 @@
+# app/services/memory/episodic/__init__.py
+"""
+Episodic Memory Package.
+
+Provides experiential memory storage and retrieval for agent learning.
+"""
+
+from .memory import EpisodicMemory
+from .recorder import EpisodeRecorder
+from .retrieval import EpisodeRetriever, RetrievalStrategy
+
+__all__ = [
+    "EpisodeRecorder",
+    "EpisodeRetriever",
+    "EpisodicMemory",
+    "RetrievalStrategy",
+]

backend/app/services/memory/episodic/memory.py

@@ -0,0 +1,490 @@
+# app/services/memory/episodic/memory.py
+"""
+Episodic Memory Implementation.
+
+Provides experiential memory storage and retrieval for agent learning.
+Combines episode recording and retrieval into a unified interface.
+"""
+
+import logging
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.services.memory.types import Episode, EpisodeCreate, Outcome, RetrievalResult
+
+from .recorder import EpisodeRecorder
+from .retrieval import EpisodeRetriever, RetrievalStrategy
+
+logger = logging.getLogger(__name__)
+
+
+class EpisodicMemory:
+    """
+    Episodic Memory Service.
+
+    Provides experiential memory for agent learning:
+    - Record task completions with context
+    - Store failures with error context
+    - Retrieve by semantic similarity
+    - Retrieve by recency, outcome, task type
+    - Track importance scores
+    - Extract lessons learned
+
+    Performance target: <100ms P95 for retrieval
+    """
+
+    def __init__(
+        self,
+        session: AsyncSession,
+        embedding_generator: Any | None = None,
+    ) -> None:
+        """
+        Initialize episodic memory.
+
+        Args:
+            session: Database session
+            embedding_generator: Optional embedding generator for semantic search
+        """
+        self._session = session
+        self._embedding_generator = embedding_generator
+        self._recorder = EpisodeRecorder(session, embedding_generator)
+        self._retriever = EpisodeRetriever(session, embedding_generator)
+
+    @classmethod
+    async def create(
+        cls,
+        session: AsyncSession,
+        embedding_generator: Any | None = None,
+    ) -> "EpisodicMemory":
+        """
+        Factory method to create EpisodicMemory.
+
+        Args:
+            session: Database session
+            embedding_generator: Optional embedding generator
+
+        Returns:
+            Configured EpisodicMemory instance
+        """
+        return cls(session=session, embedding_generator=embedding_generator)
+
+    # =========================================================================
+    # Recording Operations
+    # =========================================================================
+
+    async def record_episode(self, episode: EpisodeCreate) -> Episode:
+        """
+        Record a new episode.
+
+        Args:
+            episode: Episode data to record
+
+        Returns:
+            The created episode with assigned ID
+        """
+        return await self._recorder.record(episode)
+
+    async def record_success(
+        self,
+        project_id: UUID,
+        session_id: str,
+        task_type: str,
+        task_description: str,
+        actions: list[dict[str, Any]],
+        context_summary: str,
+        outcome_details: str = "",
+        duration_seconds: float = 0.0,
+        tokens_used: int = 0,
+        lessons_learned: list[str] | None = None,
+        agent_instance_id: UUID | None = None,
+        agent_type_id: UUID | None = None,
+    ) -> Episode:
+        """
+        Convenience method to record a successful episode.
+
+        Args:
+            project_id: Project ID
+            session_id: Session ID
+            task_type: Type of task
+            task_description: Task description
+            actions: Actions taken
+            context_summary: Context summary
+            outcome_details: Optional outcome details
+            duration_seconds: Task duration
+            tokens_used: Tokens consumed
+            lessons_learned: Optional lessons
+            agent_instance_id: Optional agent instance
+            agent_type_id: Optional agent type
+
+        Returns:
+            The created episode
+        """
+        episode_data = EpisodeCreate(
+            project_id=project_id,
+            session_id=session_id,
+            task_type=task_type,
+            task_description=task_description,
+            actions=actions,
+            context_summary=context_summary,
+            outcome=Outcome.SUCCESS,
+            outcome_details=outcome_details,
+            duration_seconds=duration_seconds,
+            tokens_used=tokens_used,
+            lessons_learned=lessons_learned or [],
+            agent_instance_id=agent_instance_id,
+            agent_type_id=agent_type_id,
+        )
+        return await self.record_episode(episode_data)
+
+    async def record_failure(
+        self,
+        project_id: UUID,
+        session_id: str,
+        task_type: str,
+        task_description: str,
+        actions: list[dict[str, Any]],
+        context_summary: str,
+        error_details: str,
+        duration_seconds: float = 0.0,
+        tokens_used: int = 0,
+        lessons_learned: list[str] | None = None,
+        agent_instance_id: UUID | None = None,
+        agent_type_id: UUID | None = None,
+    ) -> Episode:
+        """
+        Convenience method to record a failed episode.
+
+        Args:
+            project_id: Project ID
+            session_id: Session ID
+            task_type: Type of task
+            task_description: Task description
+            actions: Actions taken before failure
+            context_summary: Context summary
+            error_details: Error details
+            duration_seconds: Task duration
+            tokens_used: Tokens consumed
+            lessons_learned: Optional lessons from failure
+            agent_instance_id: Optional agent instance
+            agent_type_id: Optional agent type
+
+        Returns:
+            The created episode
+        """
+        episode_data = EpisodeCreate(
+            project_id=project_id,
+            session_id=session_id,
+            task_type=task_type,
+            task_description=task_description,
+            actions=actions,
+            context_summary=context_summary,
+            outcome=Outcome.FAILURE,
+            outcome_details=error_details,
+            duration_seconds=duration_seconds,
+            tokens_used=tokens_used,
+            lessons_learned=lessons_learned or [],
+            agent_instance_id=agent_instance_id,
+            agent_type_id=agent_type_id,
+        )
+        return await self.record_episode(episode_data)
+
+    # =========================================================================
+    # Retrieval Operations
+    # =========================================================================
+
+    async def search_similar(
+        self,
+        project_id: UUID,
+        query: str,
+        limit: int = 10,
+        agent_instance_id: UUID | None = None,
+    ) -> list[Episode]:
+        """
+        Search for semantically similar episodes.
+
+        Args:
+            project_id: Project to search within
+            query: Search query
+            limit: Maximum results
+            agent_instance_id: Optional filter by agent instance
+
+        Returns:
+            List of similar episodes
+        """
+        result = await self._retriever.search_similar(
+            project_id, query, limit, agent_instance_id
+        )
+        return result.items
+
+    async def get_recent(
+        self,
+        project_id: UUID,
+        limit: int = 10,
+        since: datetime | None = None,
+        agent_instance_id: UUID | None = None,
+    ) -> list[Episode]:
+        """
+        Get recent episodes.
+
+        Args:
+            project_id: Project to search within
+            limit: Maximum results
+            since: Optional time filter
+            agent_instance_id: Optional filter by agent instance
+
+        Returns:
+            List of recent episodes
+        """
+        result = await self._retriever.get_recent(
+            project_id, limit, since, agent_instance_id
+        )
+        return result.items
+
+    async def get_by_outcome(
+        self,
+        project_id: UUID,
+        outcome: Outcome,
+        limit: int = 10,
+        agent_instance_id: UUID | None = None,
+    ) -> list[Episode]:
+        """
+        Get episodes by outcome.
+
+        Args:
+            project_id: Project to search within
+            outcome: Outcome to filter by
+            limit: Maximum results
+            agent_instance_id: Optional filter by agent instance
+
+        Returns:
+            List of episodes with specified outcome
+        """
+        result = await self._retriever.get_by_outcome(
+            project_id, outcome, limit, agent_instance_id
+        )
+        return result.items
+
+    async def get_by_task_type(
+        self,
+        project_id: UUID,
+        task_type: str,
+        limit: int = 10,
+        agent_instance_id: UUID | None = None,
+    ) -> list[Episode]:
+        """
+        Get episodes by task type.
+
+        Args:
+            project_id: Project to search within
+            task_type: Task type to filter by
+            limit: Maximum results
+            agent_instance_id: Optional filter by agent instance
+
+        Returns:
+            List of episodes with specified task type
+        """
+        result = await self._retriever.get_by_task_type(
+            project_id, task_type, limit, agent_instance_id
+        )
+        return result.items
+
+    async def get_important(
+        self,
+        project_id: UUID,
+        limit: int = 10,
+        min_importance: float = 0.7,
+        agent_instance_id: UUID | None = None,
+    ) -> list[Episode]:
+        """
+        Get high-importance episodes.
+
+        Args:
+            project_id: Project to search within
+            limit: Maximum results
+            min_importance: Minimum importance score
+            agent_instance_id: Optional filter by agent instance
+
+        Returns:
+            List of important episodes
+        """
+        result = await self._retriever.get_important(
+            project_id, limit, min_importance, agent_instance_id
+        )
+        return result.items
+
+    async def retrieve(
+        self,
+        project_id: UUID,
+        strategy: RetrievalStrategy = RetrievalStrategy.RECENCY,
+        limit: int = 10,
+        **kwargs: Any,
+    ) -> RetrievalResult[Episode]:
+        """
+        Retrieve episodes with full result metadata.
+
+        Args:
+            project_id: Project to search within
+            strategy: Retrieval strategy
+            limit: Maximum results
+            **kwargs: Strategy-specific parameters
+
+        Returns:
+            RetrievalResult with episodes and metadata
+        """
+        return await self._retriever.retrieve(project_id, strategy, limit, **kwargs)
+
+    # =========================================================================
+    # Modification Operations
+    # =========================================================================
+
+    async def get_by_id(self, episode_id: UUID) -> Episode | None:
+        """Get an episode by ID."""
+        return await self._recorder.get_by_id(episode_id)
+
+    async def update_importance(
+        self,
+        episode_id: UUID,
+        importance_score: float,
+    ) -> Episode | None:
+        """
+        Update an episode's importance score.
+
+        Args:
+            episode_id: Episode to update
+            importance_score: New importance score (0.0 to 1.0)
+
+        Returns:
+            Updated episode or None if not found
+        """
+        return await self._recorder.update_importance(episode_id, importance_score)
+
+    async def add_lessons(
+        self,
+        episode_id: UUID,
+        lessons: list[str],
+    ) -> Episode | None:
+        """
+        Add lessons learned to an episode.
+
+        Args:
+            episode_id: Episode to update
+            lessons: Lessons to add
+
+        Returns:
+            Updated episode or None if not found
+        """
+        return await self._recorder.add_lessons(episode_id, lessons)
+
+    async def delete(self, episode_id: UUID) -> bool:
+        """
+        Delete an episode.
+
+        Args:
+            episode_id: Episode to delete
+
+        Returns:
+            True if deleted
+        """
+        return await self._recorder.delete(episode_id)
+
+    # =========================================================================
+    # Summarization
+    # =========================================================================
+
+    async def summarize_episodes(
+        self,
+        episode_ids: list[UUID],
+    ) -> str:
+        """
+        Summarize multiple episodes into a consolidated view.
+
+        Args:
+            episode_ids: Episodes to summarize
+
+        Returns:
+            Summary text
+        """
+        if not episode_ids:
+            return "No episodes to summarize."
+
+        episodes: list[Episode] = []
+        for episode_id in episode_ids:
+            episode = await self.get_by_id(episode_id)
+            if episode:
+                episodes.append(episode)
+
+        if not episodes:
+            return "No episodes found."
+
+        # Build summary
+        lines = [f"Summary of {len(episodes)} episodes:", ""]
+
+        # Outcome breakdown
+        success = sum(1 for e in episodes if e.outcome == Outcome.SUCCESS)
+        failure = sum(1 for e in episodes if e.outcome == Outcome.FAILURE)
+        partial = sum(1 for e in episodes if e.outcome == Outcome.PARTIAL)
+        lines.append(
+            f"Outcomes: {success} success, {failure} failure, {partial} partial"
+        )
+
+        # Task types
+        task_types = {e.task_type for e in episodes}
+        lines.append(f"Task types: {', '.join(sorted(task_types))}")
+
+        # Aggregate lessons
+        all_lessons: list[str] = []
+        for e in episodes:
+            all_lessons.extend(e.lessons_learned)
+
+        if all_lessons:
+            lines.append("")
+            lines.append("Key lessons learned:")
+            # Deduplicate lessons
+            unique_lessons = list(dict.fromkeys(all_lessons))
+            for lesson in unique_lessons[:10]:  # Top 10
+                lines.append(f"  - {lesson}")
+
+        # Duration and tokens
+        total_duration = sum(e.duration_seconds for e in episodes)
+        total_tokens = sum(e.tokens_used for e in episodes)
+        lines.append("")
+        lines.append(f"Total duration: {total_duration:.1f}s")
+        lines.append(f"Total tokens: {total_tokens:,}")
+
+        return "\n".join(lines)
+
+    # =========================================================================
+    # Statistics
+    # =========================================================================
+
+    async def get_stats(self, project_id: UUID) -> dict[str, Any]:
+        """
+        Get episode statistics for a project.
+
+        Args:
+            project_id: Project to get stats for
+
+        Returns:
+            Dictionary with episode statistics
+        """
+        return await self._recorder.get_stats(project_id)
+
+    async def count(
+        self,
+        project_id: UUID,
+        since: datetime | None = None,
+    ) -> int:
+        """
+        Count episodes for a project.
+
+        Args:
+            project_id: Project to count for
+            since: Optional time filter
+
+        Returns:
+            Number of episodes
+        """
+        return await self._recorder.count_by_project(project_id, since)

backend/app/services/memory/episodic/recorder.py

@@ -0,0 +1,357 @@
+# app/services/memory/episodic/recorder.py
+"""
+Episode Recording.
+
+Handles the creation and storage of episodic memories
+during agent task execution.
+"""
+
+import logging
+from datetime import UTC, datetime
+from typing import Any
+from uuid import UUID, uuid4
+
+from sqlalchemy import select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.memory.enums import EpisodeOutcome
+from app.models.memory.episode import Episode as EpisodeModel
+from app.services.memory.config import get_memory_settings
+from app.services.memory.types import Episode, EpisodeCreate, Outcome
+
+logger = logging.getLogger(__name__)
+
+
+def _outcome_to_db(outcome: Outcome) -> EpisodeOutcome:
+    """Convert service Outcome to database EpisodeOutcome."""
+    return EpisodeOutcome(outcome.value)
+
+
+def _db_to_outcome(db_outcome: EpisodeOutcome) -> Outcome:
+    """Convert database EpisodeOutcome to service Outcome."""
+    return Outcome(db_outcome.value)
+
+
+def _model_to_episode(model: EpisodeModel) -> Episode:
+    """Convert SQLAlchemy model to Episode dataclass."""
+    # SQLAlchemy Column types are inferred as Column[T] by mypy, but at runtime
+    # they return actual values. We use type: ignore to handle this mismatch.
+    return Episode(
+        id=model.id,  # type: ignore[arg-type]
+        project_id=model.project_id,  # type: ignore[arg-type]
+        agent_instance_id=model.agent_instance_id,  # type: ignore[arg-type]
+        agent_type_id=model.agent_type_id,  # type: ignore[arg-type]
+        session_id=model.session_id,  # type: ignore[arg-type]
+        task_type=model.task_type,  # type: ignore[arg-type]
+        task_description=model.task_description,  # type: ignore[arg-type]
+        actions=model.actions or [],  # type: ignore[arg-type]
+        context_summary=model.context_summary,  # type: ignore[arg-type]
+        outcome=_db_to_outcome(model.outcome),  # type: ignore[arg-type]
+        outcome_details=model.outcome_details or "",  # type: ignore[arg-type]
+        duration_seconds=model.duration_seconds,  # type: ignore[arg-type]
+        tokens_used=model.tokens_used,  # type: ignore[arg-type]
+        lessons_learned=model.lessons_learned or [],  # type: ignore[arg-type]
+        importance_score=model.importance_score,  # type: ignore[arg-type]
+        embedding=None,  # Don't expose raw embedding
+        occurred_at=model.occurred_at,  # type: ignore[arg-type]
+        created_at=model.created_at,  # type: ignore[arg-type]
+        updated_at=model.updated_at,  # type: ignore[arg-type]
+    )
+
+
+class EpisodeRecorder:
+    """
+    Records episodes to the database.
+
+    Handles episode creation, importance scoring,
+    and lesson extraction.
+    """
+
+    def __init__(
+        self,
+        session: AsyncSession,
+        embedding_generator: Any | None = None,
+    ) -> None:
+        """
+        Initialize recorder.
+
+        Args:
+            session: Database session
+            embedding_generator: Optional embedding generator for semantic indexing
+        """
+        self._session = session
+        self._embedding_generator = embedding_generator
+        self._settings = get_memory_settings()
+
+    async def record(self, episode_data: EpisodeCreate) -> Episode:
+        """
+        Record a new episode.
+
+        Args:
+            episode_data: Episode data to record
+
+        Returns:
+            The created episode
+        """
+        now = datetime.now(UTC)
+
+        # Calculate importance score if not provided
+        importance = episode_data.importance_score
+        if importance == 0.5:  # Default value, calculate
+            importance = self._calculate_importance(episode_data)
+
+        # Create the model
+        model = EpisodeModel(
+            id=uuid4(),
+            project_id=episode_data.project_id,
+            agent_instance_id=episode_data.agent_instance_id,
+            agent_type_id=episode_data.agent_type_id,
+            session_id=episode_data.session_id,
+            task_type=episode_data.task_type,
+            task_description=episode_data.task_description,
+            actions=episode_data.actions,
+            context_summary=episode_data.context_summary,
+            outcome=_outcome_to_db(episode_data.outcome),
+            outcome_details=episode_data.outcome_details,
+            duration_seconds=episode_data.duration_seconds,
+            tokens_used=episode_data.tokens_used,
+            lessons_learned=episode_data.lessons_learned,
+            importance_score=importance,
+            occurred_at=now,
+            created_at=now,
+            updated_at=now,
+        )
+
+        # Generate embedding if generator available
+        if self._embedding_generator is not None:
+            try:
+                text_for_embedding = self._create_embedding_text(episode_data)
+                embedding = await self._embedding_generator.generate(text_for_embedding)
+                model.embedding = embedding
+            except Exception as e:
+                logger.warning(f"Failed to generate embedding: {e}")
+
+        self._session.add(model)
+        await self._session.flush()
+        await self._session.refresh(model)
+
+        logger.debug(f"Recorded episode {model.id} for task {model.task_type}")
+        return _model_to_episode(model)
+
+    def _calculate_importance(self, episode_data: EpisodeCreate) -> float:
+        """
+        Calculate importance score for an episode.
+
+        Factors:
+        - Outcome: Failures are more important to learn from
+        - Duration: Longer tasks may be more significant
+        - Token usage: Higher usage may indicate complexity
+        - Lessons learned: Episodes with lessons are more valuable
+        """
+        score = 0.5  # Base score
+
+        # Outcome factor
+        if episode_data.outcome == Outcome.FAILURE:
+            score += 0.2  # Failures are important for learning
+        elif episode_data.outcome == Outcome.PARTIAL:
+            score += 0.1
+        # Success is default, no adjustment
+
+        # Lessons learned factor
+        if episode_data.lessons_learned:
+            score += min(0.15, len(episode_data.lessons_learned) * 0.05)
+
+        # Duration factor (longer tasks may be more significant)
+        if episode_data.duration_seconds > 60:
+            score += 0.05
+        if episode_data.duration_seconds > 300:
+            score += 0.05
+
+        # Token usage factor (complex tasks)
+        if episode_data.tokens_used > 1000:
+            score += 0.05
+
+        # Clamp to valid range
+        return min(1.0, max(0.0, score))
+
+    def _create_embedding_text(self, episode_data: EpisodeCreate) -> str:
+        """Create text representation for embedding generation."""
+        parts = [
+            f"Task: {episode_data.task_type}",
+            f"Description: {episode_data.task_description}",
+            f"Context: {episode_data.context_summary}",
+            f"Outcome: {episode_data.outcome.value}",
+        ]
+
+        if episode_data.outcome_details:
+            parts.append(f"Details: {episode_data.outcome_details}")
+
+        if episode_data.lessons_learned:
+            parts.append(f"Lessons: {', '.join(episode_data.lessons_learned)}")
+
+        return "\n".join(parts)
+
+    async def get_by_id(self, episode_id: UUID) -> Episode | None:
+        """Get an episode by ID."""
+        query = select(EpisodeModel).where(EpisodeModel.id == episode_id)
+        result = await self._session.execute(query)
+        model = result.scalar_one_or_none()
+
+        if model is None:
+            return None
+
+        return _model_to_episode(model)
+
+    async def update_importance(
+        self,
+        episode_id: UUID,
+        importance_score: float,
+    ) -> Episode | None:
+        """
+        Update the importance score of an episode.
+
+        Args:
+            episode_id: Episode to update
+            importance_score: New importance score (0.0 to 1.0)
+
+        Returns:
+            Updated episode or None if not found
+        """
+        # Validate score
+        importance_score = min(1.0, max(0.0, importance_score))
+
+        stmt = (
+            update(EpisodeModel)
+            .where(EpisodeModel.id == episode_id)
+            .values(
+                importance_score=importance_score,
+                updated_at=datetime.now(UTC),
+            )
+            .returning(EpisodeModel)
+        )
+
+        result = await self._session.execute(stmt)
+        model = result.scalar_one_or_none()
+
+        if model is None:
+            return None
+
+        await self._session.flush()
+        return _model_to_episode(model)
+
+    async def add_lessons(
+        self,
+        episode_id: UUID,
+        lessons: list[str],
+    ) -> Episode | None:
+        """
+        Add lessons learned to an episode.
+
+        Args:
+            episode_id: Episode to update
+            lessons: New lessons to add
+
+        Returns:
+            Updated episode or None if not found
+        """
+        # Get current episode
+        query = select(EpisodeModel).where(EpisodeModel.id == episode_id)
+        result = await self._session.execute(query)
+        model = result.scalar_one_or_none()
+
+        if model is None:
+            return None
+
+        # Append lessons
+        current_lessons: list[str] = model.lessons_learned or []  # type: ignore[assignment]
+        updated_lessons = current_lessons + lessons
+
+        stmt = (
+            update(EpisodeModel)
+            .where(EpisodeModel.id == episode_id)
+            .values(
+                lessons_learned=updated_lessons,
+                updated_at=datetime.now(UTC),
+            )
+            .returning(EpisodeModel)
+        )
+
+        result = await self._session.execute(stmt)
+        model = result.scalar_one_or_none()
+        await self._session.flush()
+
+        return _model_to_episode(model) if model else None
+
+    async def delete(self, episode_id: UUID) -> bool:
+        """
+        Delete an episode.
+
+        Args:
+            episode_id: Episode to delete
+
+        Returns:
+            True if deleted
+        """
+        query = select(EpisodeModel).where(EpisodeModel.id == episode_id)
+        result = await self._session.execute(query)
+        model = result.scalar_one_or_none()
+
+        if model is None:
+            return False
+
+        await self._session.delete(model)
+        await self._session.flush()
+        return True
+
+    async def count_by_project(
+        self,
+        project_id: UUID,
+        since: datetime | None = None,
+    ) -> int:
+        """Count episodes for a project."""
+        query = select(EpisodeModel).where(EpisodeModel.project_id == project_id)
+        if since is not None:
+            query = query.where(EpisodeModel.occurred_at >= since)
+
+        result = await self._session.execute(query)
+        return len(list(result.scalars().all()))
+
+    async def get_stats(self, project_id: UUID) -> dict[str, Any]:
+        """
+        Get statistics for a project's episodes.
+
+        Returns:
+            Dictionary with episode statistics
+        """
+        query = select(EpisodeModel).where(EpisodeModel.project_id == project_id)
+        result = await self._session.execute(query)
+        episodes = list(result.scalars().all())
+
+        if not episodes:
+            return {
+                "total_count": 0,
+                "success_count": 0,
+                "failure_count": 0,
+                "partial_count": 0,
+                "avg_importance": 0.0,
+                "avg_duration": 0.0,
+                "total_tokens": 0,
+            }
+
+        success_count = sum(1 for e in episodes if e.outcome == EpisodeOutcome.SUCCESS)
+        failure_count = sum(1 for e in episodes if e.outcome == EpisodeOutcome.FAILURE)
+        partial_count = sum(1 for e in episodes if e.outcome == EpisodeOutcome.PARTIAL)
+
+        avg_importance = sum(e.importance_score for e in episodes) / len(episodes)
+        avg_duration = sum(e.duration_seconds for e in episodes) / len(episodes)
+        total_tokens = sum(e.tokens_used for e in episodes)
+
+        return {
+            "total_count": len(episodes),
+            "success_count": success_count,
+            "failure_count": failure_count,
+            "partial_count": partial_count,
+            "avg_importance": avg_importance,
+            "avg_duration": avg_duration,
+            "total_tokens": total_tokens,
+        }

backend/app/services/memory/episodic/retrieval.py

@@ -0,0 +1,503 @@
+# app/services/memory/episodic/retrieval.py
+"""
+Episode Retrieval Strategies.
+
+Provides different retrieval strategies for finding relevant episodes:
+- Semantic similarity (vector search)
+- Recency-based
+- Outcome-based filtering
+- Importance-based ranking
+"""
+
+import logging
+import time
+from abc import ABC, abstractmethod
+from datetime import datetime
+from enum import Enum
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import and_, desc, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.memory.enums import EpisodeOutcome
+from app.models.memory.episode import Episode as EpisodeModel
+from app.services.memory.types import Episode, Outcome, RetrievalResult
+
+logger = logging.getLogger(__name__)
+
+
+class RetrievalStrategy(str, Enum):
+    """Retrieval strategy types."""
+
+    SEMANTIC = "semantic"
+    RECENCY = "recency"
+    OUTCOME = "outcome"
+    IMPORTANCE = "importance"
+    HYBRID = "hybrid"
+
+
+def _model_to_episode(model: EpisodeModel) -> Episode:
+    """Convert SQLAlchemy model to Episode dataclass."""
+    # SQLAlchemy Column types are inferred as Column[T] by mypy, but at runtime
+    # they return actual values. We use type: ignore to handle this mismatch.
+    return Episode(
+        id=model.id,  # type: ignore[arg-type]
+        project_id=model.project_id,  # type: ignore[arg-type]
+        agent_instance_id=model.agent_instance_id,  # type: ignore[arg-type]
+        agent_type_id=model.agent_type_id,  # type: ignore[arg-type]
+        session_id=model.session_id,  # type: ignore[arg-type]
+        task_type=model.task_type,  # type: ignore[arg-type]
+        task_description=model.task_description,  # type: ignore[arg-type]
+        actions=model.actions or [],  # type: ignore[arg-type]
+        context_summary=model.context_summary,  # type: ignore[arg-type]
+        outcome=Outcome(model.outcome.value),
+        outcome_details=model.outcome_details or "",  # type: ignore[arg-type]
+        duration_seconds=model.duration_seconds,  # type: ignore[arg-type]
+        tokens_used=model.tokens_used,  # type: ignore[arg-type]
+        lessons_learned=model.lessons_learned or [],  # type: ignore[arg-type]
+        importance_score=model.importance_score,  # type: ignore[arg-type]
+        embedding=None,  # Don't expose raw embedding
+        occurred_at=model.occurred_at,  # type: ignore[arg-type]
+        created_at=model.created_at,  # type: ignore[arg-type]
+        updated_at=model.updated_at,  # type: ignore[arg-type]
+    )
+
+
+class BaseRetriever(ABC):
+    """Abstract base class for episode retrieval strategies."""
+
+    @abstractmethod
+    async def retrieve(
+        self,
+        session: AsyncSession,
+        project_id: UUID,
+        limit: int = 10,
+        **kwargs: Any,
+    ) -> RetrievalResult[Episode]:
+        """Retrieve episodes based on the strategy."""
+        ...
+
+
+class RecencyRetriever(BaseRetriever):
+    """Retrieves episodes by recency (most recent first)."""
+
+    async def retrieve(
+        self,
+        session: AsyncSession,
+        project_id: UUID,
+        limit: int = 10,
+        *,
+        since: datetime | None = None,
+        agent_instance_id: UUID | None = None,
+        **kwargs: Any,
+    ) -> RetrievalResult[Episode]:
+        """Retrieve most recent episodes."""
+        start_time = time.perf_counter()
+
+        query = (
+            select(EpisodeModel)
+            .where(EpisodeModel.project_id == project_id)
+            .order_by(desc(EpisodeModel.occurred_at))
+            .limit(limit)
+        )
+
+        if since is not None:
+            query = query.where(EpisodeModel.occurred_at >= since)
+
+        if agent_instance_id is not None:
+            query = query.where(EpisodeModel.agent_instance_id == agent_instance_id)
+
+        result = await session.execute(query)
+        models = list(result.scalars().all())
+
+        # Get total count
+        count_query = select(EpisodeModel).where(EpisodeModel.project_id == project_id)
+        if since is not None:
+            count_query = count_query.where(EpisodeModel.occurred_at >= since)
+        count_result = await session.execute(count_query)
+        total_count = len(list(count_result.scalars().all()))
+
+        latency_ms = (time.perf_counter() - start_time) * 1000
+
+        return RetrievalResult(
+            items=[_model_to_episode(m) for m in models],
+            total_count=total_count,
+            query="recency",
+            retrieval_type=RetrievalStrategy.RECENCY.value,
+            latency_ms=latency_ms,
+            metadata={"since": since.isoformat() if since else None},
+        )
+
+
+class OutcomeRetriever(BaseRetriever):
+    """Retrieves episodes filtered by outcome."""
+
+    async def retrieve(
+        self,
+        session: AsyncSession,
+        project_id: UUID,
+        limit: int = 10,
+        *,
+        outcome: Outcome | None = None,
+        agent_instance_id: UUID | None = None,
+        **kwargs: Any,
+    ) -> RetrievalResult[Episode]:
+        """Retrieve episodes by outcome."""
+        start_time = time.perf_counter()
+
+        query = (
+            select(EpisodeModel)
+            .where(EpisodeModel.project_id == project_id)
+            .order_by(desc(EpisodeModel.occurred_at))
+            .limit(limit)
+        )
+
+        if outcome is not None:
+            db_outcome = EpisodeOutcome(outcome.value)
+            query = query.where(EpisodeModel.outcome == db_outcome)
+
+        if agent_instance_id is not None:
+            query = query.where(EpisodeModel.agent_instance_id == agent_instance_id)
+
+        result = await session.execute(query)
+        models = list(result.scalars().all())
+
+        # Get total count
+        count_query = select(EpisodeModel).where(EpisodeModel.project_id == project_id)
+        if outcome is not None:
+            count_query = count_query.where(
+                EpisodeModel.outcome == EpisodeOutcome(outcome.value)
+            )
+        count_result = await session.execute(count_query)
+        total_count = len(list(count_result.scalars().all()))
+
+        latency_ms = (time.perf_counter() - start_time) * 1000
+
+        return RetrievalResult(
+            items=[_model_to_episode(m) for m in models],
+            total_count=total_count,
+            query=f"outcome:{outcome.value if outcome else 'all'}",
+            retrieval_type=RetrievalStrategy.OUTCOME.value,
+            latency_ms=latency_ms,
+            metadata={"outcome": outcome.value if outcome else None},
+        )
+
+
+class TaskTypeRetriever(BaseRetriever):
+    """Retrieves episodes filtered by task type."""
+
+    async def retrieve(
+        self,
+        session: AsyncSession,
+        project_id: UUID,
+        limit: int = 10,
+        *,
+        task_type: str | None = None,
+        agent_instance_id: UUID | None = None,
+        **kwargs: Any,
+    ) -> RetrievalResult[Episode]:
+        """Retrieve episodes by task type."""
+        start_time = time.perf_counter()
+
+        query = (
+            select(EpisodeModel)
+            .where(EpisodeModel.project_id == project_id)
+            .order_by(desc(EpisodeModel.occurred_at))
+            .limit(limit)
+        )
+
+        if task_type is not None:
+            query = query.where(EpisodeModel.task_type == task_type)
+
+        if agent_instance_id is not None:
+            query = query.where(EpisodeModel.agent_instance_id == agent_instance_id)
+
+        result = await session.execute(query)
+        models = list(result.scalars().all())
+
+        # Get total count
+        count_query = select(EpisodeModel).where(EpisodeModel.project_id == project_id)
+        if task_type is not None:
+            count_query = count_query.where(EpisodeModel.task_type == task_type)
+        count_result = await session.execute(count_query)
+        total_count = len(list(count_result.scalars().all()))
+
+        latency_ms = (time.perf_counter() - start_time) * 1000
+
+        return RetrievalResult(
+            items=[_model_to_episode(m) for m in models],
+            total_count=total_count,
+            query=f"task_type:{task_type or 'all'}",
+            retrieval_type="task_type",
+            latency_ms=latency_ms,
+            metadata={"task_type": task_type},
+        )
+
+
+class ImportanceRetriever(BaseRetriever):
+    """Retrieves episodes ranked by importance score."""
+
+    async def retrieve(
+        self,
+        session: AsyncSession,
+        project_id: UUID,
+        limit: int = 10,
+        *,
+        min_importance: float = 0.0,
+        agent_instance_id: UUID | None = None,
+        **kwargs: Any,
+    ) -> RetrievalResult[Episode]:
+        """Retrieve episodes by importance."""
+        start_time = time.perf_counter()
+
+        query = (
+            select(EpisodeModel)
+            .where(
+                and_(
+                    EpisodeModel.project_id == project_id,
+                    EpisodeModel.importance_score >= min_importance,
+                )
+            )
+            .order_by(desc(EpisodeModel.importance_score))
+            .limit(limit)
+        )
+
+        if agent_instance_id is not None:
+            query = query.where(EpisodeModel.agent_instance_id == agent_instance_id)
+
+        result = await session.execute(query)
+        models = list(result.scalars().all())
+
+        # Get total count
+        count_query = select(EpisodeModel).where(
+            and_(
+                EpisodeModel.project_id == project_id,
+                EpisodeModel.importance_score >= min_importance,
+            )
+        )
+        count_result = await session.execute(count_query)
+        total_count = len(list(count_result.scalars().all()))
+
+        latency_ms = (time.perf_counter() - start_time) * 1000
+
+        return RetrievalResult(
+            items=[_model_to_episode(m) for m in models],
+            total_count=total_count,
+            query=f"importance>={min_importance}",
+            retrieval_type=RetrievalStrategy.IMPORTANCE.value,
+            latency_ms=latency_ms,
+            metadata={"min_importance": min_importance},
+        )
+
+
+class SemanticRetriever(BaseRetriever):
+    """Retrieves episodes by semantic similarity using vector search."""
+
+    def __init__(self, embedding_generator: Any | None = None) -> None:
+        """Initialize with optional embedding generator."""
+        self._embedding_generator = embedding_generator
+
+    async def retrieve(
+        self,
+        session: AsyncSession,
+        project_id: UUID,
+        limit: int = 10,
+        *,
+        query_text: str | None = None,
+        query_embedding: list[float] | None = None,
+        agent_instance_id: UUID | None = None,
+        **kwargs: Any,
+    ) -> RetrievalResult[Episode]:
+        """Retrieve episodes by semantic similarity."""
+        start_time = time.perf_counter()
+
+        # If no embedding provided, fall back to recency
+        if query_embedding is None and query_text is None:
+            logger.warning(
+                "No query provided for semantic search, falling back to recency"
+            )
+            recency = RecencyRetriever()
+            fallback_result = await recency.retrieve(
+                session, project_id, limit, agent_instance_id=agent_instance_id
+            )
+            latency_ms = (time.perf_counter() - start_time) * 1000
+            return RetrievalResult(
+                items=fallback_result.items,
+                total_count=fallback_result.total_count,
+                query="no_query",
+                retrieval_type=RetrievalStrategy.SEMANTIC.value,
+                latency_ms=latency_ms,
+                metadata={"fallback": "recency", "reason": "no_query"},
+            )
+
+        # Generate embedding if needed
+        embedding = query_embedding
+        if embedding is None and query_text is not None:
+            if self._embedding_generator is not None:
+                embedding = await self._embedding_generator.generate(query_text)
+            else:
+                logger.warning("No embedding generator, falling back to recency")
+                recency = RecencyRetriever()
+                fallback_result = await recency.retrieve(
+                    session, project_id, limit, agent_instance_id=agent_instance_id
+                )
+                latency_ms = (time.perf_counter() - start_time) * 1000
+                return RetrievalResult(
+                    items=fallback_result.items,
+                    total_count=fallback_result.total_count,
+                    query=query_text,
+                    retrieval_type=RetrievalStrategy.SEMANTIC.value,
+                    latency_ms=latency_ms,
+                    metadata={
+                        "fallback": "recency",
+                        "reason": "no_embedding_generator",
+                    },
+                )
+
+        # For now, use recency if vector search not available
+        # TODO: Implement proper pgvector similarity search when integrated
+        logger.debug("Vector search not yet implemented, using recency fallback")
+        recency = RecencyRetriever()
+        result = await recency.retrieve(
+            session, project_id, limit, agent_instance_id=agent_instance_id
+        )
+
+        latency_ms = (time.perf_counter() - start_time) * 1000
+
+        return RetrievalResult(
+            items=result.items,
+            total_count=result.total_count,
+            query=query_text or "embedding",
+            retrieval_type=RetrievalStrategy.SEMANTIC.value,
+            latency_ms=latency_ms,
+            metadata={"fallback": "recency"},
+        )
+
+
+class EpisodeRetriever:
+    """
+    Unified episode retrieval service.
+
+    Provides a single interface for all retrieval strategies.
+    """
+
+    def __init__(
+        self,
+        session: AsyncSession,
+        embedding_generator: Any | None = None,
+    ) -> None:
+        """Initialize retriever with database session."""
+        self._session = session
+        self._retrievers: dict[RetrievalStrategy, BaseRetriever] = {
+            RetrievalStrategy.RECENCY: RecencyRetriever(),
+            RetrievalStrategy.OUTCOME: OutcomeRetriever(),
+            RetrievalStrategy.IMPORTANCE: ImportanceRetriever(),
+            RetrievalStrategy.SEMANTIC: SemanticRetriever(embedding_generator),
+        }
+
+    async def retrieve(
+        self,
+        project_id: UUID,
+        strategy: RetrievalStrategy = RetrievalStrategy.RECENCY,
+        limit: int = 10,
+        **kwargs: Any,
+    ) -> RetrievalResult[Episode]:
+        """
+        Retrieve episodes using the specified strategy.
+
+        Args:
+            project_id: Project to search within
+            strategy: Retrieval strategy to use
+            limit: Maximum number of episodes to return
+            **kwargs: Strategy-specific parameters
+
+        Returns:
+            RetrievalResult containing matching episodes
+        """
+        retriever = self._retrievers.get(strategy)
+        if retriever is None:
+            raise ValueError(f"Unknown retrieval strategy: {strategy}")
+
+        return await retriever.retrieve(self._session, project_id, limit, **kwargs)
+
+    async def get_recent(
+        self,
+        project_id: UUID,
+        limit: int = 10,
+        since: datetime | None = None,
+        agent_instance_id: UUID | None = None,
+    ) -> RetrievalResult[Episode]:
+        """Get recent episodes."""
+        return await self.retrieve(
+            project_id,
+            RetrievalStrategy.RECENCY,
+            limit,
+            since=since,
+            agent_instance_id=agent_instance_id,
+        )
+
+    async def get_by_outcome(
+        self,
+        project_id: UUID,
+        outcome: Outcome,
+        limit: int = 10,
+        agent_instance_id: UUID | None = None,
+    ) -> RetrievalResult[Episode]:
+        """Get episodes by outcome."""
+        return await self.retrieve(
+            project_id,
+            RetrievalStrategy.OUTCOME,
+            limit,
+            outcome=outcome,
+            agent_instance_id=agent_instance_id,
+        )
+
+    async def get_by_task_type(
+        self,
+        project_id: UUID,
+        task_type: str,
+        limit: int = 10,
+        agent_instance_id: UUID | None = None,
+    ) -> RetrievalResult[Episode]:
+        """Get episodes by task type."""
+        retriever = TaskTypeRetriever()
+        return await retriever.retrieve(
+            self._session,
+            project_id,
+            limit,
+            task_type=task_type,
+            agent_instance_id=agent_instance_id,
+        )
+
+    async def get_important(
+        self,
+        project_id: UUID,
+        limit: int = 10,
+        min_importance: float = 0.7,
+        agent_instance_id: UUID | None = None,
+    ) -> RetrievalResult[Episode]:
+        """Get high-importance episodes."""
+        return await self.retrieve(
+            project_id,
+            RetrievalStrategy.IMPORTANCE,
+            limit,
+            min_importance=min_importance,
+            agent_instance_id=agent_instance_id,
+        )
+
+    async def search_similar(
+        self,
+        project_id: UUID,
+        query: str,
+        limit: int = 10,
+        agent_instance_id: UUID | None = None,
+    ) -> RetrievalResult[Episode]:
+        """Search for semantically similar episodes."""
+        return await self.retrieve(
+            project_id,
+            RetrievalStrategy.SEMANTIC,
+            limit,
+            query_text=query,
+            agent_instance_id=agent_instance_id,
+        )

backend/app/services/memory/exceptions.py

@@ -0,0 +1,222 @@
+"""
+Memory System Exceptions
+
+Custom exception classes for the Agent Memory System.
+"""
+
+from typing import Any
+from uuid import UUID
+
+
+class MemoryError(Exception):
+    """Base exception for all memory-related errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        memory_type: str | None = None,
+        scope_type: str | None = None,
+        scope_id: str | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.memory_type = memory_type
+        self.scope_type = scope_type
+        self.scope_id = scope_id
+        self.details = details or {}
+
+
+class MemoryNotFoundError(MemoryError):
+    """Raised when a memory item is not found."""
+
+    def __init__(
+        self,
+        message: str = "Memory not found",
+        *,
+        memory_id: UUID | str | None = None,
+        key: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.memory_id = memory_id
+        self.key = key
+
+
+class MemoryCapacityError(MemoryError):
+    """Raised when memory capacity limits are exceeded."""
+
+    def __init__(
+        self,
+        message: str = "Memory capacity exceeded",
+        *,
+        current_size: int = 0,
+        max_size: int = 0,
+        item_count: int = 0,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.current_size = current_size
+        self.max_size = max_size
+        self.item_count = item_count
+
+
+class MemoryExpiredError(MemoryError):
+    """Raised when attempting to access expired memory."""
+
+    def __init__(
+        self,
+        message: str = "Memory has expired",
+        *,
+        key: str | None = None,
+        expired_at: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.key = key
+        self.expired_at = expired_at
+
+
+class MemoryStorageError(MemoryError):
+    """Raised when memory storage operations fail."""
+
+    def __init__(
+        self,
+        message: str = "Memory storage operation failed",
+        *,
+        operation: str | None = None,
+        backend: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.operation = operation
+        self.backend = backend
+
+
+class MemoryConnectionError(MemoryError):
+    """Raised when memory storage connection fails."""
+
+    def __init__(
+        self,
+        message: str = "Memory connection failed",
+        *,
+        backend: str | None = None,
+        host: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.backend = backend
+        self.host = host
+
+
+class MemorySerializationError(MemoryError):
+    """Raised when memory serialization/deserialization fails."""
+
+    def __init__(
+        self,
+        message: str = "Memory serialization failed",
+        *,
+        content_type: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.content_type = content_type
+
+
+class MemoryScopeError(MemoryError):
+    """Raised when memory scope operations fail."""
+
+    def __init__(
+        self,
+        message: str = "Memory scope error",
+        *,
+        requested_scope: str | None = None,
+        allowed_scopes: list[str] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.requested_scope = requested_scope
+        self.allowed_scopes = allowed_scopes or []
+
+
+class MemoryConsolidationError(MemoryError):
+    """Raised when memory consolidation fails."""
+
+    def __init__(
+        self,
+        message: str = "Memory consolidation failed",
+        *,
+        source_type: str | None = None,
+        target_type: str | None = None,
+        items_processed: int = 0,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.source_type = source_type
+        self.target_type = target_type
+        self.items_processed = items_processed
+
+
+class MemoryRetrievalError(MemoryError):
+    """Raised when memory retrieval fails."""
+
+    def __init__(
+        self,
+        message: str = "Memory retrieval failed",
+        *,
+        query: str | None = None,
+        retrieval_type: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.query = query
+        self.retrieval_type = retrieval_type
+
+
+class EmbeddingError(MemoryError):
+    """Raised when embedding generation fails."""
+
+    def __init__(
+        self,
+        message: str = "Embedding generation failed",
+        *,
+        content_length: int = 0,
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.content_length = content_length
+        self.model = model
+
+
+class CheckpointError(MemoryError):
+    """Raised when checkpoint operations fail."""
+
+    def __init__(
+        self,
+        message: str = "Checkpoint operation failed",
+        *,
+        checkpoint_id: str | None = None,
+        operation: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.checkpoint_id = checkpoint_id
+        self.operation = operation
+
+
+class MemoryConflictError(MemoryError):
+    """Raised when there's a conflict in memory (e.g., contradictory facts)."""
+
+    def __init__(
+        self,
+        message: str = "Memory conflict detected",
+        *,
+        conflicting_ids: list[str | UUID] | None = None,
+        conflict_type: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.conflicting_ids = conflicting_ids or []
+        self.conflict_type = conflict_type

backend/app/services/memory/indexing/__init__.py

@@ -0,0 +1,56 @@
+# app/services/memory/indexing/__init__.py
+"""
+Memory Indexing & Retrieval.
+
+Provides vector embeddings and multiple index types for efficient memory search:
+- Vector index for semantic similarity
+- Temporal index for time-based queries
+- Entity index for entity lookups
+- Outcome index for success/failure filtering
+"""
+
+from .index import (
+    EntityIndex,
+    EntityIndexEntry,
+    IndexEntry,
+    MemoryIndex,
+    MemoryIndexer,
+    OutcomeIndex,
+    OutcomeIndexEntry,
+    TemporalIndex,
+    TemporalIndexEntry,
+    VectorIndex,
+    VectorIndexEntry,
+    get_memory_indexer,
+)
+from .retrieval import (
+    CacheEntry,
+    RelevanceScorer,
+    RetrievalCache,
+    RetrievalEngine,
+    RetrievalQuery,
+    ScoredResult,
+    get_retrieval_engine,
+)
+
+__all__ = [
+    "CacheEntry",
+    "EntityIndex",
+    "EntityIndexEntry",
+    "IndexEntry",
+    "MemoryIndex",
+    "MemoryIndexer",
+    "OutcomeIndex",
+    "OutcomeIndexEntry",
+    "RelevanceScorer",
+    "RetrievalCache",
+    "RetrievalEngine",
+    "RetrievalQuery",
+    "ScoredResult",
+    "TemporalIndex",
+    "TemporalIndexEntry",
+    "VectorIndex",
+    "VectorIndexEntry",
+    "get_memory_indexer",
+    "get_retrieval_engine",
+]

backend/app/services/memory/indexing/index.py

@@ -0,0 +1,851 @@
+# app/services/memory/indexing/index.py
+"""
+Memory Indexing.
+
+Provides multiple indexing strategies for efficient memory retrieval:
+- Vector embeddings for semantic search
+- Temporal index for time-based queries
+- Entity index for entity-based lookups
+- Outcome index for success/failure filtering
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Any, TypeVar
+from uuid import UUID
+
+from app.services.memory.types import Episode, Fact, MemoryType, Outcome, Procedure
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", Episode, Fact, Procedure)
+
+
+def _utcnow() -> datetime:
+    """Get current UTC time as timezone-aware datetime."""
+    return datetime.now(UTC)
+
+
+@dataclass
+class IndexEntry:
+    """A single entry in an index."""
+
+    memory_id: UUID
+    memory_type: MemoryType
+    indexed_at: datetime = field(default_factory=_utcnow)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class VectorIndexEntry(IndexEntry):
+    """An entry with vector embedding."""
+
+    embedding: list[float] = field(default_factory=list)
+    dimension: int = 0
+
+    def __post_init__(self) -> None:
+        """Set dimension from embedding."""
+        if self.embedding:
+            self.dimension = len(self.embedding)
+
+
+@dataclass
+class TemporalIndexEntry(IndexEntry):
+    """An entry indexed by time."""
+
+    timestamp: datetime = field(default_factory=_utcnow)
+
+
+@dataclass
+class EntityIndexEntry(IndexEntry):
+    """An entry indexed by entity."""
+
+    entity_type: str = ""
+    entity_value: str = ""
+
+
+@dataclass
+class OutcomeIndexEntry(IndexEntry):
+    """An entry indexed by outcome."""
+
+    outcome: Outcome = Outcome.SUCCESS
+
+
+class MemoryIndex[T](ABC):
+    """Abstract base class for memory indices."""
+
+    @abstractmethod
+    async def add(self, item: T) -> IndexEntry:
+        """Add an item to the index."""
+        ...
+
+    @abstractmethod
+    async def remove(self, memory_id: UUID) -> bool:
+        """Remove an item from the index."""
+        ...
+
+    @abstractmethod
+    async def search(
+        self,
+        query: Any,
+        limit: int = 10,
+        **kwargs: Any,
+    ) -> list[IndexEntry]:
+        """Search the index."""
+        ...
+
+    @abstractmethod
+    async def clear(self) -> int:
+        """Clear all entries from the index."""
+        ...
+
+    @abstractmethod
+    async def count(self) -> int:
+        """Get the number of entries in the index."""
+        ...
+
+
+class VectorIndex(MemoryIndex[T]):
+    """
+    Vector-based index using embeddings for semantic similarity search.
+
+    Uses cosine similarity for matching.
+    """
+
+    def __init__(self, dimension: int = 1536) -> None:
+        """
+        Initialize the vector index.
+
+        Args:
+            dimension: Embedding dimension (default 1536 for OpenAI)
+        """
+        self._dimension = dimension
+        self._entries: dict[UUID, VectorIndexEntry] = {}
+        logger.info(f"Initialized VectorIndex with dimension={dimension}")
+
+    async def add(self, item: T) -> VectorIndexEntry:
+        """
+        Add an item to the vector index.
+
+        Args:
+            item: Memory item with embedding
+
+        Returns:
+            The created index entry
+        """
+        embedding = getattr(item, "embedding", None) or []
+
+        entry = VectorIndexEntry(
+            memory_id=item.id,
+            memory_type=self._get_memory_type(item),
+            embedding=embedding,
+            dimension=len(embedding),
+        )
+
+        self._entries[item.id] = entry
+        logger.debug(f"Added {item.id} to vector index")
+        return entry
+
+    async def remove(self, memory_id: UUID) -> bool:
+        """Remove an item from the vector index."""
+        if memory_id in self._entries:
+            del self._entries[memory_id]
+            logger.debug(f"Removed {memory_id} from vector index")
+            return True
+        return False
+
+    async def search(  # type: ignore[override]
+        self,
+        query: Any,
+        limit: int = 10,
+        min_similarity: float = 0.0,
+        **kwargs: Any,
+    ) -> list[VectorIndexEntry]:
+        """
+        Search for similar items using vector similarity.
+
+        Args:
+            query: Query embedding vector
+            limit: Maximum results to return
+            min_similarity: Minimum similarity threshold (0-1)
+            **kwargs: Additional filter parameters
+
+        Returns:
+            List of matching entries sorted by similarity
+        """
+        if not isinstance(query, list) or not query:
+            return []
+
+        results: list[tuple[float, VectorIndexEntry]] = []
+
+        for entry in self._entries.values():
+            if not entry.embedding:
+                continue
+
+            similarity = self._cosine_similarity(query, entry.embedding)
+            if similarity >= min_similarity:
+                results.append((similarity, entry))
+
+        # Sort by similarity descending
+        results.sort(key=lambda x: x[0], reverse=True)
+
+        # Apply memory type filter if provided
+        memory_type = kwargs.get("memory_type")
+        if memory_type:
+            results = [(s, e) for s, e in results if e.memory_type == memory_type]
+
+        # Store similarity in metadata for the returned entries
+        output = []
+        for similarity, entry in results[:limit]:
+            entry.metadata["similarity"] = similarity
+            output.append(entry)
+
+        logger.debug(f"Vector search returned {len(output)} results")
+        return output
+
+    async def clear(self) -> int:
+        """Clear all entries from the index."""
+        count = len(self._entries)
+        self._entries.clear()
+        logger.info(f"Cleared {count} entries from vector index")
+        return count
+
+    async def count(self) -> int:
+        """Get the number of entries in the index."""
+        return len(self._entries)
+
+    def _cosine_similarity(self, a: list[float], b: list[float]) -> float:
+        """Calculate cosine similarity between two vectors."""
+        if len(a) != len(b) or len(a) == 0:
+            return 0.0
+
+        dot_product = sum(x * y for x, y in zip(a, b, strict=True))
+        norm_a = sum(x * x for x in a) ** 0.5
+        norm_b = sum(x * x for x in b) ** 0.5
+
+        if norm_a == 0 or norm_b == 0:
+            return 0.0
+
+        return dot_product / (norm_a * norm_b)
+
+    def _get_memory_type(self, item: T) -> MemoryType:
+        """Get the memory type for an item."""
+        if isinstance(item, Episode):
+            return MemoryType.EPISODIC
+        elif isinstance(item, Fact):
+            return MemoryType.SEMANTIC
+        elif isinstance(item, Procedure):
+            return MemoryType.PROCEDURAL
+        return MemoryType.WORKING
+
+
+class TemporalIndex(MemoryIndex[T]):
+    """
+    Time-based index for efficient temporal queries.
+
+    Supports:
+    - Range queries (between timestamps)
+    - Recent items (within last N seconds/hours/days)
+    - Oldest/newest sorting
+    """
+
+    def __init__(self) -> None:
+        """Initialize the temporal index."""
+        self._entries: dict[UUID, TemporalIndexEntry] = {}
+        # Sorted list for efficient range queries
+        self._sorted_entries: list[tuple[datetime, UUID]] = []
+        logger.info("Initialized TemporalIndex")
+
+    async def add(self, item: T) -> TemporalIndexEntry:
+        """
+        Add an item to the temporal index.
+
+        Args:
+            item: Memory item with timestamp
+
+        Returns:
+            The created index entry
+        """
+        # Get timestamp from various possible fields
+        timestamp = self._get_timestamp(item)
+
+        entry = TemporalIndexEntry(
+            memory_id=item.id,
+            memory_type=self._get_memory_type(item),
+            timestamp=timestamp,
+        )
+
+        self._entries[item.id] = entry
+        self._insert_sorted(timestamp, item.id)
+
+        logger.debug(f"Added {item.id} to temporal index at {timestamp}")
+        return entry
+
+    async def remove(self, memory_id: UUID) -> bool:
+        """Remove an item from the temporal index."""
+        if memory_id not in self._entries:
+            return False
+
+        self._entries.pop(memory_id)
+        self._sorted_entries = [
+            (ts, mid) for ts, mid in self._sorted_entries if mid != memory_id
+        ]
+
+        logger.debug(f"Removed {memory_id} from temporal index")
+        return True
+
+    async def search(  # type: ignore[override]
+        self,
+        query: Any,
+        limit: int = 10,
+        start_time: datetime | None = None,
+        end_time: datetime | None = None,
+        recent_seconds: float | None = None,
+        order: str = "desc",
+        **kwargs: Any,
+    ) -> list[TemporalIndexEntry]:
+        """
+        Search for items by time.
+
+        Args:
+            query: Ignored for temporal search
+            limit: Maximum results to return
+            start_time: Start of time range
+            end_time: End of time range
+            recent_seconds: Get items from last N seconds
+            order: Sort order ("asc" or "desc")
+            **kwargs: Additional filter parameters
+
+        Returns:
+            List of matching entries sorted by time
+        """
+        if recent_seconds is not None:
+            start_time = _utcnow() - timedelta(seconds=recent_seconds)
+            end_time = _utcnow()
+
+        # Filter by time range
+        results: list[TemporalIndexEntry] = []
+        for entry in self._entries.values():
+            if start_time and entry.timestamp < start_time:
+                continue
+            if end_time and entry.timestamp > end_time:
+                continue
+            results.append(entry)
+
+        # Apply memory type filter if provided
+        memory_type = kwargs.get("memory_type")
+        if memory_type:
+            results = [e for e in results if e.memory_type == memory_type]
+
+        # Sort by timestamp
+        results.sort(key=lambda e: e.timestamp, reverse=(order == "desc"))
+
+        logger.debug(f"Temporal search returned {min(len(results), limit)} results")
+        return results[:limit]
+
+    async def clear(self) -> int:
+        """Clear all entries from the index."""
+        count = len(self._entries)
+        self._entries.clear()
+        self._sorted_entries.clear()
+        logger.info(f"Cleared {count} entries from temporal index")
+        return count
+
+    async def count(self) -> int:
+        """Get the number of entries in the index."""
+        return len(self._entries)
+
+    def _insert_sorted(self, timestamp: datetime, memory_id: UUID) -> None:
+        """Insert entry maintaining sorted order."""
+        # Binary search insert for efficiency
+        low, high = 0, len(self._sorted_entries)
+        while low < high:
+            mid = (low + high) // 2
+            if self._sorted_entries[mid][0] < timestamp:
+                low = mid + 1
+            else:
+                high = mid
+        self._sorted_entries.insert(low, (timestamp, memory_id))
+
+    def _get_timestamp(self, item: T) -> datetime:
+        """Get the relevant timestamp for an item."""
+        if hasattr(item, "occurred_at"):
+            return item.occurred_at
+        if hasattr(item, "first_learned"):
+            return item.first_learned
+        if hasattr(item, "last_used") and item.last_used:
+            return item.last_used
+        if hasattr(item, "created_at"):
+            return item.created_at
+        return _utcnow()
+
+    def _get_memory_type(self, item: T) -> MemoryType:
+        """Get the memory type for an item."""
+        if isinstance(item, Episode):
+            return MemoryType.EPISODIC
+        elif isinstance(item, Fact):
+            return MemoryType.SEMANTIC
+        elif isinstance(item, Procedure):
+            return MemoryType.PROCEDURAL
+        return MemoryType.WORKING
+
+
+class EntityIndex(MemoryIndex[T]):
+    """
+    Entity-based index for lookups by entities mentioned in memories.
+
+    Supports:
+    - Single entity lookup
+    - Multi-entity intersection
+    - Entity type filtering
+    """
+
+    def __init__(self) -> None:
+        """Initialize the entity index."""
+        # Main storage
+        self._entries: dict[UUID, EntityIndexEntry] = {}
+        # Inverted index: entity -> set of memory IDs
+        self._entity_to_memories: dict[str, set[UUID]] = {}
+        # Memory to entities mapping
+        self._memory_to_entities: dict[UUID, set[str]] = {}
+        logger.info("Initialized EntityIndex")
+
+    async def add(self, item: T) -> EntityIndexEntry:
+        """
+        Add an item to the entity index.
+
+        Args:
+            item: Memory item with entity information
+
+        Returns:
+            The created index entry
+        """
+        entities = self._extract_entities(item)
+
+        # Create entry for the primary entity (or first one)
+        primary_entity = entities[0] if entities else ("unknown", "unknown")
+
+        entry = EntityIndexEntry(
+            memory_id=item.id,
+            memory_type=self._get_memory_type(item),
+            entity_type=primary_entity[0],
+            entity_value=primary_entity[1],
+        )
+
+        self._entries[item.id] = entry
+
+        # Update inverted indices
+        entity_keys = {f"{etype}:{evalue}" for etype, evalue in entities}
+        self._memory_to_entities[item.id] = entity_keys
+
+        for entity_key in entity_keys:
+            if entity_key not in self._entity_to_memories:
+                self._entity_to_memories[entity_key] = set()
+            self._entity_to_memories[entity_key].add(item.id)
+
+        logger.debug(f"Added {item.id} to entity index with {len(entities)} entities")
+        return entry
+
+    async def remove(self, memory_id: UUID) -> bool:
+        """Remove an item from the entity index."""
+        if memory_id not in self._entries:
+            return False
+
+        # Remove from inverted index
+        if memory_id in self._memory_to_entities:
+            for entity_key in self._memory_to_entities[memory_id]:
+                if entity_key in self._entity_to_memories:
+                    self._entity_to_memories[entity_key].discard(memory_id)
+                    if not self._entity_to_memories[entity_key]:
+                        del self._entity_to_memories[entity_key]
+            del self._memory_to_entities[memory_id]
+
+        del self._entries[memory_id]
+        logger.debug(f"Removed {memory_id} from entity index")
+        return True
+
+    async def search(  # type: ignore[override]
+        self,
+        query: Any,
+        limit: int = 10,
+        entity_type: str | None = None,
+        entity_value: str | None = None,
+        entities: list[tuple[str, str]] | None = None,
+        match_all: bool = False,
+        **kwargs: Any,
+    ) -> list[EntityIndexEntry]:
+        """
+        Search for items by entity.
+
+        Args:
+            query: Entity value to search (if entity_type not specified)
+            limit: Maximum results to return
+            entity_type: Type of entity to filter
+            entity_value: Specific entity value
+            entities: List of (type, value) tuples to match
+            match_all: If True, require all entities to match
+            **kwargs: Additional filter parameters
+
+        Returns:
+            List of matching entries
+        """
+        matching_ids: set[UUID] | None = None
+
+        # Handle single entity query
+        if entity_type and entity_value:
+            entities = [(entity_type, entity_value)]
+        elif entity_value is None and isinstance(query, str):
+            # Search across all entity types
+            entity_value = query
+
+        if entities:
+            for etype, evalue in entities:
+                entity_key = f"{etype}:{evalue}"
+                if entity_key in self._entity_to_memories:
+                    ids = self._entity_to_memories[entity_key]
+                    if matching_ids is None:
+                        matching_ids = ids.copy()
+                    elif match_all:
+                        matching_ids &= ids
+                    else:
+                        matching_ids |= ids
+                elif match_all:
+                    # Required entity not found
+                    matching_ids = set()
+                    break
+        elif entity_value:
+            # Search for value across all types
+            matching_ids = set()
+            for entity_key, ids in self._entity_to_memories.items():
+                if entity_value.lower() in entity_key.lower():
+                    matching_ids |= ids
+
+        if matching_ids is None:
+            matching_ids = set(self._entries.keys())
+
+        # Apply memory type filter if provided
+        memory_type = kwargs.get("memory_type")
+        results = []
+        for mid in matching_ids:
+            if mid in self._entries:
+                entry = self._entries[mid]
+                if memory_type and entry.memory_type != memory_type:
+                    continue
+                results.append(entry)
+
+        logger.debug(f"Entity search returned {min(len(results), limit)} results")
+        return results[:limit]
+
+    async def clear(self) -> int:
+        """Clear all entries from the index."""
+        count = len(self._entries)
+        self._entries.clear()
+        self._entity_to_memories.clear()
+        self._memory_to_entities.clear()
+        logger.info(f"Cleared {count} entries from entity index")
+        return count
+
+    async def count(self) -> int:
+        """Get the number of entries in the index."""
+        return len(self._entries)
+
+    async def get_entities(self, memory_id: UUID) -> list[tuple[str, str]]:
+        """Get all entities for a memory item."""
+        if memory_id not in self._memory_to_entities:
+            return []
+
+        entities = []
+        for entity_key in self._memory_to_entities[memory_id]:
+            if ":" in entity_key:
+                etype, evalue = entity_key.split(":", 1)
+                entities.append((etype, evalue))
+        return entities
+
+    def _extract_entities(self, item: T) -> list[tuple[str, str]]:
+        """Extract entities from a memory item."""
+        entities: list[tuple[str, str]] = []
+
+        if isinstance(item, Episode):
+            # Extract from task type and context
+            entities.append(("task_type", item.task_type))
+            if item.project_id:
+                entities.append(("project", str(item.project_id)))
+            if item.agent_instance_id:
+                entities.append(("agent_instance", str(item.agent_instance_id)))
+            if item.agent_type_id:
+                entities.append(("agent_type", str(item.agent_type_id)))
+
+        elif isinstance(item, Fact):
+            # Subject and object are entities
+            entities.append(("subject", item.subject))
+            entities.append(("object", item.object))
+            if item.project_id:
+                entities.append(("project", str(item.project_id)))
+
+        elif isinstance(item, Procedure):
+            entities.append(("procedure", item.name))
+            if item.project_id:
+                entities.append(("project", str(item.project_id)))
+            if item.agent_type_id:
+                entities.append(("agent_type", str(item.agent_type_id)))
+
+        return entities
+
+    def _get_memory_type(self, item: T) -> MemoryType:
+        """Get the memory type for an item."""
+        if isinstance(item, Episode):
+            return MemoryType.EPISODIC
+        elif isinstance(item, Fact):
+            return MemoryType.SEMANTIC
+        elif isinstance(item, Procedure):
+            return MemoryType.PROCEDURAL
+        return MemoryType.WORKING
+
+
+class OutcomeIndex(MemoryIndex[T]):
+    """
+    Outcome-based index for filtering by success/failure.
+
+    Primarily used for episodes and procedures.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the outcome index."""
+        self._entries: dict[UUID, OutcomeIndexEntry] = {}
+        # Inverted index by outcome
+        self._outcome_to_memories: dict[Outcome, set[UUID]] = {
+            Outcome.SUCCESS: set(),
+            Outcome.FAILURE: set(),
+            Outcome.PARTIAL: set(),
+        }
+        logger.info("Initialized OutcomeIndex")
+
+    async def add(self, item: T) -> OutcomeIndexEntry:
+        """
+        Add an item to the outcome index.
+
+        Args:
+            item: Memory item with outcome information
+
+        Returns:
+            The created index entry
+        """
+        outcome = self._get_outcome(item)
+
+        entry = OutcomeIndexEntry(
+            memory_id=item.id,
+            memory_type=self._get_memory_type(item),
+            outcome=outcome,
+        )
+
+        self._entries[item.id] = entry
+        self._outcome_to_memories[outcome].add(item.id)
+
+        logger.debug(f"Added {item.id} to outcome index with {outcome.value}")
+        return entry
+
+    async def remove(self, memory_id: UUID) -> bool:
+        """Remove an item from the outcome index."""
+        if memory_id not in self._entries:
+            return False
+
+        entry = self._entries.pop(memory_id)
+        self._outcome_to_memories[entry.outcome].discard(memory_id)
+
+        logger.debug(f"Removed {memory_id} from outcome index")
+        return True
+
+    async def search(  # type: ignore[override]
+        self,
+        query: Any,
+        limit: int = 10,
+        outcome: Outcome | None = None,
+        outcomes: list[Outcome] | None = None,
+        **kwargs: Any,
+    ) -> list[OutcomeIndexEntry]:
+        """
+        Search for items by outcome.
+
+        Args:
+            query: Ignored for outcome search
+            limit: Maximum results to return
+            outcome: Single outcome to filter
+            outcomes: Multiple outcomes to filter (OR)
+            **kwargs: Additional filter parameters
+
+        Returns:
+            List of matching entries
+        """
+        if outcome:
+            outcomes = [outcome]
+
+        if outcomes:
+            matching_ids: set[UUID] = set()
+            for o in outcomes:
+                matching_ids |= self._outcome_to_memories.get(o, set())
+        else:
+            matching_ids = set(self._entries.keys())
+
+        # Apply memory type filter if provided
+        memory_type = kwargs.get("memory_type")
+        results = []
+        for mid in matching_ids:
+            if mid in self._entries:
+                entry = self._entries[mid]
+                if memory_type and entry.memory_type != memory_type:
+                    continue
+                results.append(entry)
+
+        logger.debug(f"Outcome search returned {min(len(results), limit)} results")
+        return results[:limit]
+
+    async def clear(self) -> int:
+        """Clear all entries from the index."""
+        count = len(self._entries)
+        self._entries.clear()
+        for outcome in self._outcome_to_memories:
+            self._outcome_to_memories[outcome].clear()
+        logger.info(f"Cleared {count} entries from outcome index")
+        return count
+
+    async def count(self) -> int:
+        """Get the number of entries in the index."""
+        return len(self._entries)
+
+    async def get_outcome_stats(self) -> dict[Outcome, int]:
+        """Get statistics on outcomes."""
+        return {outcome: len(ids) for outcome, ids in self._outcome_to_memories.items()}
+
+    def _get_outcome(self, item: T) -> Outcome:
+        """Get the outcome for an item."""
+        if isinstance(item, Episode):
+            return item.outcome
+        elif isinstance(item, Procedure):
+            # Derive from success rate
+            if item.success_rate >= 0.8:
+                return Outcome.SUCCESS
+            elif item.success_rate <= 0.2:
+                return Outcome.FAILURE
+            return Outcome.PARTIAL
+        return Outcome.SUCCESS
+
+    def _get_memory_type(self, item: T) -> MemoryType:
+        """Get the memory type for an item."""
+        if isinstance(item, Episode):
+            return MemoryType.EPISODIC
+        elif isinstance(item, Fact):
+            return MemoryType.SEMANTIC
+        elif isinstance(item, Procedure):
+            return MemoryType.PROCEDURAL
+        return MemoryType.WORKING
+
+
+@dataclass
+class MemoryIndexer:
+    """
+    Unified indexer that manages all index types.
+
+    Provides a single interface for indexing and searching across
+    multiple index types.
+    """
+
+    vector_index: VectorIndex[Any] = field(default_factory=VectorIndex)
+    temporal_index: TemporalIndex[Any] = field(default_factory=TemporalIndex)
+    entity_index: EntityIndex[Any] = field(default_factory=EntityIndex)
+    outcome_index: OutcomeIndex[Any] = field(default_factory=OutcomeIndex)
+
+    async def index(self, item: Episode | Fact | Procedure) -> dict[str, IndexEntry]:
+        """
+        Index an item across all applicable indices.
+
+        Args:
+            item: Memory item to index
+
+        Returns:
+            Dictionary of index type to entry
+        """
+        results: dict[str, IndexEntry] = {}
+
+        # Vector index (if embedding present)
+        if getattr(item, "embedding", None):
+            results["vector"] = await self.vector_index.add(item)
+
+        # Temporal index
+        results["temporal"] = await self.temporal_index.add(item)
+
+        # Entity index
+        results["entity"] = await self.entity_index.add(item)
+
+        # Outcome index (for episodes and procedures)
+        if isinstance(item, (Episode, Procedure)):
+            results["outcome"] = await self.outcome_index.add(item)
+
+        logger.info(
+            f"Indexed {item.id} across {len(results)} indices: {list(results.keys())}"
+        )
+        return results
+
+    async def remove(self, memory_id: UUID) -> dict[str, bool]:
+        """
+        Remove an item from all indices.
+
+        Args:
+            memory_id: ID of the memory to remove
+
+        Returns:
+            Dictionary of index type to removal success
+        """
+        results = {
+            "vector": await self.vector_index.remove(memory_id),
+            "temporal": await self.temporal_index.remove(memory_id),
+            "entity": await self.entity_index.remove(memory_id),
+            "outcome": await self.outcome_index.remove(memory_id),
+        }
+
+        removed_from = [k for k, v in results.items() if v]
+        if removed_from:
+            logger.info(f"Removed {memory_id} from indices: {removed_from}")
+
+        return results
+
+    async def clear_all(self) -> dict[str, int]:
+        """
+        Clear all indices.
+
+        Returns:
+            Dictionary of index type to count cleared
+        """
+        return {
+            "vector": await self.vector_index.clear(),
+            "temporal": await self.temporal_index.clear(),
+            "entity": await self.entity_index.clear(),
+            "outcome": await self.outcome_index.clear(),
+        }
+
+    async def get_stats(self) -> dict[str, int]:
+        """
+        Get statistics for all indices.
+
+        Returns:
+            Dictionary of index type to entry count
+        """
+        return {
+            "vector": await self.vector_index.count(),
+            "temporal": await self.temporal_index.count(),
+            "entity": await self.entity_index.count(),
+            "outcome": await self.outcome_index.count(),
+        }
+
+
+# Singleton indexer instance
+_indexer: MemoryIndexer | None = None
+
+
+def get_memory_indexer() -> MemoryIndexer:
+    """Get the singleton memory indexer instance."""
+    global _indexer
+    if _indexer is None:
+        _indexer = MemoryIndexer()
+    return _indexer

backend/app/services/memory/indexing/retrieval.py

@@ -0,0 +1,750 @@
+# app/services/memory/indexing/retrieval.py
+"""
+Memory Retrieval Engine.
+
+Provides hybrid retrieval capabilities combining:
+- Vector similarity search
+- Temporal filtering
+- Entity filtering
+- Outcome filtering
+- Relevance scoring
+- Result caching
+"""
+
+import hashlib
+import logging
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any, TypeVar
+from uuid import UUID
+
+from app.services.memory.types import (
+    Episode,
+    Fact,
+    MemoryType,
+    Outcome,
+    Procedure,
+    RetrievalResult,
+)
+
+from .index import (
+    MemoryIndexer,
+    get_memory_indexer,
+)
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", Episode, Fact, Procedure)
+
+
+def _utcnow() -> datetime:
+    """Get current UTC time as timezone-aware datetime."""
+    return datetime.now(UTC)
+
+
+@dataclass
+class RetrievalQuery:
+    """Query parameters for memory retrieval."""
+
+    # Text/semantic query
+    query_text: str | None = None
+    query_embedding: list[float] | None = None
+
+    # Temporal filters
+    start_time: datetime | None = None
+    end_time: datetime | None = None
+    recent_seconds: float | None = None
+
+    # Entity filters
+    entities: list[tuple[str, str]] | None = None
+    entity_match_all: bool = False
+
+    # Outcome filters
+    outcomes: list[Outcome] | None = None
+
+    # Memory type filter
+    memory_types: list[MemoryType] | None = None
+
+    # Result options
+    limit: int = 10
+    min_relevance: float = 0.0
+
+    # Retrieval mode
+    use_vector: bool = True
+    use_temporal: bool = True
+    use_entity: bool = True
+    use_outcome: bool = True
+
+    def to_cache_key(self) -> str:
+        """Generate a cache key for this query."""
+        key_parts = [
+            self.query_text or "",
+            str(self.start_time),
+            str(self.end_time),
+            str(self.recent_seconds),
+            str(self.entities),
+            str(self.outcomes),
+            str(self.memory_types),
+            str(self.limit),
+            str(self.min_relevance),
+        ]
+        key_string = "|".join(key_parts)
+        return hashlib.sha256(key_string.encode()).hexdigest()[:32]
+
+
+@dataclass
+class ScoredResult:
+    """A retrieval result with relevance score."""
+
+    memory_id: UUID
+    memory_type: MemoryType
+    relevance_score: float
+    score_breakdown: dict[str, float] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class CacheEntry:
+    """A cached retrieval result."""
+
+    results: list[ScoredResult]
+    created_at: datetime
+    ttl_seconds: float
+    query_key: str
+
+    def is_expired(self) -> bool:
+        """Check if this cache entry has expired."""
+        age = (_utcnow() - self.created_at).total_seconds()
+        return age > self.ttl_seconds
+
+
+class RelevanceScorer:
+    """
+    Calculates relevance scores for retrieved memories.
+
+    Combines multiple signals:
+    - Vector similarity (if available)
+    - Temporal recency
+    - Entity match count
+    - Outcome preference
+    - Importance/confidence
+    """
+
+    def __init__(
+        self,
+        vector_weight: float = 0.4,
+        recency_weight: float = 0.2,
+        entity_weight: float = 0.2,
+        outcome_weight: float = 0.1,
+        importance_weight: float = 0.1,
+    ) -> None:
+        """
+        Initialize the relevance scorer.
+
+        Args:
+            vector_weight: Weight for vector similarity (0-1)
+            recency_weight: Weight for temporal recency (0-1)
+            entity_weight: Weight for entity matches (0-1)
+            outcome_weight: Weight for outcome preference (0-1)
+            importance_weight: Weight for importance score (0-1)
+        """
+        total = (
+            vector_weight
+            + recency_weight
+            + entity_weight
+            + outcome_weight
+            + importance_weight
+        )
+        # Normalize weights
+        self.vector_weight = vector_weight / total
+        self.recency_weight = recency_weight / total
+        self.entity_weight = entity_weight / total
+        self.outcome_weight = outcome_weight / total
+        self.importance_weight = importance_weight / total
+
+    def score(
+        self,
+        memory_id: UUID,
+        memory_type: MemoryType,
+        vector_similarity: float | None = None,
+        timestamp: datetime | None = None,
+        entity_match_count: int = 0,
+        entity_total: int = 1,
+        outcome: Outcome | None = None,
+        importance: float = 0.5,
+        preferred_outcomes: list[Outcome] | None = None,
+    ) -> ScoredResult:
+        """
+        Calculate a relevance score for a memory.
+
+        Args:
+            memory_id: ID of the memory
+            memory_type: Type of memory
+            vector_similarity: Similarity score from vector search (0-1)
+            timestamp: Timestamp of the memory
+            entity_match_count: Number of matching entities
+            entity_total: Total entities in query
+            outcome: Outcome of the memory
+            importance: Importance score of the memory (0-1)
+            preferred_outcomes: Outcomes to prefer
+
+        Returns:
+            Scored result with breakdown
+        """
+        breakdown: dict[str, float] = {}
+
+        # Vector similarity score
+        if vector_similarity is not None:
+            breakdown["vector"] = vector_similarity
+        else:
+            breakdown["vector"] = 0.5  # Neutral if no vector
+
+        # Recency score (exponential decay)
+        if timestamp:
+            age_hours = (_utcnow() - timestamp).total_seconds() / 3600
+            # Decay with half-life of 24 hours
+            breakdown["recency"] = 2 ** (-age_hours / 24)
+        else:
+            breakdown["recency"] = 0.5
+
+        # Entity match score
+        if entity_total > 0:
+            breakdown["entity"] = entity_match_count / entity_total
+        else:
+            breakdown["entity"] = 1.0  # No entity filter = full score
+
+        # Outcome score
+        if preferred_outcomes and outcome:
+            breakdown["outcome"] = 1.0 if outcome in preferred_outcomes else 0.0
+        else:
+            breakdown["outcome"] = 0.5  # Neutral if no preference
+
+        # Importance score
+        breakdown["importance"] = importance
+
+        # Calculate weighted sum
+        total_score = (
+            breakdown["vector"] * self.vector_weight
+            + breakdown["recency"] * self.recency_weight
+            + breakdown["entity"] * self.entity_weight
+            + breakdown["outcome"] * self.outcome_weight
+            + breakdown["importance"] * self.importance_weight
+        )
+
+        return ScoredResult(
+            memory_id=memory_id,
+            memory_type=memory_type,
+            relevance_score=total_score,
+            score_breakdown=breakdown,
+        )
+
+
+class RetrievalCache:
+    """
+    In-memory cache for retrieval results.
+
+    Supports TTL-based expiration and LRU eviction.
+    """
+
+    def __init__(
+        self,
+        max_entries: int = 1000,
+        default_ttl_seconds: float = 300,
+    ) -> None:
+        """
+        Initialize the cache.
+
+        Args:
+            max_entries: Maximum cache entries
+            default_ttl_seconds: Default TTL for entries
+        """
+        self._cache: dict[str, CacheEntry] = {}
+        self._max_entries = max_entries
+        self._default_ttl = default_ttl_seconds
+        self._access_order: list[str] = []
+        logger.info(
+            f"Initialized RetrievalCache with max_entries={max_entries}, "
+            f"ttl={default_ttl_seconds}s"
+        )
+
+    def get(self, query_key: str) -> list[ScoredResult] | None:
+        """
+        Get cached results for a query.
+
+        Args:
+            query_key: Cache key for the query
+
+        Returns:
+            Cached results or None if not found/expired
+        """
+        if query_key not in self._cache:
+            return None
+
+        entry = self._cache[query_key]
+        if entry.is_expired():
+            del self._cache[query_key]
+            if query_key in self._access_order:
+                self._access_order.remove(query_key)
+            return None
+
+        # Update access order (LRU)
+        if query_key in self._access_order:
+            self._access_order.remove(query_key)
+        self._access_order.append(query_key)
+
+        logger.debug(f"Cache hit for {query_key}")
+        return entry.results
+
+    def put(
+        self,
+        query_key: str,
+        results: list[ScoredResult],
+        ttl_seconds: float | None = None,
+    ) -> None:
+        """
+        Cache results for a query.
+
+        Args:
+            query_key: Cache key for the query
+            results: Results to cache
+            ttl_seconds: TTL for this entry (or default)
+        """
+        # Evict if at capacity
+        while len(self._cache) >= self._max_entries and self._access_order:
+            oldest_key = self._access_order.pop(0)
+            if oldest_key in self._cache:
+                del self._cache[oldest_key]
+
+        entry = CacheEntry(
+            results=results,
+            created_at=_utcnow(),
+            ttl_seconds=ttl_seconds or self._default_ttl,
+            query_key=query_key,
+        )
+
+        self._cache[query_key] = entry
+        self._access_order.append(query_key)
+        logger.debug(f"Cached {len(results)} results for {query_key}")
+
+    def invalidate(self, query_key: str) -> bool:
+        """
+        Invalidate a specific cache entry.
+
+        Args:
+            query_key: Cache key to invalidate
+
+        Returns:
+            True if entry was found and removed
+        """
+        if query_key in self._cache:
+            del self._cache[query_key]
+            if query_key in self._access_order:
+                self._access_order.remove(query_key)
+            return True
+        return False
+
+    def invalidate_by_memory(self, memory_id: UUID) -> int:
+        """
+        Invalidate all cache entries containing a specific memory.
+
+        Args:
+            memory_id: Memory ID to invalidate
+
+        Returns:
+            Number of entries invalidated
+        """
+        keys_to_remove = []
+        for key, entry in self._cache.items():
+            if any(r.memory_id == memory_id for r in entry.results):
+                keys_to_remove.append(key)
+
+        for key in keys_to_remove:
+            self.invalidate(key)
+
+        if keys_to_remove:
+            logger.debug(
+                f"Invalidated {len(keys_to_remove)} cache entries for {memory_id}"
+            )
+        return len(keys_to_remove)
+
+    def clear(self) -> int:
+        """
+        Clear all cache entries.
+
+        Returns:
+            Number of entries cleared
+        """
+        count = len(self._cache)
+        self._cache.clear()
+        self._access_order.clear()
+        logger.info(f"Cleared {count} cache entries")
+        return count
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get cache statistics."""
+        expired_count = sum(1 for e in self._cache.values() if e.is_expired())
+        return {
+            "total_entries": len(self._cache),
+            "expired_entries": expired_count,
+            "max_entries": self._max_entries,
+            "default_ttl_seconds": self._default_ttl,
+        }
+
+
+class RetrievalEngine:
+    """
+    Hybrid retrieval engine for memory search.
+
+    Combines multiple index types for comprehensive retrieval:
+    - Vector search for semantic similarity
+    - Temporal index for time-based filtering
+    - Entity index for entity-based lookups
+    - Outcome index for success/failure filtering
+
+    Results are scored and ranked using relevance scoring.
+    """
+
+    def __init__(
+        self,
+        indexer: MemoryIndexer | None = None,
+        scorer: RelevanceScorer | None = None,
+        cache: RetrievalCache | None = None,
+        enable_cache: bool = True,
+    ) -> None:
+        """
+        Initialize the retrieval engine.
+
+        Args:
+            indexer: Memory indexer (defaults to singleton)
+            scorer: Relevance scorer (defaults to new instance)
+            cache: Retrieval cache (defaults to new instance)
+            enable_cache: Whether to enable result caching
+        """
+        self._indexer = indexer or get_memory_indexer()
+        self._scorer = scorer or RelevanceScorer()
+        self._cache = cache or RetrievalCache() if enable_cache else None
+        self._enable_cache = enable_cache
+        logger.info(f"Initialized RetrievalEngine with cache={enable_cache}")
+
+    async def retrieve(
+        self,
+        query: RetrievalQuery,
+        use_cache: bool = True,
+    ) -> RetrievalResult[ScoredResult]:
+        """
+        Retrieve relevant memories using hybrid search.
+
+        Args:
+            query: Retrieval query parameters
+            use_cache: Whether to use cached results
+
+        Returns:
+            Retrieval result with scored items
+        """
+        start_time = _utcnow()
+
+        # Check cache
+        cache_key = query.to_cache_key()
+        if use_cache and self._cache:
+            cached = self._cache.get(cache_key)
+            if cached:
+                latency = (_utcnow() - start_time).total_seconds() * 1000
+                return RetrievalResult(
+                    items=cached,
+                    total_count=len(cached),
+                    query=query.query_text or "",
+                    retrieval_type="cached",
+                    latency_ms=latency,
+                    metadata={"cache_hit": True},
+                )
+
+        # Collect candidates from each index
+        candidates: dict[UUID, dict[str, Any]] = {}
+
+        # Vector search
+        if query.use_vector and query.query_embedding:
+            vector_results = await self._indexer.vector_index.search(
+                query=query.query_embedding,
+                limit=query.limit * 3,  # Get more for filtering
+                min_similarity=query.min_relevance,
+                memory_type=query.memory_types[0] if query.memory_types else None,
+            )
+            for entry in vector_results:
+                if entry.memory_id not in candidates:
+                    candidates[entry.memory_id] = {
+                        "memory_type": entry.memory_type,
+                        "sources": [],
+                    }
+                candidates[entry.memory_id]["vector_similarity"] = entry.metadata.get(
+                    "similarity", 0.5
+                )
+                candidates[entry.memory_id]["sources"].append("vector")
+
+        # Temporal search
+        if query.use_temporal and (
+            query.start_time or query.end_time or query.recent_seconds
+        ):
+            temporal_results = await self._indexer.temporal_index.search(
+                query=None,
+                limit=query.limit * 3,
+                start_time=query.start_time,
+                end_time=query.end_time,
+                recent_seconds=query.recent_seconds,
+                memory_type=query.memory_types[0] if query.memory_types else None,
+            )
+            for temporal_entry in temporal_results:
+                if temporal_entry.memory_id not in candidates:
+                    candidates[temporal_entry.memory_id] = {
+                        "memory_type": temporal_entry.memory_type,
+                        "sources": [],
+                    }
+                candidates[temporal_entry.memory_id]["timestamp"] = (
+                    temporal_entry.timestamp
+                )
+                candidates[temporal_entry.memory_id]["sources"].append("temporal")
+
+        # Entity search
+        if query.use_entity and query.entities:
+            entity_results = await self._indexer.entity_index.search(
+                query=None,
+                limit=query.limit * 3,
+                entities=query.entities,
+                match_all=query.entity_match_all,
+                memory_type=query.memory_types[0] if query.memory_types else None,
+            )
+            for entity_entry in entity_results:
+                if entity_entry.memory_id not in candidates:
+                    candidates[entity_entry.memory_id] = {
+                        "memory_type": entity_entry.memory_type,
+                        "sources": [],
+                    }
+                # Count entity matches
+                entity_count = candidates[entity_entry.memory_id].get(
+                    "entity_match_count", 0
+                )
+                candidates[entity_entry.memory_id]["entity_match_count"] = (
+                    entity_count + 1
+                )
+                candidates[entity_entry.memory_id]["sources"].append("entity")
+
+        # Outcome search
+        if query.use_outcome and query.outcomes:
+            outcome_results = await self._indexer.outcome_index.search(
+                query=None,
+                limit=query.limit * 3,
+                outcomes=query.outcomes,
+                memory_type=query.memory_types[0] if query.memory_types else None,
+            )
+            for outcome_entry in outcome_results:
+                if outcome_entry.memory_id not in candidates:
+                    candidates[outcome_entry.memory_id] = {
+                        "memory_type": outcome_entry.memory_type,
+                        "sources": [],
+                    }
+                candidates[outcome_entry.memory_id]["outcome"] = outcome_entry.outcome
+                candidates[outcome_entry.memory_id]["sources"].append("outcome")
+
+        # Score and rank candidates
+        scored_results: list[ScoredResult] = []
+        entity_total = len(query.entities) if query.entities else 1
+
+        for memory_id, data in candidates.items():
+            scored = self._scorer.score(
+                memory_id=memory_id,
+                memory_type=data["memory_type"],
+                vector_similarity=data.get("vector_similarity"),
+                timestamp=data.get("timestamp"),
+                entity_match_count=data.get("entity_match_count", 0),
+                entity_total=entity_total,
+                outcome=data.get("outcome"),
+                preferred_outcomes=query.outcomes,
+            )
+            scored.metadata["sources"] = data.get("sources", [])
+
+            # Filter by minimum relevance
+            if scored.relevance_score >= query.min_relevance:
+                scored_results.append(scored)
+
+        # Sort by relevance score
+        scored_results.sort(key=lambda x: x.relevance_score, reverse=True)
+
+        # Apply limit
+        final_results = scored_results[: query.limit]
+
+        # Cache results
+        if use_cache and self._cache and final_results:
+            self._cache.put(cache_key, final_results)
+
+        latency = (_utcnow() - start_time).total_seconds() * 1000
+
+        logger.info(
+            f"Retrieved {len(final_results)} results from {len(candidates)} candidates "
+            f"in {latency:.2f}ms"
+        )
+
+        return RetrievalResult(
+            items=final_results,
+            total_count=len(candidates),
+            query=query.query_text or "",
+            retrieval_type="hybrid",
+            latency_ms=latency,
+            metadata={
+                "cache_hit": False,
+                "candidates_count": len(candidates),
+                "filtered_count": len(scored_results),
+            },
+        )
+
+    async def retrieve_similar(
+        self,
+        embedding: list[float],
+        limit: int = 10,
+        min_similarity: float = 0.5,
+        memory_types: list[MemoryType] | None = None,
+    ) -> RetrievalResult[ScoredResult]:
+        """
+        Retrieve memories similar to a given embedding.
+
+        Args:
+            embedding: Query embedding
+            limit: Maximum results
+            min_similarity: Minimum similarity threshold
+            memory_types: Filter by memory types
+
+        Returns:
+            Retrieval result with scored items
+        """
+        query = RetrievalQuery(
+            query_embedding=embedding,
+            limit=limit,
+            min_relevance=min_similarity,
+            memory_types=memory_types,
+            use_temporal=False,
+            use_entity=False,
+            use_outcome=False,
+        )
+        return await self.retrieve(query)
+
+    async def retrieve_recent(
+        self,
+        hours: float = 24,
+        limit: int = 10,
+        memory_types: list[MemoryType] | None = None,
+    ) -> RetrievalResult[ScoredResult]:
+        """
+        Retrieve recent memories.
+
+        Args:
+            hours: Number of hours to look back
+            limit: Maximum results
+            memory_types: Filter by memory types
+
+        Returns:
+            Retrieval result with scored items
+        """
+        query = RetrievalQuery(
+            recent_seconds=hours * 3600,
+            limit=limit,
+            memory_types=memory_types,
+            use_vector=False,
+            use_entity=False,
+            use_outcome=False,
+        )
+        return await self.retrieve(query)
+
+    async def retrieve_by_entity(
+        self,
+        entity_type: str,
+        entity_value: str,
+        limit: int = 10,
+        memory_types: list[MemoryType] | None = None,
+    ) -> RetrievalResult[ScoredResult]:
+        """
+        Retrieve memories by entity.
+
+        Args:
+            entity_type: Type of entity
+            entity_value: Entity value
+            limit: Maximum results
+            memory_types: Filter by memory types
+
+        Returns:
+            Retrieval result with scored items
+        """
+        query = RetrievalQuery(
+            entities=[(entity_type, entity_value)],
+            limit=limit,
+            memory_types=memory_types,
+            use_vector=False,
+            use_temporal=False,
+            use_outcome=False,
+        )
+        return await self.retrieve(query)
+
+    async def retrieve_successful(
+        self,
+        limit: int = 10,
+        memory_types: list[MemoryType] | None = None,
+    ) -> RetrievalResult[ScoredResult]:
+        """
+        Retrieve successful memories.
+
+        Args:
+            limit: Maximum results
+            memory_types: Filter by memory types
+
+        Returns:
+            Retrieval result with scored items
+        """
+        query = RetrievalQuery(
+            outcomes=[Outcome.SUCCESS],
+            limit=limit,
+            memory_types=memory_types,
+            use_vector=False,
+            use_temporal=False,
+            use_entity=False,
+        )
+        return await self.retrieve(query)
+
+    def invalidate_cache(self) -> int:
+        """
+        Invalidate all cached results.
+
+        Returns:
+            Number of entries invalidated
+        """
+        if self._cache:
+            return self._cache.clear()
+        return 0
+
+    def invalidate_cache_for_memory(self, memory_id: UUID) -> int:
+        """
+        Invalidate cache entries containing a specific memory.
+
+        Args:
+            memory_id: Memory ID to invalidate
+
+        Returns:
+            Number of entries invalidated
+        """
+        if self._cache:
+            return self._cache.invalidate_by_memory(memory_id)
+        return 0
+
+    def get_cache_stats(self) -> dict[str, Any]:
+        """Get cache statistics."""
+        if self._cache:
+            return self._cache.get_stats()
+        return {"enabled": False}
+
+
+# Singleton retrieval engine instance
+_engine: RetrievalEngine | None = None
+
+
+def get_retrieval_engine() -> RetrievalEngine:
+    """Get the singleton retrieval engine instance."""
+    global _engine
+    if _engine is None:
+        _engine = RetrievalEngine()
+    return _engine

backend/app/services/memory/integration/__init__.py

@@ -0,0 +1,19 @@
+# app/services/memory/integration/__init__.py
+"""
+Memory Integration Module.
+
+Provides integration between the agent memory system and other Syndarix components:
+- Context Engine: Memory as context source
+- Agent Lifecycle: Spawn, pause, resume, terminate hooks
+"""
+
+from .context_source import MemoryContextSource, get_memory_context_source
+from .lifecycle import AgentLifecycleManager, LifecycleHooks, get_lifecycle_manager
+
+__all__ = [
+    "AgentLifecycleManager",
+    "LifecycleHooks",
+    "MemoryContextSource",
+    "get_lifecycle_manager",
+    "get_memory_context_source",
+]

backend/app/services/memory/integration/context_source.py

@@ -0,0 +1,402 @@
+# app/services/memory/integration/context_source.py
+"""
+Memory Context Source.
+
+Provides agent memory as a context source for the Context Engine.
+Retrieves relevant memories based on query and converts them to MemoryContext objects.
+"""
+
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.services.context.types.memory import MemoryContext
+from app.services.memory.episodic import EpisodicMemory
+from app.services.memory.procedural import ProceduralMemory
+from app.services.memory.semantic import SemanticMemory
+from app.services.memory.working import WorkingMemory
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class MemoryFetchConfig:
+    """Configuration for memory fetching."""
+
+    # Limits per memory type
+    working_limit: int = 10
+    episodic_limit: int = 10
+    semantic_limit: int = 15
+    procedural_limit: int = 5
+
+    # Time ranges
+    episodic_days_back: int = 30
+    min_relevance: float = 0.3
+
+    # Which memory types to include
+    include_working: bool = True
+    include_episodic: bool = True
+    include_semantic: bool = True
+    include_procedural: bool = True
+
+
+@dataclass
+class MemoryFetchResult:
+    """Result of memory fetch operation."""
+
+    contexts: list[MemoryContext]
+    by_type: dict[str, int]
+    fetch_time_ms: float
+    query: str
+
+
+class MemoryContextSource:
+    """
+    Source for memory context in the Context Engine.
+
+    This service retrieves relevant memories based on a query and
+    converts them to MemoryContext objects for context assembly.
+    It coordinates between all memory types (working, episodic,
+    semantic, procedural) to provide a comprehensive memory context.
+    """
+
+    def __init__(
+        self,
+        session: AsyncSession,
+        embedding_generator: Any | None = None,
+    ) -> None:
+        """
+        Initialize the memory context source.
+
+        Args:
+            session: Database session
+            embedding_generator: Optional embedding generator for semantic search
+        """
+        self._session = session
+        self._embedding_generator = embedding_generator
+
+        # Lazy-initialized memory services
+        self._episodic: EpisodicMemory | None = None
+        self._semantic: SemanticMemory | None = None
+        self._procedural: ProceduralMemory | None = None
+
+    async def _get_episodic(self) -> EpisodicMemory:
+        """Get or create episodic memory service."""
+        if self._episodic is None:
+            self._episodic = await EpisodicMemory.create(
+                self._session,
+                self._embedding_generator,
+            )
+        return self._episodic
+
+    async def _get_semantic(self) -> SemanticMemory:
+        """Get or create semantic memory service."""
+        if self._semantic is None:
+            self._semantic = await SemanticMemory.create(
+                self._session,
+                self._embedding_generator,
+            )
+        return self._semantic
+
+    async def _get_procedural(self) -> ProceduralMemory:
+        """Get or create procedural memory service."""
+        if self._procedural is None:
+            self._procedural = await ProceduralMemory.create(
+                self._session,
+                self._embedding_generator,
+            )
+        return self._procedural
+
+    async def fetch_context(
+        self,
+        query: str,
+        project_id: UUID,
+        agent_instance_id: UUID | None = None,
+        agent_type_id: UUID | None = None,
+        session_id: str | None = None,
+        config: MemoryFetchConfig | None = None,
+    ) -> MemoryFetchResult:
+        """
+        Fetch relevant memories as context.
+
+        This is the main entry point for the Context Engine integration.
+        It searches across all memory types and returns relevant memories
+        as MemoryContext objects.
+
+        Args:
+            query: Search query for finding relevant memories
+            project_id: Project scope
+            agent_instance_id: Optional agent instance scope
+            agent_type_id: Optional agent type scope (for procedural)
+            session_id: Optional session ID (for working memory)
+            config: Optional fetch configuration
+
+        Returns:
+            MemoryFetchResult with contexts and metadata
+        """
+        config = config or MemoryFetchConfig()
+        start_time = datetime.now(UTC)
+
+        contexts: list[MemoryContext] = []
+        by_type: dict[str, int] = {
+            "working": 0,
+            "episodic": 0,
+            "semantic": 0,
+            "procedural": 0,
+        }
+
+        # Fetch from working memory (session-scoped)
+        if config.include_working and session_id:
+            try:
+                working_contexts = await self._fetch_working(
+                    query=query,
+                    session_id=session_id,
+                    project_id=project_id,
+                    agent_instance_id=agent_instance_id,
+                    limit=config.working_limit,
+                )
+                contexts.extend(working_contexts)
+                by_type["working"] = len(working_contexts)
+            except Exception as e:
+                logger.warning(f"Failed to fetch working memory: {e}")
+
+        # Fetch from episodic memory
+        if config.include_episodic:
+            try:
+                episodic_contexts = await self._fetch_episodic(
+                    query=query,
+                    project_id=project_id,
+                    agent_instance_id=agent_instance_id,
+                    limit=config.episodic_limit,
+                    days_back=config.episodic_days_back,
+                )
+                contexts.extend(episodic_contexts)
+                by_type["episodic"] = len(episodic_contexts)
+            except Exception as e:
+                logger.warning(f"Failed to fetch episodic memory: {e}")
+
+        # Fetch from semantic memory
+        if config.include_semantic:
+            try:
+                semantic_contexts = await self._fetch_semantic(
+                    query=query,
+                    project_id=project_id,
+                    limit=config.semantic_limit,
+                    min_relevance=config.min_relevance,
+                )
+                contexts.extend(semantic_contexts)
+                by_type["semantic"] = len(semantic_contexts)
+            except Exception as e:
+                logger.warning(f"Failed to fetch semantic memory: {e}")
+
+        # Fetch from procedural memory
+        if config.include_procedural:
+            try:
+                procedural_contexts = await self._fetch_procedural(
+                    query=query,
+                    project_id=project_id,
+                    agent_type_id=agent_type_id,
+                    limit=config.procedural_limit,
+                )
+                contexts.extend(procedural_contexts)
+                by_type["procedural"] = len(procedural_contexts)
+            except Exception as e:
+                logger.warning(f"Failed to fetch procedural memory: {e}")
+
+        # Sort by relevance
+        contexts.sort(key=lambda c: c.relevance_score, reverse=True)
+
+        fetch_time = (datetime.now(UTC) - start_time).total_seconds() * 1000
+
+        logger.debug(
+            f"Fetched {len(contexts)} memory contexts for query '{query[:50]}...' "
+            f"in {fetch_time:.1f}ms"
+        )
+
+        return MemoryFetchResult(
+            contexts=contexts,
+            by_type=by_type,
+            fetch_time_ms=fetch_time,
+            query=query,
+        )
+
+    async def _fetch_working(
+        self,
+        query: str,
+        session_id: str,
+        project_id: UUID,
+        agent_instance_id: UUID | None,
+        limit: int,
+    ) -> list[MemoryContext]:
+        """Fetch from working memory."""
+        working = await WorkingMemory.for_session(
+            session_id=session_id,
+            project_id=str(project_id),
+            agent_instance_id=str(agent_instance_id) if agent_instance_id else None,
+        )
+
+        contexts: list[MemoryContext] = []
+        all_keys = await working.list_keys()
+
+        # Filter keys by query (simple substring match)
+        query_lower = query.lower()
+        matched_keys = [k for k in all_keys if query_lower in k.lower()]
+
+        # If no query match, include all keys (working memory is always relevant)
+        if not matched_keys and query:
+            matched_keys = all_keys
+
+        for key in matched_keys[:limit]:
+            value = await working.get(key)
+            if value is not None:
+                contexts.append(
+                    MemoryContext.from_working_memory(
+                        key=key,
+                        value=value,
+                        source=f"working:{session_id}",
+                        query=query,
+                    )
+                )
+
+        return contexts
+
+    async def _fetch_episodic(
+        self,
+        query: str,
+        project_id: UUID,
+        agent_instance_id: UUID | None,
+        limit: int,
+        days_back: int,
+    ) -> list[MemoryContext]:
+        """Fetch from episodic memory."""
+        episodic = await self._get_episodic()
+
+        # Search for similar episodes
+        episodes = await episodic.search_similar(
+            project_id=project_id,
+            query=query,
+            limit=limit,
+            agent_instance_id=agent_instance_id,
+        )
+
+        # Also get recent episodes if we didn't find enough
+        if len(episodes) < limit // 2:
+            since = datetime.now(UTC) - timedelta(days=days_back)
+            recent = await episodic.get_recent(
+                project_id=project_id,
+                limit=limit,
+                since=since,
+            )
+            # Deduplicate by ID
+            existing_ids = {e.id for e in episodes}
+            for ep in recent:
+                if ep.id not in existing_ids:
+                    episodes.append(ep)
+                    if len(episodes) >= limit:
+                        break
+
+        return [
+            MemoryContext.from_episodic_memory(ep, query=query)
+            for ep in episodes[:limit]
+        ]
+
+    async def _fetch_semantic(
+        self,
+        query: str,
+        project_id: UUID,
+        limit: int,
+        min_relevance: float,
+    ) -> list[MemoryContext]:
+        """Fetch from semantic memory."""
+        semantic = await self._get_semantic()
+
+        facts = await semantic.search_facts(
+            query=query,
+            project_id=project_id,
+            limit=limit,
+            min_confidence=min_relevance,
+        )
+
+        return [
+            MemoryContext.from_semantic_memory(fact, query=query)
+            for fact in facts
+        ]
+
+    async def _fetch_procedural(
+        self,
+        query: str,
+        project_id: UUID,
+        agent_type_id: UUID | None,
+        limit: int,
+    ) -> list[MemoryContext]:
+        """Fetch from procedural memory."""
+        procedural = await self._get_procedural()
+
+        procedures = await procedural.find_matching(
+            context=query,
+            project_id=project_id,
+            agent_type_id=agent_type_id,
+            limit=limit,
+        )
+
+        return [
+            MemoryContext.from_procedural_memory(proc, query=query)
+            for proc in procedures
+        ]
+
+    async def fetch_all_working(
+        self,
+        session_id: str,
+        project_id: UUID,
+        agent_instance_id: UUID | None = None,
+    ) -> list[MemoryContext]:
+        """
+        Fetch all working memory for a session.
+
+        Useful for including entire session state in context.
+
+        Args:
+            session_id: Session ID
+            project_id: Project scope
+            agent_instance_id: Optional agent instance scope
+
+        Returns:
+            List of MemoryContext for all working memory items
+        """
+        working = await WorkingMemory.for_session(
+            session_id=session_id,
+            project_id=str(project_id),
+            agent_instance_id=str(agent_instance_id) if agent_instance_id else None,
+        )
+
+        contexts: list[MemoryContext] = []
+        all_keys = await working.list_keys()
+
+        for key in all_keys:
+            value = await working.get(key)
+            if value is not None:
+                contexts.append(
+                    MemoryContext.from_working_memory(
+                        key=key,
+                        value=value,
+                        source=f"working:{session_id}",
+                    )
+                )
+
+        return contexts
+
+
+# Factory function
+async def get_memory_context_source(
+    session: AsyncSession,
+    embedding_generator: Any | None = None,
+) -> MemoryContextSource:
+    """Create a memory context source instance."""
+    return MemoryContextSource(
+        session=session,
+        embedding_generator=embedding_generator,
+    )

backend/app/services/memory/integration/lifecycle.py

@@ -0,0 +1,629 @@
+# app/services/memory/integration/lifecycle.py
+"""
+Agent Lifecycle Hooks for Memory System.
+
+Provides memory management hooks for agent lifecycle events:
+- spawn: Initialize working memory for new agent instance
+- pause: Checkpoint working memory state
+- resume: Restore working memory from checkpoint
+- terminate: Consolidate session to episodic memory
+"""
+
+import logging
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.services.memory.episodic import EpisodicMemory
+from app.services.memory.types import EpisodeCreate, Outcome
+from app.services.memory.working import WorkingMemory
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LifecycleEvent:
+    """Event data for lifecycle hooks."""
+
+    event_type: str  # spawn, pause, resume, terminate
+    project_id: UUID
+    agent_instance_id: UUID
+    agent_type_id: UUID | None = None
+    session_id: str | None = None
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class LifecycleResult:
+    """Result of a lifecycle operation."""
+
+    success: bool
+    event_type: str
+    message: str | None = None
+    data: dict[str, Any] = field(default_factory=dict)
+    duration_ms: float = 0.0
+
+
+# Type alias for lifecycle hooks
+LifecycleHook = Callable[[LifecycleEvent], Coroutine[Any, Any, None]]
+
+
+class LifecycleHooks:
+    """
+    Collection of lifecycle hooks.
+
+    Allows registration of custom hooks for lifecycle events.
+    Hooks are called after the core memory operations.
+    """
+
+    def __init__(self) -> None:
+        """Initialize lifecycle hooks."""
+        self._spawn_hooks: list[LifecycleHook] = []
+        self._pause_hooks: list[LifecycleHook] = []
+        self._resume_hooks: list[LifecycleHook] = []
+        self._terminate_hooks: list[LifecycleHook] = []
+
+    def on_spawn(self, hook: LifecycleHook) -> LifecycleHook:
+        """Register a spawn hook."""
+        self._spawn_hooks.append(hook)
+        return hook
+
+    def on_pause(self, hook: LifecycleHook) -> LifecycleHook:
+        """Register a pause hook."""
+        self._pause_hooks.append(hook)
+        return hook
+
+    def on_resume(self, hook: LifecycleHook) -> LifecycleHook:
+        """Register a resume hook."""
+        self._resume_hooks.append(hook)
+        return hook
+
+    def on_terminate(self, hook: LifecycleHook) -> LifecycleHook:
+        """Register a terminate hook."""
+        self._terminate_hooks.append(hook)
+        return hook
+
+    async def run_spawn_hooks(self, event: LifecycleEvent) -> None:
+        """Run all spawn hooks."""
+        for hook in self._spawn_hooks:
+            try:
+                await hook(event)
+            except Exception as e:
+                logger.warning(f"Spawn hook failed: {e}")
+
+    async def run_pause_hooks(self, event: LifecycleEvent) -> None:
+        """Run all pause hooks."""
+        for hook in self._pause_hooks:
+            try:
+                await hook(event)
+            except Exception as e:
+                logger.warning(f"Pause hook failed: {e}")
+
+    async def run_resume_hooks(self, event: LifecycleEvent) -> None:
+        """Run all resume hooks."""
+        for hook in self._resume_hooks:
+            try:
+                await hook(event)
+            except Exception as e:
+                logger.warning(f"Resume hook failed: {e}")
+
+    async def run_terminate_hooks(self, event: LifecycleEvent) -> None:
+        """Run all terminate hooks."""
+        for hook in self._terminate_hooks:
+            try:
+                await hook(event)
+            except Exception as e:
+                logger.warning(f"Terminate hook failed: {e}")
+
+
+class AgentLifecycleManager:
+    """
+    Manager for agent lifecycle and memory integration.
+
+    Handles memory operations during agent lifecycle events:
+    - spawn: Creates new working memory for the session
+    - pause: Saves working memory state to checkpoint
+    - resume: Restores working memory from checkpoint
+    - terminate: Consolidates working memory to episodic memory
+    """
+
+    # Key prefix for checkpoint storage
+    CHECKPOINT_PREFIX = "__checkpoint__"
+
+    def __init__(
+        self,
+        session: AsyncSession,
+        embedding_generator: Any | None = None,
+        hooks: LifecycleHooks | None = None,
+    ) -> None:
+        """
+        Initialize the lifecycle manager.
+
+        Args:
+            session: Database session
+            embedding_generator: Optional embedding generator
+            hooks: Optional lifecycle hooks
+        """
+        self._session = session
+        self._embedding_generator = embedding_generator
+        self._hooks = hooks or LifecycleHooks()
+
+        # Lazy-initialized services
+        self._episodic: EpisodicMemory | None = None
+
+    async def _get_episodic(self) -> EpisodicMemory:
+        """Get or create episodic memory service."""
+        if self._episodic is None:
+            self._episodic = await EpisodicMemory.create(
+                self._session,
+                self._embedding_generator,
+            )
+        return self._episodic
+
+    @property
+    def hooks(self) -> LifecycleHooks:
+        """Get the lifecycle hooks."""
+        return self._hooks
+
+    async def spawn(
+        self,
+        project_id: UUID,
+        agent_instance_id: UUID,
+        session_id: str,
+        agent_type_id: UUID | None = None,
+        initial_state: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> LifecycleResult:
+        """
+        Handle agent spawn - initialize working memory.
+
+        Creates a new working memory instance for the agent session
+        and optionally populates it with initial state.
+
+        Args:
+            project_id: Project scope
+            agent_instance_id: Agent instance ID
+            session_id: Session ID for working memory
+            agent_type_id: Optional agent type ID
+            initial_state: Optional initial state to populate
+            metadata: Optional metadata for the event
+
+        Returns:
+            LifecycleResult with spawn outcome
+        """
+        start_time = datetime.now(UTC)
+
+        try:
+            # Create working memory for the session
+            working = await WorkingMemory.for_session(
+                session_id=session_id,
+                project_id=str(project_id),
+                agent_instance_id=str(agent_instance_id),
+            )
+
+            # Populate initial state if provided
+            items_set = 0
+            if initial_state:
+                for key, value in initial_state.items():
+                    await working.set(key, value)
+                    items_set += 1
+
+            # Create and run event hooks
+            event = LifecycleEvent(
+                event_type="spawn",
+                project_id=project_id,
+                agent_instance_id=agent_instance_id,
+                agent_type_id=agent_type_id,
+                session_id=session_id,
+                metadata=metadata or {},
+            )
+            await self._hooks.run_spawn_hooks(event)
+
+            duration_ms = (datetime.now(UTC) - start_time).total_seconds() * 1000
+
+            logger.info(
+                f"Agent {agent_instance_id} spawned with session {session_id}, "
+                f"initial state: {items_set} items"
+            )
+
+            return LifecycleResult(
+                success=True,
+                event_type="spawn",
+                message="Agent spawned successfully",
+                data={
+                    "session_id": session_id,
+                    "initial_items": items_set,
+                },
+                duration_ms=duration_ms,
+            )
+
+        except Exception as e:
+            logger.error(f"Spawn failed for agent {agent_instance_id}: {e}")
+            return LifecycleResult(
+                success=False,
+                event_type="spawn",
+                message=f"Spawn failed: {e}",
+            )
+
+    async def pause(
+        self,
+        project_id: UUID,
+        agent_instance_id: UUID,
+        session_id: str,
+        checkpoint_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> LifecycleResult:
+        """
+        Handle agent pause - checkpoint working memory.
+
+        Saves the current working memory state to a checkpoint
+        that can be restored later with resume().
+
+        Args:
+            project_id: Project scope
+            agent_instance_id: Agent instance ID
+            session_id: Session ID
+            checkpoint_id: Optional checkpoint identifier
+            metadata: Optional metadata for the event
+
+        Returns:
+            LifecycleResult with checkpoint data
+        """
+        start_time = datetime.now(UTC)
+        checkpoint_id = checkpoint_id or f"checkpoint_{int(start_time.timestamp())}"
+
+        try:
+            working = await WorkingMemory.for_session(
+                session_id=session_id,
+                project_id=str(project_id),
+                agent_instance_id=str(agent_instance_id),
+            )
+
+            # Get all current state
+            all_keys = await working.list_keys()
+            # Filter out checkpoint keys
+            state_keys = [k for k in all_keys if not k.startswith(self.CHECKPOINT_PREFIX)]
+
+            state: dict[str, Any] = {}
+            for key in state_keys:
+                value = await working.get(key)
+                if value is not None:
+                    state[key] = value
+
+            # Store checkpoint
+            checkpoint_key = f"{self.CHECKPOINT_PREFIX}{checkpoint_id}"
+            await working.set(
+                checkpoint_key,
+                {
+                    "state": state,
+                    "timestamp": start_time.isoformat(),
+                    "keys_count": len(state),
+                },
+                ttl_seconds=86400 * 7,  # Keep checkpoint for 7 days
+            )
+
+            # Run hooks
+            event = LifecycleEvent(
+                event_type="pause",
+                project_id=project_id,
+                agent_instance_id=agent_instance_id,
+                session_id=session_id,
+                metadata={**(metadata or {}), "checkpoint_id": checkpoint_id},
+            )
+            await self._hooks.run_pause_hooks(event)
+
+            duration_ms = (datetime.now(UTC) - start_time).total_seconds() * 1000
+
+            logger.info(
+                f"Agent {agent_instance_id} paused, checkpoint {checkpoint_id} "
+                f"saved with {len(state)} items"
+            )
+
+            return LifecycleResult(
+                success=True,
+                event_type="pause",
+                message="Agent paused successfully",
+                data={
+                    "checkpoint_id": checkpoint_id,
+                    "items_saved": len(state),
+                    "timestamp": start_time.isoformat(),
+                },
+                duration_ms=duration_ms,
+            )
+
+        except Exception as e:
+            logger.error(f"Pause failed for agent {agent_instance_id}: {e}")
+            return LifecycleResult(
+                success=False,
+                event_type="pause",
+                message=f"Pause failed: {e}",
+            )
+
+    async def resume(
+        self,
+        project_id: UUID,
+        agent_instance_id: UUID,
+        session_id: str,
+        checkpoint_id: str,
+        clear_current: bool = True,
+        metadata: dict[str, Any] | None = None,
+    ) -> LifecycleResult:
+        """
+        Handle agent resume - restore from checkpoint.
+
+        Restores working memory state from a previously saved checkpoint.
+
+        Args:
+            project_id: Project scope
+            agent_instance_id: Agent instance ID
+            session_id: Session ID
+            checkpoint_id: Checkpoint to restore from
+            clear_current: Whether to clear current state before restoring
+            metadata: Optional metadata for the event
+
+        Returns:
+            LifecycleResult with restore outcome
+        """
+        start_time = datetime.now(UTC)
+
+        try:
+            working = await WorkingMemory.for_session(
+                session_id=session_id,
+                project_id=str(project_id),
+                agent_instance_id=str(agent_instance_id),
+            )
+
+            # Get checkpoint
+            checkpoint_key = f"{self.CHECKPOINT_PREFIX}{checkpoint_id}"
+            checkpoint = await working.get(checkpoint_key)
+
+            if checkpoint is None:
+                return LifecycleResult(
+                    success=False,
+                    event_type="resume",
+                    message=f"Checkpoint '{checkpoint_id}' not found",
+                )
+
+            # Clear current state if requested
+            if clear_current:
+                all_keys = await working.list_keys()
+                for key in all_keys:
+                    if not key.startswith(self.CHECKPOINT_PREFIX):
+                        await working.delete(key)
+
+            # Restore state from checkpoint
+            state = checkpoint.get("state", {})
+            items_restored = 0
+            for key, value in state.items():
+                await working.set(key, value)
+                items_restored += 1
+
+            # Run hooks
+            event = LifecycleEvent(
+                event_type="resume",
+                project_id=project_id,
+                agent_instance_id=agent_instance_id,
+                session_id=session_id,
+                metadata={**(metadata or {}), "checkpoint_id": checkpoint_id},
+            )
+            await self._hooks.run_resume_hooks(event)
+
+            duration_ms = (datetime.now(UTC) - start_time).total_seconds() * 1000
+
+            logger.info(
+                f"Agent {agent_instance_id} resumed from checkpoint {checkpoint_id}, "
+                f"restored {items_restored} items"
+            )
+
+            return LifecycleResult(
+                success=True,
+                event_type="resume",
+                message="Agent resumed successfully",
+                data={
+                    "checkpoint_id": checkpoint_id,
+                    "items_restored": items_restored,
+                    "checkpoint_timestamp": checkpoint.get("timestamp"),
+                },
+                duration_ms=duration_ms,
+            )
+
+        except Exception as e:
+            logger.error(f"Resume failed for agent {agent_instance_id}: {e}")
+            return LifecycleResult(
+                success=False,
+                event_type="resume",
+                message=f"Resume failed: {e}",
+            )
+
+    async def terminate(
+        self,
+        project_id: UUID,
+        agent_instance_id: UUID,
+        session_id: str,
+        task_description: str | None = None,
+        outcome: Outcome = Outcome.SUCCESS,
+        lessons_learned: list[str] | None = None,
+        consolidate_to_episodic: bool = True,
+        cleanup_working: bool = True,
+        metadata: dict[str, Any] | None = None,
+    ) -> LifecycleResult:
+        """
+        Handle agent termination - consolidate to episodic memory.
+
+        Consolidates the session's working memory into an episodic memory
+        entry, then optionally cleans up the working memory.
+
+        Args:
+            project_id: Project scope
+            agent_instance_id: Agent instance ID
+            session_id: Session ID
+            task_description: Description of what was accomplished
+            outcome: Task outcome (SUCCESS, FAILURE, PARTIAL)
+            lessons_learned: Optional list of lessons learned
+            consolidate_to_episodic: Whether to create episodic entry
+            cleanup_working: Whether to clear working memory
+            metadata: Optional metadata for the event
+
+        Returns:
+            LifecycleResult with termination outcome
+        """
+        start_time = datetime.now(UTC)
+
+        try:
+            working = await WorkingMemory.for_session(
+                session_id=session_id,
+                project_id=str(project_id),
+                agent_instance_id=str(agent_instance_id),
+            )
+
+            # Gather session state for consolidation
+            all_keys = await working.list_keys()
+            state_keys = [k for k in all_keys if not k.startswith(self.CHECKPOINT_PREFIX)]
+
+            session_state: dict[str, Any] = {}
+            for key in state_keys:
+                value = await working.get(key)
+                if value is not None:
+                    session_state[key] = value
+
+            episode_id: str | None = None
+
+            # Consolidate to episodic memory
+            if consolidate_to_episodic:
+                episodic = await self._get_episodic()
+
+                description = task_description or f"Session {session_id} completed"
+
+                episode_data = EpisodeCreate(
+                    project_id=project_id,
+                    agent_instance_id=agent_instance_id,
+                    session_id=session_id,
+                    task_type="session_completion",
+                    task_description=description[:500],
+                    outcome=outcome,
+                    outcome_details=f"Session terminated with {len(session_state)} state items",
+                    actions=[
+                        {
+                            "type": "session_terminate",
+                            "state_keys": list(session_state.keys()),
+                            "outcome": outcome.value,
+                        }
+                    ],
+                    context_summary=str(session_state)[:1000] if session_state else "",
+                    lessons_learned=lessons_learned or [],
+                    duration_seconds=0.0,  # Unknown at this point
+                    tokens_used=0,
+                    importance_score=0.6,  # Moderate importance for session ends
+                )
+
+                episode = await episodic.record_episode(episode_data)
+                episode_id = str(episode.id)
+
+            # Clean up working memory
+            items_cleared = 0
+            if cleanup_working:
+                for key in all_keys:
+                    await working.delete(key)
+                    items_cleared += 1
+
+            # Run hooks
+            event = LifecycleEvent(
+                event_type="terminate",
+                project_id=project_id,
+                agent_instance_id=agent_instance_id,
+                session_id=session_id,
+                metadata={**(metadata or {}), "episode_id": episode_id},
+            )
+            await self._hooks.run_terminate_hooks(event)
+
+            duration_ms = (datetime.now(UTC) - start_time).total_seconds() * 1000
+
+            logger.info(
+                f"Agent {agent_instance_id} terminated, session {session_id} "
+                f"consolidated to episode {episode_id}"
+            )
+
+            return LifecycleResult(
+                success=True,
+                event_type="terminate",
+                message="Agent terminated successfully",
+                data={
+                    "episode_id": episode_id,
+                    "state_items_consolidated": len(session_state),
+                    "items_cleared": items_cleared,
+                    "outcome": outcome.value,
+                },
+                duration_ms=duration_ms,
+            )
+
+        except Exception as e:
+            logger.error(f"Terminate failed for agent {agent_instance_id}: {e}")
+            return LifecycleResult(
+                success=False,
+                event_type="terminate",
+                message=f"Terminate failed: {e}",
+            )
+
+    async def list_checkpoints(
+        self,
+        project_id: UUID,
+        agent_instance_id: UUID,
+        session_id: str,
+    ) -> list[dict[str, Any]]:
+        """
+        List available checkpoints for a session.
+
+        Args:
+            project_id: Project scope
+            agent_instance_id: Agent instance ID
+            session_id: Session ID
+
+        Returns:
+            List of checkpoint metadata dicts
+        """
+        working = await WorkingMemory.for_session(
+            session_id=session_id,
+            project_id=str(project_id),
+            agent_instance_id=str(agent_instance_id),
+        )
+
+        all_keys = await working.list_keys()
+        checkpoints: list[dict[str, Any]] = []
+
+        for key in all_keys:
+            if key.startswith(self.CHECKPOINT_PREFIX):
+                checkpoint_id = key[len(self.CHECKPOINT_PREFIX):]
+                checkpoint = await working.get(key)
+                if checkpoint:
+                    checkpoints.append({
+                        "checkpoint_id": checkpoint_id,
+                        "timestamp": checkpoint.get("timestamp"),
+                        "keys_count": checkpoint.get("keys_count", 0),
+                    })
+
+        # Sort by timestamp (newest first)
+        checkpoints.sort(
+            key=lambda c: c.get("timestamp", ""),
+            reverse=True,
+        )
+
+        return checkpoints
+
+
+# Factory function
+async def get_lifecycle_manager(
+    session: AsyncSession,
+    embedding_generator: Any | None = None,
+    hooks: LifecycleHooks | None = None,
+) -> AgentLifecycleManager:
+    """Create a lifecycle manager instance."""
+    return AgentLifecycleManager(
+        session=session,
+        embedding_generator=embedding_generator,
+        hooks=hooks,
+    )

backend/app/services/memory/manager.py

@@ -0,0 +1,606 @@
+"""
+Memory Manager
+
+Facade for the Agent Memory System providing unified access
+to all memory types and operations.
+"""
+
+import logging
+from typing import Any
+from uuid import UUID
+
+from .config import MemorySettings, get_memory_settings
+from .types import (
+    Episode,
+    EpisodeCreate,
+    Fact,
+    FactCreate,
+    MemoryStats,
+    MemoryType,
+    Outcome,
+    Procedure,
+    ProcedureCreate,
+    RetrievalResult,
+    ScopeContext,
+    ScopeLevel,
+    TaskState,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryManager:
+    """
+    Unified facade for the Agent Memory System.
+
+    Provides a single entry point for all memory operations across
+    working, episodic, semantic, and procedural memory types.
+
+    Usage:
+        manager = MemoryManager.create()
+
+        # Working memory
+        await manager.set_working("key", {"data": "value"})
+        value = await manager.get_working("key")
+
+        # Episodic memory
+        episode = await manager.record_episode(episode_data)
+        similar = await manager.search_episodes("query")
+
+        # Semantic memory
+        fact = await manager.store_fact(fact_data)
+        facts = await manager.search_facts("query")
+
+        # Procedural memory
+        procedure = await manager.record_procedure(procedure_data)
+        procedures = await manager.find_procedures("context")
+    """
+
+    def __init__(
+        self,
+        settings: MemorySettings,
+        scope: ScopeContext,
+    ) -> None:
+        """
+        Initialize the MemoryManager.
+
+        Args:
+            settings: Memory configuration settings
+            scope: The scope context for this manager instance
+        """
+        self._settings = settings
+        self._scope = scope
+        self._initialized = False
+
+        # These will be initialized when the respective sub-modules are implemented
+        self._working_memory: Any | None = None
+        self._episodic_memory: Any | None = None
+        self._semantic_memory: Any | None = None
+        self._procedural_memory: Any | None = None
+
+        logger.debug(
+            "MemoryManager created for scope %s:%s",
+            scope.scope_type.value,
+            scope.scope_id,
+        )
+
+    @classmethod
+    def create(
+        cls,
+        scope_type: ScopeLevel = ScopeLevel.SESSION,
+        scope_id: str = "default",
+        parent_scope: ScopeContext | None = None,
+        settings: MemorySettings | None = None,
+    ) -> "MemoryManager":
+        """
+        Create a new MemoryManager instance.
+
+        Args:
+            scope_type: The scope level for this manager
+            scope_id: The scope identifier
+            parent_scope: Optional parent scope for inheritance
+            settings: Optional custom settings (uses global if not provided)
+
+        Returns:
+            A new MemoryManager instance
+        """
+        if settings is None:
+            settings = get_memory_settings()
+
+        scope = ScopeContext(
+            scope_type=scope_type,
+            scope_id=scope_id,
+            parent=parent_scope,
+        )
+
+        return cls(settings=settings, scope=scope)
+
+    @classmethod
+    def for_session(
+        cls,
+        session_id: str,
+        agent_instance_id: UUID | None = None,
+        project_id: UUID | None = None,
+    ) -> "MemoryManager":
+        """
+        Create a MemoryManager for a specific session.
+
+        Builds the appropriate scope hierarchy based on provided IDs.
+
+        Args:
+            session_id: The session identifier
+            agent_instance_id: Optional agent instance ID
+            project_id: Optional project ID
+
+        Returns:
+            A MemoryManager configured for the session scope
+        """
+        settings = get_memory_settings()
+
+        # Build scope hierarchy
+        parent: ScopeContext | None = None
+
+        if project_id:
+            parent = ScopeContext(
+                scope_type=ScopeLevel.PROJECT,
+                scope_id=str(project_id),
+                parent=ScopeContext(
+                    scope_type=ScopeLevel.GLOBAL,
+                    scope_id="global",
+                ),
+            )
+
+        if agent_instance_id:
+            parent = ScopeContext(
+                scope_type=ScopeLevel.AGENT_INSTANCE,
+                scope_id=str(agent_instance_id),
+                parent=parent,
+            )
+
+        scope = ScopeContext(
+            scope_type=ScopeLevel.SESSION,
+            scope_id=session_id,
+            parent=parent,
+        )
+
+        return cls(settings=settings, scope=scope)
+
+    @property
+    def scope(self) -> ScopeContext:
+        """Get the current scope context."""
+        return self._scope
+
+    @property
+    def settings(self) -> MemorySettings:
+        """Get the memory settings."""
+        return self._settings
+
+    # =========================================================================
+    # Working Memory Operations
+    # =========================================================================
+
+    async def set_working(
+        self,
+        key: str,
+        value: Any,
+        ttl_seconds: int | None = None,
+    ) -> None:
+        """
+        Set a value in working memory.
+
+        Args:
+            key: The key to store the value under
+            value: The value to store (must be JSON serializable)
+            ttl_seconds: Optional TTL (uses default if not provided)
+        """
+        # Placeholder - will be implemented in #89
+        logger.debug("set_working called for key=%s (not yet implemented)", key)
+        raise NotImplementedError("Working memory not yet implemented")
+
+    async def get_working(
+        self,
+        key: str,
+        default: Any = None,
+    ) -> Any:
+        """
+        Get a value from working memory.
+
+        Args:
+            key: The key to retrieve
+            default: Default value if key not found
+
+        Returns:
+            The stored value or default
+        """
+        # Placeholder - will be implemented in #89
+        logger.debug("get_working called for key=%s (not yet implemented)", key)
+        raise NotImplementedError("Working memory not yet implemented")
+
+    async def delete_working(self, key: str) -> bool:
+        """
+        Delete a value from working memory.
+
+        Args:
+            key: The key to delete
+
+        Returns:
+            True if the key was deleted, False if not found
+        """
+        # Placeholder - will be implemented in #89
+        logger.debug("delete_working called for key=%s (not yet implemented)", key)
+        raise NotImplementedError("Working memory not yet implemented")
+
+    async def set_task_state(self, state: TaskState) -> None:
+        """
+        Set the current task state in working memory.
+
+        Args:
+            state: The task state to store
+        """
+        # Placeholder - will be implemented in #89
+        logger.debug(
+            "set_task_state called for task=%s (not yet implemented)",
+            state.task_id,
+        )
+        raise NotImplementedError("Working memory not yet implemented")
+
+    async def get_task_state(self) -> TaskState | None:
+        """
+        Get the current task state from working memory.
+
+        Returns:
+            The current task state or None
+        """
+        # Placeholder - will be implemented in #89
+        logger.debug("get_task_state called (not yet implemented)")
+        raise NotImplementedError("Working memory not yet implemented")
+
+    async def create_checkpoint(self) -> str:
+        """
+        Create a checkpoint of the current working memory state.
+
+        Returns:
+            The checkpoint ID
+        """
+        # Placeholder - will be implemented in #89
+        logger.debug("create_checkpoint called (not yet implemented)")
+        raise NotImplementedError("Working memory not yet implemented")
+
+    async def restore_checkpoint(self, checkpoint_id: str) -> None:
+        """
+        Restore working memory from a checkpoint.
+
+        Args:
+            checkpoint_id: The checkpoint to restore from
+        """
+        # Placeholder - will be implemented in #89
+        logger.debug(
+            "restore_checkpoint called for id=%s (not yet implemented)",
+            checkpoint_id,
+        )
+        raise NotImplementedError("Working memory not yet implemented")
+
+    # =========================================================================
+    # Episodic Memory Operations
+    # =========================================================================
+
+    async def record_episode(self, episode: EpisodeCreate) -> Episode:
+        """
+        Record a new episode in episodic memory.
+
+        Args:
+            episode: The episode data to record
+
+        Returns:
+            The created episode with ID
+        """
+        # Placeholder - will be implemented in #90
+        logger.debug(
+            "record_episode called for task=%s (not yet implemented)",
+            episode.task_type,
+        )
+        raise NotImplementedError("Episodic memory not yet implemented")
+
+    async def search_episodes(
+        self,
+        query: str,
+        limit: int | None = None,
+    ) -> RetrievalResult[Episode]:
+        """
+        Search for similar episodes.
+
+        Args:
+            query: The search query
+            limit: Maximum results to return
+
+        Returns:
+            Retrieval result with matching episodes
+        """
+        # Placeholder - will be implemented in #90
+        logger.debug(
+            "search_episodes called for query=%s (not yet implemented)",
+            query[:50],
+        )
+        raise NotImplementedError("Episodic memory not yet implemented")
+
+    async def get_recent_episodes(
+        self,
+        limit: int = 10,
+    ) -> list[Episode]:
+        """
+        Get the most recent episodes.
+
+        Args:
+            limit: Maximum episodes to return
+
+        Returns:
+            List of recent episodes
+        """
+        # Placeholder - will be implemented in #90
+        logger.debug("get_recent_episodes called (not yet implemented)")
+        raise NotImplementedError("Episodic memory not yet implemented")
+
+    async def get_episodes_by_outcome(
+        self,
+        outcome: Outcome,
+        limit: int = 10,
+    ) -> list[Episode]:
+        """
+        Get episodes by outcome.
+
+        Args:
+            outcome: The outcome to filter by
+            limit: Maximum episodes to return
+
+        Returns:
+            List of episodes with the specified outcome
+        """
+        # Placeholder - will be implemented in #90
+        logger.debug(
+            "get_episodes_by_outcome called for outcome=%s (not yet implemented)",
+            outcome.value,
+        )
+        raise NotImplementedError("Episodic memory not yet implemented")
+
+    # =========================================================================
+    # Semantic Memory Operations
+    # =========================================================================
+
+    async def store_fact(self, fact: FactCreate) -> Fact:
+        """
+        Store a new fact in semantic memory.
+
+        Args:
+            fact: The fact data to store
+
+        Returns:
+            The created fact with ID
+        """
+        # Placeholder - will be implemented in #91
+        logger.debug(
+            "store_fact called for %s %s %s (not yet implemented)",
+            fact.subject,
+            fact.predicate,
+            fact.object,
+        )
+        raise NotImplementedError("Semantic memory not yet implemented")
+
+    async def search_facts(
+        self,
+        query: str,
+        limit: int | None = None,
+    ) -> RetrievalResult[Fact]:
+        """
+        Search for facts matching a query.
+
+        Args:
+            query: The search query
+            limit: Maximum results to return
+
+        Returns:
+            Retrieval result with matching facts
+        """
+        # Placeholder - will be implemented in #91
+        logger.debug(
+            "search_facts called for query=%s (not yet implemented)",
+            query[:50],
+        )
+        raise NotImplementedError("Semantic memory not yet implemented")
+
+    async def get_facts_by_entity(
+        self,
+        entity: str,
+        limit: int = 20,
+    ) -> list[Fact]:
+        """
+        Get facts related to an entity.
+
+        Args:
+            entity: The entity to search for
+            limit: Maximum facts to return
+
+        Returns:
+            List of facts mentioning the entity
+        """
+        # Placeholder - will be implemented in #91
+        logger.debug(
+            "get_facts_by_entity called for entity=%s (not yet implemented)",
+            entity,
+        )
+        raise NotImplementedError("Semantic memory not yet implemented")
+
+    async def reinforce_fact(self, fact_id: UUID) -> Fact:
+        """
+        Reinforce a fact (increase confidence from repeated learning).
+
+        Args:
+            fact_id: The fact to reinforce
+
+        Returns:
+            The updated fact
+        """
+        # Placeholder - will be implemented in #91
+        logger.debug(
+            "reinforce_fact called for id=%s (not yet implemented)",
+            fact_id,
+        )
+        raise NotImplementedError("Semantic memory not yet implemented")
+
+    # =========================================================================
+    # Procedural Memory Operations
+    # =========================================================================
+
+    async def record_procedure(self, procedure: ProcedureCreate) -> Procedure:
+        """
+        Record a new procedure.
+
+        Args:
+            procedure: The procedure data to record
+
+        Returns:
+            The created procedure with ID
+        """
+        # Placeholder - will be implemented in #92
+        logger.debug(
+            "record_procedure called for name=%s (not yet implemented)",
+            procedure.name,
+        )
+        raise NotImplementedError("Procedural memory not yet implemented")
+
+    async def find_procedures(
+        self,
+        context: str,
+        limit: int = 5,
+    ) -> list[Procedure]:
+        """
+        Find procedures matching the current context.
+
+        Args:
+            context: The context to match against
+            limit: Maximum procedures to return
+
+        Returns:
+            List of matching procedures sorted by success rate
+        """
+        # Placeholder - will be implemented in #92
+        logger.debug(
+            "find_procedures called for context=%s (not yet implemented)",
+            context[:50],
+        )
+        raise NotImplementedError("Procedural memory not yet implemented")
+
+    async def record_procedure_outcome(
+        self,
+        procedure_id: UUID,
+        success: bool,
+    ) -> None:
+        """
+        Record the outcome of using a procedure.
+
+        Args:
+            procedure_id: The procedure that was used
+            success: Whether the procedure succeeded
+        """
+        # Placeholder - will be implemented in #92
+        logger.debug(
+            "record_procedure_outcome called for id=%s success=%s (not yet implemented)",
+            procedure_id,
+            success,
+        )
+        raise NotImplementedError("Procedural memory not yet implemented")
+
+    # =========================================================================
+    # Cross-Memory Operations
+    # =========================================================================
+
+    async def recall(
+        self,
+        query: str,
+        memory_types: list[MemoryType] | None = None,
+        limit: int = 10,
+    ) -> dict[MemoryType, list[Any]]:
+        """
+        Recall memories across multiple memory types.
+
+        Args:
+            query: The search query
+            memory_types: Memory types to search (all if not specified)
+            limit: Maximum results per type
+
+        Returns:
+            Dictionary mapping memory types to results
+        """
+        # Placeholder - will be implemented in #97 (Component Integration)
+        logger.debug("recall called for query=%s (not yet implemented)", query[:50])
+        raise NotImplementedError("Cross-memory recall not yet implemented")
+
+    async def get_stats(
+        self,
+        memory_type: MemoryType | None = None,
+    ) -> list[MemoryStats]:
+        """
+        Get memory statistics.
+
+        Args:
+            memory_type: Specific type or all if not specified
+
+        Returns:
+            List of statistics for requested memory types
+        """
+        # Placeholder - will be implemented in #100 (Metrics & Observability)
+        logger.debug("get_stats called (not yet implemented)")
+        raise NotImplementedError("Memory stats not yet implemented")
+
+    # =========================================================================
+    # Lifecycle Operations
+    # =========================================================================
+
+    async def initialize(self) -> None:
+        """
+        Initialize the memory manager and its backends.
+
+        Should be called before using the manager.
+        """
+        if self._initialized:
+            logger.debug("MemoryManager already initialized")
+            return
+
+        logger.info(
+            "Initializing MemoryManager for scope %s:%s",
+            self._scope.scope_type.value,
+            self._scope.scope_id,
+        )
+
+        # TODO: Initialize backends when implemented
+
+        self._initialized = True
+        logger.info("MemoryManager initialized successfully")
+
+    async def close(self) -> None:
+        """
+        Close the memory manager and release resources.
+
+        Should be called when done using the manager.
+        """
+        if not self._initialized:
+            return
+
+        logger.info(
+            "Closing MemoryManager for scope %s:%s",
+            self._scope.scope_type.value,
+            self._scope.scope_id,
+        )
+
+        # TODO: Close backends when implemented
+
+        self._initialized = False
+        logger.info("MemoryManager closed successfully")
+
+    async def __aenter__(self) -> "MemoryManager":
+        """Async context manager entry."""
+        await self.initialize()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit."""
+        await self.close()

backend/app/services/memory/mcp/__init__.py

@@ -0,0 +1,40 @@
+# app/services/memory/mcp/__init__.py
+"""
+MCP Tools for Agent Memory System.
+
+Exposes memory operations as MCP-compatible tools that agents can invoke:
+- remember: Store data in memory
+- recall: Retrieve from memory
+- forget: Remove from memory
+- reflect: Analyze patterns
+- get_memory_stats: Usage statistics
+- search_procedures: Find relevant procedures
+- record_outcome: Record task success/failure
+"""
+
+from .service import MemoryToolService, get_memory_tool_service
+from .tools import (
+    MEMORY_TOOL_DEFINITIONS,
+    ForgetArgs,
+    GetMemoryStatsArgs,
+    MemoryToolDefinition,
+    RecallArgs,
+    RecordOutcomeArgs,
+    ReflectArgs,
+    RememberArgs,
+    SearchProceduresArgs,
+)
+
+__all__ = [
+    "MEMORY_TOOL_DEFINITIONS",
+    "ForgetArgs",
+    "GetMemoryStatsArgs",
+    "MemoryToolDefinition",
+    "MemoryToolService",
+    "RecallArgs",
+    "RecordOutcomeArgs",
+    "ReflectArgs",
+    "RememberArgs",
+    "SearchProceduresArgs",
+    "get_memory_tool_service",
+]

backend/app/services/memory/mcp/tools.py

@@ -0,0 +1,491 @@
+# app/services/memory/mcp/tools.py
+"""
+MCP Tool Definitions for Agent Memory System.
+
+Defines the schema and metadata for memory-related MCP tools.
+These tools are invoked by AI agents to interact with the memory system.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class MemoryType(str, Enum):
+    """Types of memory for storage operations."""
+
+    WORKING = "working"
+    EPISODIC = "episodic"
+    SEMANTIC = "semantic"
+    PROCEDURAL = "procedural"
+
+
+class AnalysisType(str, Enum):
+    """Types of pattern analysis for the reflect tool."""
+
+    RECENT_PATTERNS = "recent_patterns"
+    SUCCESS_FACTORS = "success_factors"
+    FAILURE_PATTERNS = "failure_patterns"
+    COMMON_PROCEDURES = "common_procedures"
+    LEARNING_PROGRESS = "learning_progress"
+
+
+class OutcomeType(str, Enum):
+    """Outcome types for record_outcome tool."""
+
+    SUCCESS = "success"
+    PARTIAL = "partial"
+    FAILURE = "failure"
+    ABANDONED = "abandoned"
+
+
+# ============================================================================
+# Tool Argument Schemas (Pydantic models for validation)
+# ============================================================================
+
+
+class RememberArgs(BaseModel):
+    """Arguments for the 'remember' tool."""
+
+    memory_type: MemoryType = Field(
+        ...,
+        description="Type of memory to store in: working, episodic, semantic, or procedural",
+    )
+    content: str = Field(
+        ...,
+        description="The content to remember. Can be text, facts, or procedure steps.",
+        min_length=1,
+        max_length=10000,
+    )
+    key: str | None = Field(
+        None,
+        description="Optional key for working memory entries. Required for working memory type.",
+        max_length=256,
+    )
+    importance: float = Field(
+        0.5,
+        description="Importance score from 0.0 (low) to 1.0 (critical)",
+        ge=0.0,
+        le=1.0,
+    )
+    ttl_seconds: int | None = Field(
+        None,
+        description="Time-to-live in seconds for working memory. None for permanent storage.",
+        ge=1,
+        le=86400 * 30,  # Max 30 days
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional metadata to store with the memory",
+    )
+    # For semantic memory (facts)
+    subject: str | None = Field(
+        None,
+        description="Subject of the fact (for semantic memory)",
+        max_length=256,
+    )
+    predicate: str | None = Field(
+        None,
+        description="Predicate/relationship (for semantic memory)",
+        max_length=256,
+    )
+    object_value: str | None = Field(
+        None,
+        description="Object of the fact (for semantic memory)",
+        max_length=1000,
+    )
+    # For procedural memory
+    trigger: str | None = Field(
+        None,
+        description="Trigger condition for the procedure (for procedural memory)",
+        max_length=500,
+    )
+    steps: list[dict[str, Any]] | None = Field(
+        None,
+        description="Procedure steps as a list of action dictionaries",
+    )
+
+
+class RecallArgs(BaseModel):
+    """Arguments for the 'recall' tool."""
+
+    query: str = Field(
+        ...,
+        description="Search query to find relevant memories",
+        min_length=1,
+        max_length=1000,
+    )
+    memory_types: list[MemoryType] = Field(
+        default_factory=lambda: [MemoryType.EPISODIC, MemoryType.SEMANTIC],
+        description="Types of memory to search in",
+    )
+    limit: int = Field(
+        10,
+        description="Maximum number of results to return",
+        ge=1,
+        le=100,
+    )
+    min_relevance: float = Field(
+        0.0,
+        description="Minimum relevance score (0.0-1.0) for results",
+        ge=0.0,
+        le=1.0,
+    )
+    filters: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional filters (e.g., outcome, task_type, date range)",
+    )
+    include_context: bool = Field(
+        True,
+        description="Whether to include surrounding context in results",
+    )
+
+
+class ForgetArgs(BaseModel):
+    """Arguments for the 'forget' tool."""
+
+    memory_type: MemoryType = Field(
+        ...,
+        description="Type of memory to remove from",
+    )
+    key: str | None = Field(
+        None,
+        description="Key to remove (for working memory)",
+        max_length=256,
+    )
+    memory_id: str | None = Field(
+        None,
+        description="Specific memory ID to remove (for episodic/semantic/procedural)",
+    )
+    pattern: str | None = Field(
+        None,
+        description="Pattern to match for bulk removal (use with caution)",
+        max_length=500,
+    )
+    confirm_bulk: bool = Field(
+        False,
+        description="Must be True to confirm bulk deletion when using pattern",
+    )
+
+
+class ReflectArgs(BaseModel):
+    """Arguments for the 'reflect' tool."""
+
+    analysis_type: AnalysisType = Field(
+        ...,
+        description="Type of pattern analysis to perform",
+    )
+    scope: str | None = Field(
+        None,
+        description="Optional scope to limit analysis (e.g., task_type, time range)",
+        max_length=500,
+    )
+    depth: int = Field(
+        3,
+        description="Depth of analysis (1=surface, 5=deep)",
+        ge=1,
+        le=5,
+    )
+    include_examples: bool = Field(
+        True,
+        description="Whether to include example memories in the analysis",
+    )
+    max_items: int = Field(
+        10,
+        description="Maximum number of patterns/examples to analyze",
+        ge=1,
+        le=50,
+    )
+
+
+class GetMemoryStatsArgs(BaseModel):
+    """Arguments for the 'get_memory_stats' tool."""
+
+    include_breakdown: bool = Field(
+        True,
+        description="Include breakdown by memory type",
+    )
+    include_recent_activity: bool = Field(
+        True,
+        description="Include recent memory activity summary",
+    )
+    time_range_days: int = Field(
+        7,
+        description="Time range for activity analysis in days",
+        ge=1,
+        le=90,
+    )
+
+
+class SearchProceduresArgs(BaseModel):
+    """Arguments for the 'search_procedures' tool."""
+
+    trigger: str = Field(
+        ...,
+        description="Trigger or situation to find procedures for",
+        min_length=1,
+        max_length=500,
+    )
+    task_type: str | None = Field(
+        None,
+        description="Optional task type to filter procedures",
+        max_length=100,
+    )
+    min_success_rate: float = Field(
+        0.5,
+        description="Minimum success rate (0.0-1.0) for returned procedures",
+        ge=0.0,
+        le=1.0,
+    )
+    limit: int = Field(
+        5,
+        description="Maximum number of procedures to return",
+        ge=1,
+        le=20,
+    )
+    include_steps: bool = Field(
+        True,
+        description="Whether to include detailed steps in the response",
+    )
+
+
+class RecordOutcomeArgs(BaseModel):
+    """Arguments for the 'record_outcome' tool."""
+
+    task_type: str = Field(
+        ...,
+        description="Type of task that was executed",
+        min_length=1,
+        max_length=100,
+    )
+    outcome: OutcomeType = Field(
+        ...,
+        description="Outcome of the task execution",
+    )
+    procedure_id: str | None = Field(
+        None,
+        description="ID of the procedure that was followed (if any)",
+    )
+    context: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Context in which the task was executed",
+    )
+    lessons_learned: str | None = Field(
+        None,
+        description="What was learned from this execution",
+        max_length=2000,
+    )
+    duration_seconds: float | None = Field(
+        None,
+        description="How long the task took to execute",
+        ge=0.0,
+    )
+    error_details: str | None = Field(
+        None,
+        description="Details about any errors encountered (for failures)",
+        max_length=2000,
+    )
+
+
+# ============================================================================
+# Tool Definition Structure
+# ============================================================================
+
+
+@dataclass
+class MemoryToolDefinition:
+    """Definition of an MCP tool for the memory system."""
+
+    name: str
+    description: str
+    args_schema: type[BaseModel]
+    input_schema: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Generate input schema from Pydantic model."""
+        if not self.input_schema:
+            self.input_schema = self.args_schema.model_json_schema()
+
+    def to_mcp_format(self) -> dict[str, Any]:
+        """Convert to MCP tool format."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.input_schema,
+        }
+
+    def validate_args(self, args: dict[str, Any]) -> BaseModel:
+        """Validate and parse arguments."""
+        return self.args_schema.model_validate(args)
+
+
+# ============================================================================
+# Tool Definitions
+# ============================================================================
+
+
+REMEMBER_TOOL = MemoryToolDefinition(
+    name="remember",
+    description="""Store information in the agent's memory system.
+
+Use this tool to:
+- Store temporary data in working memory (key-value with optional TTL)
+- Record important events in episodic memory (automatically done on session end)
+- Store facts/knowledge in semantic memory (subject-predicate-object triples)
+- Save procedures in procedural memory (trigger conditions and steps)
+
+Examples:
+- Working memory: {"memory_type": "working", "key": "current_task", "content": "Implementing auth", "ttl_seconds": 3600}
+- Semantic fact: {"memory_type": "semantic", "subject": "User", "predicate": "prefers", "object_value": "dark mode", "content": "User preference noted"}
+- Procedure: {"memory_type": "procedural", "trigger": "When creating a new file", "steps": [{"action": "check_exists"}, {"action": "create"}], "content": "File creation procedure"}
+""",
+    args_schema=RememberArgs,
+)
+
+
+RECALL_TOOL = MemoryToolDefinition(
+    name="recall",
+    description="""Retrieve information from the agent's memory system.
+
+Use this tool to:
+- Search for relevant past experiences (episodic)
+- Look up known facts and knowledge (semantic)
+- Find applicable procedures for current task (procedural)
+- Get current session state (working)
+
+The query supports semantic search - describe what you're looking for in natural language.
+
+Examples:
+- {"query": "How did I handle authentication errors before?", "memory_types": ["episodic"]}
+- {"query": "What are the user's preferences?", "memory_types": ["semantic"], "limit": 5}
+- {"query": "database connection", "memory_types": ["episodic", "semantic", "procedural"], "filters": {"outcome": "success"}}
+""",
+    args_schema=RecallArgs,
+)
+
+
+FORGET_TOOL = MemoryToolDefinition(
+    name="forget",
+    description="""Remove information from the agent's memory system.
+
+Use this tool to:
+- Clear temporary working memory entries
+- Remove specific memories by ID
+- Bulk remove memories matching a pattern (requires confirmation)
+
+WARNING: Deletion is permanent. Use with caution.
+
+Examples:
+- Working memory: {"memory_type": "working", "key": "temp_calculation"}
+- Specific memory: {"memory_type": "episodic", "memory_id": "ep-123"}
+- Bulk (requires confirm): {"memory_type": "working", "pattern": "cache_*", "confirm_bulk": true}
+""",
+    args_schema=ForgetArgs,
+)
+
+
+REFLECT_TOOL = MemoryToolDefinition(
+    name="reflect",
+    description="""Analyze patterns in the agent's memory to gain insights.
+
+Use this tool to:
+- Identify patterns in recent work
+- Understand what leads to success/failure
+- Learn from past experiences
+- Track learning progress over time
+
+Analysis types:
+- recent_patterns: What patterns appear in recent work
+- success_factors: What conditions lead to success
+- failure_patterns: What causes failures and how to avoid them
+- common_procedures: Most frequently used procedures
+- learning_progress: How knowledge has grown over time
+
+Examples:
+- {"analysis_type": "success_factors", "scope": "code_review", "depth": 3}
+- {"analysis_type": "failure_patterns", "include_examples": true, "max_items": 5}
+""",
+    args_schema=ReflectArgs,
+)
+
+
+GET_MEMORY_STATS_TOOL = MemoryToolDefinition(
+    name="get_memory_stats",
+    description="""Get statistics about the agent's memory usage.
+
+Returns information about:
+- Total memories stored by type
+- Storage utilization
+- Recent activity summary
+- Memory health indicators
+
+Use this to understand memory capacity and usage patterns.
+
+Examples:
+- {"include_breakdown": true, "include_recent_activity": true}
+- {"time_range_days": 30, "include_breakdown": true}
+""",
+    args_schema=GetMemoryStatsArgs,
+)
+
+
+SEARCH_PROCEDURES_TOOL = MemoryToolDefinition(
+    name="search_procedures",
+    description="""Find relevant procedures for a given situation.
+
+Use this tool when you need to:
+- Find the best way to handle a situation
+- Look up proven approaches to problems
+- Get step-by-step guidance for tasks
+
+Returns procedures ranked by relevance and success rate.
+
+Examples:
+- {"trigger": "Deploying to production", "min_success_rate": 0.8}
+- {"trigger": "Handling merge conflicts", "task_type": "git_operations", "limit": 3}
+""",
+    args_schema=SearchProceduresArgs,
+)
+
+
+RECORD_OUTCOME_TOOL = MemoryToolDefinition(
+    name="record_outcome",
+    description="""Record the outcome of a task execution.
+
+Use this tool after completing a task to:
+- Update procedure success/failure rates
+- Store lessons learned for future reference
+- Improve procedure recommendations
+
+This helps the memory system learn from experience.
+
+Examples:
+- {"task_type": "code_review", "outcome": "success", "lessons_learned": "Breaking changes caught early"}
+- {"task_type": "deployment", "outcome": "failure", "error_details": "Database migration timeout", "lessons_learned": "Need to test migrations locally first"}
+""",
+    args_schema=RecordOutcomeArgs,
+)
+
+
+# All tool definitions in a dictionary for easy lookup
+MEMORY_TOOL_DEFINITIONS: dict[str, MemoryToolDefinition] = {
+    "remember": REMEMBER_TOOL,
+    "recall": RECALL_TOOL,
+    "forget": FORGET_TOOL,
+    "reflect": REFLECT_TOOL,
+    "get_memory_stats": GET_MEMORY_STATS_TOOL,
+    "search_procedures": SEARCH_PROCEDURES_TOOL,
+    "record_outcome": RECORD_OUTCOME_TOOL,
+}
+
+
+def get_all_tool_schemas() -> list[dict[str, Any]]:
+    """Get MCP-formatted schemas for all memory tools."""
+    return [tool.to_mcp_format() for tool in MEMORY_TOOL_DEFINITIONS.values()]
+
+
+def get_tool_definition(name: str) -> MemoryToolDefinition | None:
+    """Get a specific tool definition by name."""
+    return MEMORY_TOOL_DEFINITIONS.get(name)

backend/app/services/memory/procedural/__init__.py

@@ -0,0 +1,22 @@
+# app/services/memory/procedural/__init__.py
+"""
+Procedural Memory
+
+Learned skills and procedures from successful task patterns.
+"""
+
+from .matching import (
+    MatchContext,
+    MatchResult,
+    ProcedureMatcher,
+    get_procedure_matcher,
+)
+from .memory import ProceduralMemory
+
+__all__ = [
+    "MatchContext",
+    "MatchResult",
+    "ProceduralMemory",
+    "ProcedureMatcher",
+    "get_procedure_matcher",
+]

backend/app/services/memory/procedural/matching.py

@@ -0,0 +1,291 @@
+# app/services/memory/procedural/matching.py
+"""
+Procedure Matching.
+
+Provides utilities for matching procedures to contexts,
+ranking procedures by relevance, and suggesting procedures.
+"""
+
+import logging
+import re
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+
+from app.services.memory.types import Procedure
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class MatchResult:
+    """Result of a procedure match."""
+
+    procedure: Procedure
+    score: float
+    matched_terms: list[str] = field(default_factory=list)
+    match_type: str = "keyword"  # keyword, semantic, pattern
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "procedure_id": str(self.procedure.id),
+            "procedure_name": self.procedure.name,
+            "score": self.score,
+            "matched_terms": self.matched_terms,
+            "match_type": self.match_type,
+            "success_rate": self.procedure.success_rate,
+        }
+
+
+@dataclass
+class MatchContext:
+    """Context for procedure matching."""
+
+    query: str
+    task_type: str | None = None
+    project_id: Any | None = None
+    agent_type_id: Any | None = None
+    max_results: int = 5
+    min_score: float = 0.3
+    require_success_rate: float | None = None
+
+
+class ProcedureMatcher:
+    """
+    Matches procedures to contexts using multiple strategies.
+
+    Matching strategies:
+    - Keyword matching on trigger pattern and name
+    - Pattern-based matching using regex
+    - Success rate weighting
+
+    In production, this would be augmented with vector similarity search.
+    """
+
+    # Common task-related keywords for boosting
+    TASK_KEYWORDS: ClassVar[set[str]] = {
+        "create",
+        "update",
+        "delete",
+        "fix",
+        "implement",
+        "add",
+        "remove",
+        "refactor",
+        "test",
+        "deploy",
+        "configure",
+        "setup",
+        "build",
+        "debug",
+        "optimize",
+    }
+
+    def __init__(self) -> None:
+        """Initialize the matcher."""
+        self._compiled_patterns: dict[str, re.Pattern[str]] = {}
+
+    def match(
+        self,
+        procedures: list[Procedure],
+        context: MatchContext,
+    ) -> list[MatchResult]:
+        """
+        Match procedures against a context.
+
+        Args:
+            procedures: List of procedures to match
+            context: Matching context
+
+        Returns:
+            List of match results, sorted by score (highest first)
+        """
+        results: list[MatchResult] = []
+
+        query_terms = self._extract_terms(context.query)
+        query_lower = context.query.lower()
+
+        for procedure in procedures:
+            score, matched = self._calculate_match_score(
+                procedure=procedure,
+                query_terms=query_terms,
+                query_lower=query_lower,
+                context=context,
+            )
+
+            if score >= context.min_score:
+                # Apply success rate boost
+                if context.require_success_rate is not None:
+                    if procedure.success_rate < context.require_success_rate:
+                        continue
+
+                # Boost score based on success rate
+                success_boost = procedure.success_rate * 0.2
+                final_score = min(1.0, score + success_boost)
+
+                results.append(
+                    MatchResult(
+                        procedure=procedure,
+                        score=final_score,
+                        matched_terms=matched,
+                        match_type="keyword",
+                    )
+                )
+
+        # Sort by score descending
+        results.sort(key=lambda r: r.score, reverse=True)
+
+        return results[: context.max_results]
+
+    def _extract_terms(self, text: str) -> list[str]:
+        """Extract searchable terms from text."""
+        # Remove special characters and split
+        clean = re.sub(r"[^\w\s-]", " ", text.lower())
+        terms = clean.split()
+
+        # Filter out very short terms
+        return [t for t in terms if len(t) >= 2]
+
+    def _calculate_match_score(
+        self,
+        procedure: Procedure,
+        query_terms: list[str],
+        query_lower: str,
+        context: MatchContext,
+    ) -> tuple[float, list[str]]:
+        """
+        Calculate match score between procedure and query.
+
+        Returns:
+            Tuple of (score, matched_terms)
+        """
+        score = 0.0
+        matched: list[str] = []
+
+        trigger_lower = procedure.trigger_pattern.lower()
+        name_lower = procedure.name.lower()
+
+        # Exact name match - high score
+        if name_lower in query_lower or query_lower in name_lower:
+            score += 0.5
+            matched.append(f"name:{procedure.name}")
+
+        # Trigger pattern match
+        if trigger_lower in query_lower or query_lower in trigger_lower:
+            score += 0.4
+            matched.append(f"trigger:{procedure.trigger_pattern[:30]}")
+
+        # Term-by-term matching
+        for term in query_terms:
+            if term in trigger_lower:
+                score += 0.1
+                matched.append(term)
+            elif term in name_lower:
+                score += 0.08
+                matched.append(term)
+
+            # Boost for task keywords
+            if term in self.TASK_KEYWORDS:
+                if term in trigger_lower or term in name_lower:
+                    score += 0.05
+
+        # Task type match if provided
+        if context.task_type:
+            task_type_lower = context.task_type.lower()
+            if task_type_lower in trigger_lower or task_type_lower in name_lower:
+                score += 0.3
+                matched.append(f"task_type:{context.task_type}")
+
+        # Regex pattern matching on trigger
+        try:
+            pattern = self._get_or_compile_pattern(trigger_lower)
+            if pattern and pattern.search(query_lower):
+                score += 0.25
+                matched.append("pattern_match")
+        except re.error:
+            pass  # Invalid regex, skip pattern matching
+
+        return min(1.0, score), matched
+
+    def _get_or_compile_pattern(self, pattern: str) -> re.Pattern[str] | None:
+        """Get or compile a regex pattern with caching."""
+        if pattern in self._compiled_patterns:
+            return self._compiled_patterns[pattern]
+
+        # Only compile if it looks like a regex pattern
+        if not any(c in pattern for c in r"\.*+?[]{}|()^$"):
+            return None
+
+        try:
+            compiled = re.compile(pattern, re.IGNORECASE)
+            self._compiled_patterns[pattern] = compiled
+            return compiled
+        except re.error:
+            return None
+
+    def rank_by_relevance(
+        self,
+        procedures: list[Procedure],
+        task_type: str,
+    ) -> list[Procedure]:
+        """
+        Rank procedures by relevance to a task type.
+
+        Args:
+            procedures: Procedures to rank
+            task_type: Task type for relevance
+
+        Returns:
+            Procedures sorted by relevance
+        """
+        context = MatchContext(
+            query=task_type,
+            task_type=task_type,
+            min_score=0.0,
+            max_results=len(procedures),
+        )
+
+        results = self.match(procedures, context)
+        return [r.procedure for r in results]
+
+    def suggest_procedures(
+        self,
+        procedures: list[Procedure],
+        query: str,
+        min_success_rate: float = 0.5,
+        max_suggestions: int = 3,
+    ) -> list[MatchResult]:
+        """
+        Suggest the best procedures for a query.
+
+        Only suggests procedures with sufficient success rate.
+
+        Args:
+            procedures: Available procedures
+            query: Query/context
+            min_success_rate: Minimum success rate to suggest
+            max_suggestions: Maximum suggestions
+
+        Returns:
+            List of procedure suggestions
+        """
+        context = MatchContext(
+            query=query,
+            max_results=max_suggestions,
+            min_score=0.2,
+            require_success_rate=min_success_rate,
+        )
+
+        return self.match(procedures, context)
+
+
+# Singleton matcher instance
+_matcher: ProcedureMatcher | None = None
+
+
+def get_procedure_matcher() -> ProcedureMatcher:
+    """Get the singleton procedure matcher instance."""
+    global _matcher
+    if _matcher is None:
+        _matcher = ProcedureMatcher()
+    return _matcher

backend/app/services/memory/procedural/memory.py

@@ -0,0 +1,724 @@
+# app/services/memory/procedural/memory.py
+"""
+Procedural Memory Implementation.
+
+Provides storage and retrieval for learned procedures (skills)
+derived from successful task execution patterns.
+"""
+
+import logging
+import time
+from datetime import UTC, datetime
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import and_, desc, or_, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.memory.procedure import Procedure as ProcedureModel
+from app.services.memory.config import get_memory_settings
+from app.services.memory.types import Procedure, ProcedureCreate, RetrievalResult, Step
+
+logger = logging.getLogger(__name__)
+
+
+def _model_to_procedure(model: ProcedureModel) -> Procedure:
+    """Convert SQLAlchemy model to Procedure dataclass."""
+    return Procedure(
+        id=model.id,  # type: ignore[arg-type]
+        project_id=model.project_id,  # type: ignore[arg-type]
+        agent_type_id=model.agent_type_id,  # type: ignore[arg-type]
+        name=model.name,  # type: ignore[arg-type]
+        trigger_pattern=model.trigger_pattern,  # type: ignore[arg-type]
+        steps=model.steps or [],  # type: ignore[arg-type]
+        success_count=model.success_count,  # type: ignore[arg-type]
+        failure_count=model.failure_count,  # type: ignore[arg-type]
+        last_used=model.last_used,  # type: ignore[arg-type]
+        embedding=None,  # Don't expose raw embedding
+        created_at=model.created_at,  # type: ignore[arg-type]
+        updated_at=model.updated_at,  # type: ignore[arg-type]
+    )
+
+
+class ProceduralMemory:
+    """
+    Procedural Memory Service.
+
+    Provides procedure storage and retrieval:
+    - Record procedures from successful task patterns
+    - Find matching procedures by trigger pattern
+    - Track success/failure rates
+    - Get best procedure for a task type
+    - Update procedure steps
+
+    Performance target: <50ms P95 for matching
+    """
+
+    def __init__(
+        self,
+        session: AsyncSession,
+        embedding_generator: Any | None = None,
+    ) -> None:
+        """
+        Initialize procedural memory.
+
+        Args:
+            session: Database session
+            embedding_generator: Optional embedding generator for semantic matching
+        """
+        self._session = session
+        self._embedding_generator = embedding_generator
+        self._settings = get_memory_settings()
+
+    @classmethod
+    async def create(
+        cls,
+        session: AsyncSession,
+        embedding_generator: Any | None = None,
+    ) -> "ProceduralMemory":
+        """
+        Factory method to create ProceduralMemory.
+
+        Args:
+            session: Database session
+            embedding_generator: Optional embedding generator
+
+        Returns:
+            Configured ProceduralMemory instance
+        """
+        return cls(session=session, embedding_generator=embedding_generator)
+
+    # =========================================================================
+    # Procedure Recording
+    # =========================================================================
+
+    async def record_procedure(self, procedure: ProcedureCreate) -> Procedure:
+        """
+        Record a new procedure or update an existing one.
+
+        If a procedure with the same name exists in the same scope,
+        its steps will be updated and success count incremented.
+
+        Args:
+            procedure: Procedure data to record
+
+        Returns:
+            The created or updated procedure
+        """
+        # Check for existing procedure with same name
+        existing = await self._find_existing_procedure(
+            project_id=procedure.project_id,
+            agent_type_id=procedure.agent_type_id,
+            name=procedure.name,
+        )
+
+        if existing is not None:
+            # Update existing procedure
+            return await self._update_existing_procedure(
+                existing=existing,
+                new_steps=procedure.steps,
+                new_trigger=procedure.trigger_pattern,
+            )
+
+        # Create new procedure
+        now = datetime.now(UTC)
+
+        # Generate embedding if possible
+        embedding = None
+        if self._embedding_generator is not None:
+            embedding_text = self._create_embedding_text(procedure)
+            embedding = await self._embedding_generator.generate(embedding_text)
+
+        model = ProcedureModel(
+            project_id=procedure.project_id,
+            agent_type_id=procedure.agent_type_id,
+            name=procedure.name,
+            trigger_pattern=procedure.trigger_pattern,
+            steps=procedure.steps,
+            success_count=1,  # New procedures start with 1 success (they worked)
+            failure_count=0,
+            last_used=now,
+            embedding=embedding,
+        )
+
+        self._session.add(model)
+        await self._session.flush()
+        await self._session.refresh(model)
+
+        logger.info(
+            f"Recorded new procedure: {procedure.name} with {len(procedure.steps)} steps"
+        )
+
+        return _model_to_procedure(model)
+
+    async def _find_existing_procedure(
+        self,
+        project_id: UUID | None,
+        agent_type_id: UUID | None,
+        name: str,
+    ) -> ProcedureModel | None:
+        """Find an existing procedure with the same name in the same scope."""
+        query = select(ProcedureModel).where(ProcedureModel.name == name)
+
+        if project_id is not None:
+            query = query.where(ProcedureModel.project_id == project_id)
+        else:
+            query = query.where(ProcedureModel.project_id.is_(None))
+
+        if agent_type_id is not None:
+            query = query.where(ProcedureModel.agent_type_id == agent_type_id)
+        else:
+            query = query.where(ProcedureModel.agent_type_id.is_(None))
+
+        result = await self._session.execute(query)
+        return result.scalar_one_or_none()
+
+    async def _update_existing_procedure(
+        self,
+        existing: ProcedureModel,
+        new_steps: list[dict[str, Any]],
+        new_trigger: str,
+    ) -> Procedure:
+        """Update an existing procedure with new steps."""
+        now = datetime.now(UTC)
+
+        # Merge steps intelligently - keep existing order, add new steps
+        merged_steps = self._merge_steps(
+            existing.steps or [],  # type: ignore[arg-type]
+            new_steps,
+        )
+
+        stmt = (
+            update(ProcedureModel)
+            .where(ProcedureModel.id == existing.id)
+            .values(
+                steps=merged_steps,
+                trigger_pattern=new_trigger,
+                success_count=ProcedureModel.success_count + 1,
+                last_used=now,
+                updated_at=now,
+            )
+            .returning(ProcedureModel)
+        )
+
+        result = await self._session.execute(stmt)
+        updated_model = result.scalar_one()
+        await self._session.flush()
+
+        logger.info(f"Updated existing procedure: {existing.name}")
+
+        return _model_to_procedure(updated_model)
+
+    def _merge_steps(
+        self,
+        existing_steps: list[dict[str, Any]],
+        new_steps: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """Merge steps from a new execution with existing steps."""
+        if not existing_steps:
+            return new_steps
+        if not new_steps:
+            return existing_steps
+
+        # For now, use the new steps if they differ significantly
+        # In production, this could use more sophisticated merging
+        if len(new_steps) != len(existing_steps):
+            # If structure changed, prefer newer steps
+            return new_steps
+
+        # Merge step-by-step, preferring new data where available
+        merged = []
+        for i, new_step in enumerate(new_steps):
+            if i < len(existing_steps):
+                # Merge with existing step
+                step = {**existing_steps[i], **new_step}
+            else:
+                step = new_step
+            merged.append(step)
+
+        return merged
+
+    def _create_embedding_text(self, procedure: ProcedureCreate) -> str:
+        """Create text for embedding from procedure data."""
+        steps_text = " ".join(step.get("action", "") for step in procedure.steps)
+        return f"{procedure.name} {procedure.trigger_pattern} {steps_text}"
+
+    # =========================================================================
+    # Procedure Retrieval
+    # =========================================================================
+
+    async def find_matching(
+        self,
+        context: str,
+        project_id: UUID | None = None,
+        agent_type_id: UUID | None = None,
+        limit: int = 5,
+    ) -> list[Procedure]:
+        """
+        Find procedures matching the given context.
+
+        Args:
+            context: Context/trigger to match against
+            project_id: Optional project to search within
+            agent_type_id: Optional agent type filter
+            limit: Maximum results
+
+        Returns:
+            List of matching procedures
+        """
+        result = await self._find_matching_with_metadata(
+            context=context,
+            project_id=project_id,
+            agent_type_id=agent_type_id,
+            limit=limit,
+        )
+        return result.items
+
+    async def _find_matching_with_metadata(
+        self,
+        context: str,
+        project_id: UUID | None = None,
+        agent_type_id: UUID | None = None,
+        limit: int = 5,
+    ) -> RetrievalResult[Procedure]:
+        """Find matching procedures with full result metadata."""
+        start_time = time.perf_counter()
+
+        # Build base query - prioritize by success rate
+        stmt = (
+            select(ProcedureModel)
+            .order_by(
+                desc(
+                    ProcedureModel.success_count
+                    / (ProcedureModel.success_count + ProcedureModel.failure_count + 1)
+                ),
+                desc(ProcedureModel.last_used),
+            )
+            .limit(limit)
+        )
+
+        # Apply scope filters
+        if project_id is not None:
+            stmt = stmt.where(
+                or_(
+                    ProcedureModel.project_id == project_id,
+                    ProcedureModel.project_id.is_(None),
+                )
+            )
+
+        if agent_type_id is not None:
+            stmt = stmt.where(
+                or_(
+                    ProcedureModel.agent_type_id == agent_type_id,
+                    ProcedureModel.agent_type_id.is_(None),
+                )
+            )
+
+        # Text-based matching on trigger pattern and name
+        # TODO: Implement proper vector similarity search when pgvector is integrated
+        search_terms = context.lower().split()[:5]  # Limit to 5 terms
+        if search_terms:
+            conditions = []
+            for term in search_terms:
+                term_pattern = f"%{term}%"
+                conditions.append(
+                    or_(
+                        ProcedureModel.trigger_pattern.ilike(term_pattern),
+                        ProcedureModel.name.ilike(term_pattern),
+                    )
+                )
+            if conditions:
+                stmt = stmt.where(or_(*conditions))
+
+        result = await self._session.execute(stmt)
+        models = list(result.scalars().all())
+
+        latency_ms = (time.perf_counter() - start_time) * 1000
+
+        return RetrievalResult(
+            items=[_model_to_procedure(m) for m in models],
+            total_count=len(models),
+            query=context,
+            retrieval_type="procedural",
+            latency_ms=latency_ms,
+            metadata={"project_id": str(project_id) if project_id else None},
+        )
+
+    async def get_best_procedure(
+        self,
+        task_type: str,
+        project_id: UUID | None = None,
+        agent_type_id: UUID | None = None,
+        min_success_rate: float = 0.5,
+        min_uses: int = 1,
+    ) -> Procedure | None:
+        """
+        Get the best procedure for a given task type.
+
+        Returns the procedure with the highest success rate that
+        meets the minimum thresholds.
+
+        Args:
+            task_type: Task type to find procedure for
+            project_id: Optional project scope
+            agent_type_id: Optional agent type scope
+            min_success_rate: Minimum required success rate
+            min_uses: Minimum number of uses required
+
+        Returns:
+            Best matching procedure or None
+        """
+        # Build query for procedures matching task type
+        stmt = (
+            select(ProcedureModel)
+            .where(
+                and_(
+                    (ProcedureModel.success_count + ProcedureModel.failure_count)
+                    >= min_uses,
+                    or_(
+                        ProcedureModel.trigger_pattern.ilike(f"%{task_type}%"),
+                        ProcedureModel.name.ilike(f"%{task_type}%"),
+                    ),
+                )
+            )
+            .order_by(
+                desc(
+                    ProcedureModel.success_count
+                    / (ProcedureModel.success_count + ProcedureModel.failure_count + 1)
+                ),
+                desc(ProcedureModel.last_used),
+            )
+            .limit(10)
+        )
+
+        # Apply scope filters
+        if project_id is not None:
+            stmt = stmt.where(
+                or_(
+                    ProcedureModel.project_id == project_id,
+                    ProcedureModel.project_id.is_(None),
+                )
+            )
+
+        if agent_type_id is not None:
+            stmt = stmt.where(
+                or_(
+                    ProcedureModel.agent_type_id == agent_type_id,
+                    ProcedureModel.agent_type_id.is_(None),
+                )
+            )
+
+        result = await self._session.execute(stmt)
+        models = list(result.scalars().all())
+
+        # Filter by success rate in Python (SQLAlchemy division in WHERE is complex)
+        for model in models:
+            success = float(model.success_count)
+            failure = float(model.failure_count)
+            total = success + failure
+            if total > 0 and (success / total) >= min_success_rate:
+                logger.debug(
+                    f"Found best procedure for '{task_type}': {model.name} "
+                    f"(success_rate={success / total:.2%})"
+                )
+                return _model_to_procedure(model)
+
+        return None
+
+    async def get_by_id(self, procedure_id: UUID) -> Procedure | None:
+        """Get a procedure by ID."""
+        query = select(ProcedureModel).where(ProcedureModel.id == procedure_id)
+        result = await self._session.execute(query)
+        model = result.scalar_one_or_none()
+        return _model_to_procedure(model) if model else None
+
+    # =========================================================================
+    # Outcome Recording
+    # =========================================================================
+
+    async def record_outcome(
+        self,
+        procedure_id: UUID,
+        success: bool,
+    ) -> Procedure:
+        """
+        Record the outcome of using a procedure.
+
+        Updates the success or failure count and last_used timestamp.
+
+        Args:
+            procedure_id: Procedure that was used
+            success: Whether the procedure succeeded
+
+        Returns:
+            Updated procedure
+
+        Raises:
+            ValueError: If procedure not found
+        """
+        query = select(ProcedureModel).where(ProcedureModel.id == procedure_id)
+        result = await self._session.execute(query)
+        model = result.scalar_one_or_none()
+
+        if model is None:
+            raise ValueError(f"Procedure not found: {procedure_id}")
+
+        now = datetime.now(UTC)
+
+        if success:
+            stmt = (
+                update(ProcedureModel)
+                .where(ProcedureModel.id == procedure_id)
+                .values(
+                    success_count=ProcedureModel.success_count + 1,
+                    last_used=now,
+                    updated_at=now,
+                )
+                .returning(ProcedureModel)
+            )
+        else:
+            stmt = (
+                update(ProcedureModel)
+                .where(ProcedureModel.id == procedure_id)
+                .values(
+                    failure_count=ProcedureModel.failure_count + 1,
+                    last_used=now,
+                    updated_at=now,
+                )
+                .returning(ProcedureModel)
+            )
+
+        result = await self._session.execute(stmt)
+        updated_model = result.scalar_one()
+        await self._session.flush()
+
+        outcome = "success" if success else "failure"
+        logger.info(
+            f"Recorded {outcome} for procedure {procedure_id}: "
+            f"success_rate={updated_model.success_rate:.2%}"
+        )
+
+        return _model_to_procedure(updated_model)
+
+    # =========================================================================
+    # Step Management
+    # =========================================================================
+
+    async def update_steps(
+        self,
+        procedure_id: UUID,
+        steps: list[Step],
+    ) -> Procedure:
+        """
+        Update the steps of a procedure.
+
+        Args:
+            procedure_id: Procedure to update
+            steps: New steps
+
+        Returns:
+            Updated procedure
+
+        Raises:
+            ValueError: If procedure not found
+        """
+        query = select(ProcedureModel).where(ProcedureModel.id == procedure_id)
+        result = await self._session.execute(query)
+        model = result.scalar_one_or_none()
+
+        if model is None:
+            raise ValueError(f"Procedure not found: {procedure_id}")
+
+        # Convert Step objects to dictionaries
+        steps_dict = [
+            {
+                "order": step.order,
+                "action": step.action,
+                "parameters": step.parameters,
+                "expected_outcome": step.expected_outcome,
+                "fallback_action": step.fallback_action,
+            }
+            for step in steps
+        ]
+
+        now = datetime.now(UTC)
+        stmt = (
+            update(ProcedureModel)
+            .where(ProcedureModel.id == procedure_id)
+            .values(
+                steps=steps_dict,
+                updated_at=now,
+            )
+            .returning(ProcedureModel)
+        )
+
+        result = await self._session.execute(stmt)
+        updated_model = result.scalar_one()
+        await self._session.flush()
+
+        logger.info(f"Updated steps for procedure {procedure_id}: {len(steps)} steps")
+
+        return _model_to_procedure(updated_model)
+
+    # =========================================================================
+    # Statistics & Management
+    # =========================================================================
+
+    async def get_stats(
+        self,
+        project_id: UUID | None = None,
+        agent_type_id: UUID | None = None,
+    ) -> dict[str, Any]:
+        """
+        Get statistics about procedural memory.
+
+        Args:
+            project_id: Optional project to get stats for
+            agent_type_id: Optional agent type filter
+
+        Returns:
+            Dictionary with statistics
+        """
+        query = select(ProcedureModel)
+
+        if project_id is not None:
+            query = query.where(
+                or_(
+                    ProcedureModel.project_id == project_id,
+                    ProcedureModel.project_id.is_(None),
+                )
+            )
+
+        if agent_type_id is not None:
+            query = query.where(
+                or_(
+                    ProcedureModel.agent_type_id == agent_type_id,
+                    ProcedureModel.agent_type_id.is_(None),
+                )
+            )
+
+        result = await self._session.execute(query)
+        models = list(result.scalars().all())
+
+        if not models:
+            return {
+                "total_procedures": 0,
+                "avg_success_rate": 0.0,
+                "avg_steps_count": 0.0,
+                "total_uses": 0,
+                "high_success_count": 0,
+                "low_success_count": 0,
+            }
+
+        success_rates = [m.success_rate for m in models]
+        step_counts = [len(m.steps or []) for m in models]
+        total_uses = sum(m.total_uses for m in models)
+
+        return {
+            "total_procedures": len(models),
+            "avg_success_rate": sum(success_rates) / len(success_rates),
+            "avg_steps_count": sum(step_counts) / len(step_counts),
+            "total_uses": total_uses,
+            "high_success_count": sum(1 for r in success_rates if r >= 0.8),
+            "low_success_count": sum(1 for r in success_rates if r < 0.5),
+        }
+
+    async def count(
+        self,
+        project_id: UUID | None = None,
+        agent_type_id: UUID | None = None,
+    ) -> int:
+        """
+        Count procedures in scope.
+
+        Args:
+            project_id: Optional project to count for
+            agent_type_id: Optional agent type filter
+
+        Returns:
+            Number of procedures
+        """
+        query = select(ProcedureModel)
+
+        if project_id is not None:
+            query = query.where(
+                or_(
+                    ProcedureModel.project_id == project_id,
+                    ProcedureModel.project_id.is_(None),
+                )
+            )
+
+        if agent_type_id is not None:
+            query = query.where(
+                or_(
+                    ProcedureModel.agent_type_id == agent_type_id,
+                    ProcedureModel.agent_type_id.is_(None),
+                )
+            )
+
+        result = await self._session.execute(query)
+        return len(list(result.scalars().all()))
+
+    async def delete(self, procedure_id: UUID) -> bool:
+        """
+        Delete a procedure.
+
+        Args:
+            procedure_id: Procedure to delete
+
+        Returns:
+            True if deleted, False if not found
+        """
+        query = select(ProcedureModel).where(ProcedureModel.id == procedure_id)
+        result = await self._session.execute(query)
+        model = result.scalar_one_or_none()
+
+        if model is None:
+            return False
+
+        await self._session.delete(model)
+        await self._session.flush()
+
+        logger.info(f"Deleted procedure {procedure_id}")
+        return True
+
+    async def get_procedures_by_success_rate(
+        self,
+        min_rate: float = 0.0,
+        max_rate: float = 1.0,
+        project_id: UUID | None = None,
+        limit: int = 20,
+    ) -> list[Procedure]:
+        """
+        Get procedures within a success rate range.
+
+        Args:
+            min_rate: Minimum success rate
+            max_rate: Maximum success rate
+            project_id: Optional project scope
+            limit: Maximum results
+
+        Returns:
+            List of procedures
+        """
+        query = (
+            select(ProcedureModel)
+            .order_by(desc(ProcedureModel.last_used))
+            .limit(limit * 2)  # Fetch more since we filter in Python
+        )
+
+        if project_id is not None:
+            query = query.where(
+                or_(
+                    ProcedureModel.project_id == project_id,
+                    ProcedureModel.project_id.is_(None),
+                )
+            )
+
+        result = await self._session.execute(query)
+        models = list(result.scalars().all())
+
+        # Filter by success rate in Python
+        filtered = [m for m in models if min_rate <= m.success_rate <= max_rate][:limit]
+
+        return [_model_to_procedure(m) for m in filtered]

backend/app/services/memory/scoping/__init__.py

@@ -0,0 +1,33 @@
+# app/services/memory/scoping/__init__.py
+"""
+Memory Scoping
+
+Hierarchical scoping for memory with inheritance:
+Global -> Project -> Agent Type -> Agent Instance -> Session
+"""
+
+from .resolver import (
+    ResolutionOptions,
+    ResolutionResult,
+    ScopeFilter,
+    ScopeResolver,
+    get_scope_resolver,
+)
+from .scope import (
+    ScopeInfo,
+    ScopeManager,
+    ScopePolicy,
+    get_scope_manager,
+)
+
+__all__ = [
+    "ResolutionOptions",
+    "ResolutionResult",
+    "ScopeFilter",
+    "ScopeInfo",
+    "ScopeManager",
+    "ScopePolicy",
+    "ScopeResolver",
+    "get_scope_manager",
+    "get_scope_resolver",
+]

backend/app/services/memory/scoping/resolver.py

@@ -0,0 +1,390 @@
+# app/services/memory/scoping/resolver.py
+"""
+Scope Resolution.
+
+Provides utilities for resolving memory queries across scope hierarchies,
+implementing inheritance and aggregation of memories from parent scopes.
+"""
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, TypeVar
+
+from app.services.memory.types import ScopeContext, ScopeLevel
+
+from .scope import ScopeManager, get_scope_manager
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+@dataclass
+class ResolutionResult[T]:
+    """Result of a scope resolution."""
+
+    items: list[T]
+    sources: list[ScopeContext]
+    total_from_each: dict[str, int] = field(default_factory=dict)
+    inherited_count: int = 0
+    own_count: int = 0
+
+    @property
+    def total_count(self) -> int:
+        """Get total items from all sources."""
+        return len(self.items)
+
+
+@dataclass
+class ResolutionOptions:
+    """Options for scope resolution."""
+
+    include_inherited: bool = True
+    max_inheritance_depth: int = 5
+    limit_per_scope: int = 100
+    total_limit: int = 500
+    deduplicate: bool = True
+    deduplicate_key: str | None = None  # Field to use for deduplication
+
+
+class ScopeResolver:
+    """
+    Resolves memory queries across scope hierarchies.
+
+    Features:
+    - Traverse scope hierarchy for inherited memories
+    - Aggregate results from multiple scope levels
+    - Apply access control policies
+    - Support deduplication across scopes
+    """
+
+    def __init__(
+        self,
+        manager: ScopeManager | None = None,
+    ) -> None:
+        """
+        Initialize the resolver.
+
+        Args:
+            manager: Scope manager to use (defaults to singleton)
+        """
+        self._manager = manager or get_scope_manager()
+
+    def resolve(
+        self,
+        scope: ScopeContext,
+        fetcher: Callable[[ScopeContext, int], list[T]],
+        options: ResolutionOptions | None = None,
+    ) -> ResolutionResult[T]:
+        """
+        Resolve memories for a scope, including inherited memories.
+
+        Args:
+            scope: Starting scope
+            fetcher: Function to fetch items for a scope (scope, limit) -> items
+            options: Resolution options
+
+        Returns:
+            Resolution result with items from all scopes
+        """
+        opts = options or ResolutionOptions()
+
+        all_items: list[T] = []
+        sources: list[ScopeContext] = []
+        counts: dict[str, int] = {}
+        seen_keys: set[Any] = set()
+
+        # Collect scopes to query (starting from current, going up to ancestors)
+        scopes_to_query = self._collect_queryable_scopes(
+            scope=scope,
+            max_depth=opts.max_inheritance_depth if opts.include_inherited else 0,
+        )
+
+        own_count = 0
+        inherited_count = 0
+        remaining_limit = opts.total_limit
+
+        for i, query_scope in enumerate(scopes_to_query):
+            if remaining_limit <= 0:
+                break
+
+            # Check access policy
+            policy = self._manager.get_policy(query_scope)
+            if not policy.allows_read():
+                continue
+            if i > 0 and not policy.allows_inherit():
+                continue
+
+            # Fetch items for this scope
+            scope_limit = min(opts.limit_per_scope, remaining_limit)
+            items = fetcher(query_scope, scope_limit)
+
+            # Apply deduplication
+            if opts.deduplicate and opts.deduplicate_key:
+                items = self._deduplicate(items, opts.deduplicate_key, seen_keys)
+
+            if items:
+                all_items.extend(items)
+                sources.append(query_scope)
+                key = f"{query_scope.scope_type.value}:{query_scope.scope_id}"
+                counts[key] = len(items)
+
+                if i == 0:
+                    own_count = len(items)
+                else:
+                    inherited_count += len(items)
+
+                remaining_limit -= len(items)
+
+        logger.debug(
+            f"Resolved {len(all_items)} items from {len(sources)} scopes "
+            f"(own={own_count}, inherited={inherited_count})"
+        )
+
+        return ResolutionResult(
+            items=all_items[: opts.total_limit],
+            sources=sources,
+            total_from_each=counts,
+            own_count=own_count,
+            inherited_count=inherited_count,
+        )
+
+    def _collect_queryable_scopes(
+        self,
+        scope: ScopeContext,
+        max_depth: int,
+    ) -> list[ScopeContext]:
+        """Collect scopes to query, from current to ancestors."""
+        scopes: list[ScopeContext] = [scope]
+
+        if max_depth <= 0:
+            return scopes
+
+        current = scope.parent
+        depth = 0
+
+        while current is not None and depth < max_depth:
+            scopes.append(current)
+            current = current.parent
+            depth += 1
+
+        return scopes
+
+    def _deduplicate(
+        self,
+        items: list[T],
+        key_field: str,
+        seen_keys: set[Any],
+    ) -> list[T]:
+        """Remove duplicate items based on a key field."""
+        unique: list[T] = []
+
+        for item in items:
+            key = getattr(item, key_field, None)
+            if key is None:
+                # If no key, include the item
+                unique.append(item)
+            elif key not in seen_keys:
+                seen_keys.add(key)
+                unique.append(item)
+
+        return unique
+
+    def get_visible_scopes(
+        self,
+        scope: ScopeContext,
+    ) -> list[ScopeContext]:
+        """
+        Get all scopes visible from a given scope.
+
+        A scope can see itself and all its ancestors (if inheritance allowed).
+
+        Args:
+            scope: Starting scope
+
+        Returns:
+            List of visible scopes (from most specific to most general)
+        """
+        visible = [scope]
+
+        current = scope.parent
+        while current is not None:
+            policy = self._manager.get_policy(current)
+            if policy.allows_inherit():
+                visible.append(current)
+            else:
+                break  # Stop at first non-inheritable scope
+            current = current.parent
+
+        return visible
+
+    def find_write_scope(
+        self,
+        target_level: ScopeLevel,
+        scope: ScopeContext,
+    ) -> ScopeContext | None:
+        """
+        Find the appropriate scope for writing at a target level.
+
+        Walks up the hierarchy to find a scope at the target level
+        that allows writing.
+
+        Args:
+            target_level: Desired scope level
+            scope: Starting scope
+
+        Returns:
+            Scope to write to, or None if not found/not allowed
+        """
+        # First check if current scope is at target level
+        if scope.scope_type == target_level:
+            policy = self._manager.get_policy(scope)
+            return scope if policy.allows_write() else None
+
+        # Check ancestors
+        current = scope.parent
+        while current is not None:
+            if current.scope_type == target_level:
+                policy = self._manager.get_policy(current)
+                return current if policy.allows_write() else None
+            current = current.parent
+
+        return None
+
+    def resolve_scope_from_memory(
+        self,
+        memory_type: str,
+        project_id: str | None = None,
+        agent_type_id: str | None = None,
+        agent_instance_id: str | None = None,
+        session_id: str | None = None,
+    ) -> tuple[ScopeContext, ScopeLevel]:
+        """
+        Resolve the appropriate scope for a memory operation.
+
+        Different memory types have different scope requirements:
+        - working: Session or Agent Instance
+        - episodic: Agent Instance or Project
+        - semantic: Project or Global
+        - procedural: Agent Type or Project
+
+        Args:
+            memory_type: Type of memory
+            project_id: Project ID
+            agent_type_id: Agent type ID
+            agent_instance_id: Agent instance ID
+            session_id: Session ID
+
+        Returns:
+            Tuple of (scope context, recommended level)
+        """
+        # Build full scope chain
+        scope = self._manager.create_scope_from_ids(
+            project_id=project_id if project_id else None,  # type: ignore[arg-type]
+            agent_type_id=agent_type_id if agent_type_id else None,  # type: ignore[arg-type]
+            agent_instance_id=agent_instance_id if agent_instance_id else None,  # type: ignore[arg-type]
+            session_id=session_id,
+        )
+
+        # Determine recommended level based on memory type
+        recommended = self._get_recommended_level(memory_type)
+
+        return scope, recommended
+
+    def _get_recommended_level(self, memory_type: str) -> ScopeLevel:
+        """Get recommended scope level for a memory type."""
+        recommendations = {
+            "working": ScopeLevel.SESSION,
+            "episodic": ScopeLevel.AGENT_INSTANCE,
+            "semantic": ScopeLevel.PROJECT,
+            "procedural": ScopeLevel.AGENT_TYPE,
+        }
+        return recommendations.get(memory_type, ScopeLevel.PROJECT)
+
+    def validate_write_access(
+        self,
+        scope: ScopeContext,
+        memory_type: str,
+    ) -> bool:
+        """
+        Validate that writing is allowed for the given scope and memory type.
+
+        Args:
+            scope: Scope to validate
+            memory_type: Type of memory to write
+
+        Returns:
+            True if write is allowed
+        """
+        policy = self._manager.get_policy(scope)
+
+        if not policy.allows_write():
+            return False
+
+        if not policy.allows_memory_type(memory_type):
+            return False
+
+        return True
+
+    def get_scope_chain(
+        self,
+        scope: ScopeContext,
+    ) -> list[tuple[ScopeLevel, str]]:
+        """
+        Get the scope chain as a list of (level, id) tuples.
+
+        Args:
+            scope: Scope to get chain for
+
+        Returns:
+            List of (level, id) tuples from root to leaf
+        """
+        chain: list[tuple[ScopeLevel, str]] = []
+
+        # Get full hierarchy
+        hierarchy = scope.get_hierarchy()
+        for ctx in hierarchy:
+            chain.append((ctx.scope_type, ctx.scope_id))
+
+        return chain
+
+
+@dataclass
+class ScopeFilter:
+    """Filter for querying across scopes."""
+
+    scope_types: list[ScopeLevel] | None = None
+    project_ids: list[str] | None = None
+    agent_type_ids: list[str] | None = None
+    include_global: bool = True
+
+    def matches(self, scope: ScopeContext) -> bool:
+        """Check if a scope matches this filter."""
+        if self.scope_types and scope.scope_type not in self.scope_types:
+            return False
+
+        if scope.scope_type == ScopeLevel.GLOBAL:
+            return self.include_global
+
+        if scope.scope_type == ScopeLevel.PROJECT:
+            if self.project_ids and scope.scope_id not in self.project_ids:
+                return False
+
+        if scope.scope_type == ScopeLevel.AGENT_TYPE:
+            if self.agent_type_ids and scope.scope_id not in self.agent_type_ids:
+                return False
+
+        return True
+
+
+# Singleton resolver instance
+_resolver: ScopeResolver | None = None
+
+
+def get_scope_resolver() -> ScopeResolver:
+    """Get the singleton scope resolver instance."""
+    global _resolver
+    if _resolver is None:
+        _resolver = ScopeResolver()
+    return _resolver

backend/app/services/memory/scoping/scope.py

@@ -0,0 +1,460 @@
+# app/services/memory/scoping/scope.py
+"""
+Scope Management.
+
+Provides utilities for managing memory scopes with hierarchical inheritance:
+Global -> Project -> Agent Type -> Agent Instance -> Session
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+from uuid import UUID
+
+from app.services.memory.types import ScopeContext, ScopeLevel
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ScopePolicy:
+    """Access control policy for a scope."""
+
+    scope_type: ScopeLevel
+    scope_id: str
+    can_read: bool = True
+    can_write: bool = True
+    can_inherit: bool = True
+    allowed_memory_types: list[str] = field(default_factory=lambda: ["all"])
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def allows_read(self) -> bool:
+        """Check if reading is allowed."""
+        return self.can_read
+
+    def allows_write(self) -> bool:
+        """Check if writing is allowed."""
+        return self.can_write
+
+    def allows_inherit(self) -> bool:
+        """Check if inheritance from parent is allowed."""
+        return self.can_inherit
+
+    def allows_memory_type(self, memory_type: str) -> bool:
+        """Check if a specific memory type is allowed."""
+        return (
+            "all" in self.allowed_memory_types
+            or memory_type in self.allowed_memory_types
+        )
+
+
+@dataclass
+class ScopeInfo:
+    """Information about a scope including its hierarchy."""
+
+    context: ScopeContext
+    policy: ScopePolicy
+    parent_info: "ScopeInfo | None" = None
+    child_count: int = 0
+    memory_count: int = 0
+
+    @property
+    def depth(self) -> int:
+        """Get the depth of this scope in the hierarchy."""
+        count = 0
+        current = self.parent_info
+        while current is not None:
+            count += 1
+            current = current.parent_info
+        return count
+
+
+class ScopeManager:
+    """
+    Manages memory scopes and their hierarchies.
+
+    Provides:
+    - Scope creation and validation
+    - Hierarchy management
+    - Access control policy management
+    - Scope inheritance rules
+    """
+
+    # Order of scope levels from root to leaf
+    SCOPE_ORDER: ClassVar[list[ScopeLevel]] = [
+        ScopeLevel.GLOBAL,
+        ScopeLevel.PROJECT,
+        ScopeLevel.AGENT_TYPE,
+        ScopeLevel.AGENT_INSTANCE,
+        ScopeLevel.SESSION,
+    ]
+
+    def __init__(self) -> None:
+        """Initialize the scope manager."""
+        # In-memory policy cache (would be backed by database in production)
+        self._policies: dict[str, ScopePolicy] = {}
+        self._default_policies = self._create_default_policies()
+
+    def _create_default_policies(self) -> dict[ScopeLevel, ScopePolicy]:
+        """Create default policies for each scope level."""
+        return {
+            ScopeLevel.GLOBAL: ScopePolicy(
+                scope_type=ScopeLevel.GLOBAL,
+                scope_id="global",
+                can_read=True,
+                can_write=False,  # Global writes require special permission
+                can_inherit=True,
+            ),
+            ScopeLevel.PROJECT: ScopePolicy(
+                scope_type=ScopeLevel.PROJECT,
+                scope_id="default",
+                can_read=True,
+                can_write=True,
+                can_inherit=True,
+            ),
+            ScopeLevel.AGENT_TYPE: ScopePolicy(
+                scope_type=ScopeLevel.AGENT_TYPE,
+                scope_id="default",
+                can_read=True,
+                can_write=True,
+                can_inherit=True,
+            ),
+            ScopeLevel.AGENT_INSTANCE: ScopePolicy(
+                scope_type=ScopeLevel.AGENT_INSTANCE,
+                scope_id="default",
+                can_read=True,
+                can_write=True,
+                can_inherit=True,
+            ),
+            ScopeLevel.SESSION: ScopePolicy(
+                scope_type=ScopeLevel.SESSION,
+                scope_id="default",
+                can_read=True,
+                can_write=True,
+                can_inherit=True,
+                allowed_memory_types=["working"],  # Sessions only allow working memory
+            ),
+        }
+
+    def create_scope(
+        self,
+        scope_type: ScopeLevel,
+        scope_id: str,
+        parent: ScopeContext | None = None,
+    ) -> ScopeContext:
+        """
+        Create a new scope context.
+
+        Args:
+            scope_type: Level of the scope
+            scope_id: Unique identifier within the level
+            parent: Optional parent scope
+
+        Returns:
+            Created scope context
+
+        Raises:
+            ValueError: If scope hierarchy is invalid
+        """
+        # Validate hierarchy
+        if parent is not None:
+            self._validate_parent_child(parent.scope_type, scope_type)
+
+        # For non-global scopes without parent, auto-create parent chain
+        if parent is None and scope_type != ScopeLevel.GLOBAL:
+            parent = self._create_parent_chain(scope_type, scope_id)
+
+        context = ScopeContext(
+            scope_type=scope_type,
+            scope_id=scope_id,
+            parent=parent,
+        )
+
+        logger.debug(f"Created scope: {scope_type.value}:{scope_id}")
+        return context
+
+    def _validate_parent_child(
+        self,
+        parent_type: ScopeLevel,
+        child_type: ScopeLevel,
+    ) -> None:
+        """Validate that parent-child relationship is valid."""
+        parent_idx = self.SCOPE_ORDER.index(parent_type)
+        child_idx = self.SCOPE_ORDER.index(child_type)
+
+        if child_idx <= parent_idx:
+            raise ValueError(
+                f"Invalid scope hierarchy: {child_type.value} cannot be child of {parent_type.value}"
+            )
+
+        # Allow skipping levels (e.g., PROJECT -> SESSION is valid)
+        # This enables flexible scope structures
+
+    def _create_parent_chain(
+        self,
+        target_type: ScopeLevel,
+        scope_id: str,
+    ) -> ScopeContext:
+        """Create parent scope chain up to target type."""
+        target_idx = self.SCOPE_ORDER.index(target_type)
+
+        # Start from global and build chain
+        current: ScopeContext | None = None
+
+        for i in range(target_idx):
+            level = self.SCOPE_ORDER[i]
+            if level == ScopeLevel.GLOBAL:
+                level_id = "global"
+            else:
+                # Use a default ID for intermediate levels
+                level_id = f"default_{level.value}"
+
+            current = ScopeContext(
+                scope_type=level,
+                scope_id=level_id,
+                parent=current,
+            )
+
+        return current  # type: ignore[return-value]
+
+    def create_scope_from_ids(
+        self,
+        project_id: UUID | None = None,
+        agent_type_id: UUID | None = None,
+        agent_instance_id: UUID | None = None,
+        session_id: str | None = None,
+    ) -> ScopeContext:
+        """
+        Create a scope context from individual IDs.
+
+        Automatically determines the most specific scope level
+        based on provided IDs.
+
+        Args:
+            project_id: Project UUID
+            agent_type_id: Agent type UUID
+            agent_instance_id: Agent instance UUID
+            session_id: Session identifier
+
+        Returns:
+            Scope context for the most specific level
+        """
+        # Build scope chain from most general to most specific
+        current: ScopeContext = ScopeContext(
+            scope_type=ScopeLevel.GLOBAL,
+            scope_id="global",
+            parent=None,
+        )
+
+        if project_id is not None:
+            current = ScopeContext(
+                scope_type=ScopeLevel.PROJECT,
+                scope_id=str(project_id),
+                parent=current,
+            )
+
+        if agent_type_id is not None:
+            current = ScopeContext(
+                scope_type=ScopeLevel.AGENT_TYPE,
+                scope_id=str(agent_type_id),
+                parent=current,
+            )
+
+        if agent_instance_id is not None:
+            current = ScopeContext(
+                scope_type=ScopeLevel.AGENT_INSTANCE,
+                scope_id=str(agent_instance_id),
+                parent=current,
+            )
+
+        if session_id is not None:
+            current = ScopeContext(
+                scope_type=ScopeLevel.SESSION,
+                scope_id=session_id,
+                parent=current,
+            )
+
+        return current
+
+    def get_policy(
+        self,
+        scope: ScopeContext,
+    ) -> ScopePolicy:
+        """
+        Get the access policy for a scope.
+
+        Args:
+            scope: Scope to get policy for
+
+        Returns:
+            Policy for the scope
+        """
+        key = self._scope_key(scope)
+
+        if key in self._policies:
+            return self._policies[key]
+
+        # Return default policy for the scope level
+        return self._default_policies.get(
+            scope.scope_type,
+            ScopePolicy(
+                scope_type=scope.scope_type,
+                scope_id=scope.scope_id,
+            ),
+        )
+
+    def set_policy(
+        self,
+        scope: ScopeContext,
+        policy: ScopePolicy,
+    ) -> None:
+        """
+        Set the access policy for a scope.
+
+        Args:
+            scope: Scope to set policy for
+            policy: Policy to apply
+        """
+        key = self._scope_key(scope)
+        self._policies[key] = policy
+        logger.info(f"Set policy for scope {key}")
+
+    def _scope_key(self, scope: ScopeContext) -> str:
+        """Generate a unique key for a scope."""
+        return f"{scope.scope_type.value}:{scope.scope_id}"
+
+    def get_scope_depth(self, scope_type: ScopeLevel) -> int:
+        """Get the depth of a scope level in the hierarchy."""
+        return self.SCOPE_ORDER.index(scope_type)
+
+    def get_parent_level(self, scope_type: ScopeLevel) -> ScopeLevel | None:
+        """Get the parent scope level for a given level."""
+        idx = self.SCOPE_ORDER.index(scope_type)
+        if idx == 0:
+            return None
+        return self.SCOPE_ORDER[idx - 1]
+
+    def get_child_level(self, scope_type: ScopeLevel) -> ScopeLevel | None:
+        """Get the child scope level for a given level."""
+        idx = self.SCOPE_ORDER.index(scope_type)
+        if idx >= len(self.SCOPE_ORDER) - 1:
+            return None
+        return self.SCOPE_ORDER[idx + 1]
+
+    def is_ancestor(
+        self,
+        potential_ancestor: ScopeContext,
+        descendant: ScopeContext,
+    ) -> bool:
+        """
+        Check if one scope is an ancestor of another.
+
+        Args:
+            potential_ancestor: Scope to check as ancestor
+            descendant: Scope to check as descendant
+
+        Returns:
+            True if ancestor relationship exists
+        """
+        current = descendant.parent
+        while current is not None:
+            if (
+                current.scope_type == potential_ancestor.scope_type
+                and current.scope_id == potential_ancestor.scope_id
+            ):
+                return True
+            current = current.parent
+        return False
+
+    def get_common_ancestor(
+        self,
+        scope_a: ScopeContext,
+        scope_b: ScopeContext,
+    ) -> ScopeContext | None:
+        """
+        Find the nearest common ancestor of two scopes.
+
+        Args:
+            scope_a: First scope
+            scope_b: Second scope
+
+        Returns:
+            Common ancestor or None if none exists
+        """
+        # Get ancestors of scope_a
+        ancestors_a: set[str] = set()
+        current: ScopeContext | None = scope_a
+        while current is not None:
+            ancestors_a.add(self._scope_key(current))
+            current = current.parent
+
+        # Find first ancestor of scope_b that's in ancestors_a
+        current = scope_b
+        while current is not None:
+            if self._scope_key(current) in ancestors_a:
+                return current
+            current = current.parent
+
+        return None
+
+    def can_access(
+        self,
+        accessor_scope: ScopeContext,
+        target_scope: ScopeContext,
+        operation: str = "read",
+    ) -> bool:
+        """
+        Check if accessor scope can access target scope.
+
+        Access rules:
+        - A scope can always access itself
+        - A scope can access ancestors (if inheritance allowed)
+        - A scope CANNOT access descendants (privacy)
+        - Sibling scopes cannot access each other
+
+        Args:
+            accessor_scope: Scope attempting access
+            target_scope: Scope being accessed
+            operation: Type of operation (read/write)
+
+        Returns:
+            True if access is allowed
+        """
+        # Same scope - always allowed
+        if (
+            accessor_scope.scope_type == target_scope.scope_type
+            and accessor_scope.scope_id == target_scope.scope_id
+        ):
+            policy = self.get_policy(target_scope)
+            if operation == "write":
+                return policy.allows_write()
+            return policy.allows_read()
+
+        # Check if target is ancestor (inheritance)
+        if self.is_ancestor(target_scope, accessor_scope):
+            policy = self.get_policy(target_scope)
+            if not policy.allows_inherit():
+                return False
+            if operation == "write":
+                return policy.allows_write()
+            return policy.allows_read()
+
+        # Check if accessor is ancestor of target (downward access)
+        # This is NOT allowed - parents cannot access children's memories
+        if self.is_ancestor(accessor_scope, target_scope):
+            return False
+
+        # Sibling scopes cannot access each other
+        return False
+
+
+# Singleton manager instance
+_manager: ScopeManager | None = None
+
+
+def get_scope_manager() -> ScopeManager:
+    """Get the singleton scope manager instance."""
+    global _manager
+    if _manager is None:
+        _manager = ScopeManager()
+    return _manager

backend/app/services/memory/semantic/__init__.py

@@ -0,0 +1,27 @@
+# app/services/memory/semantic/__init__.py
+"""
+Semantic Memory
+
+Fact storage with triple format (subject, predicate, object)
+and semantic search capabilities.
+"""
+
+from .extraction import (
+    ExtractedFact,
+    ExtractionContext,
+    FactExtractor,
+    get_fact_extractor,
+)
+from .memory import SemanticMemory
+from .verification import FactConflict, FactVerifier, VerificationResult
+
+__all__ = [
+    "ExtractedFact",
+    "ExtractionContext",
+    "FactConflict",
+    "FactExtractor",
+    "FactVerifier",
+    "SemanticMemory",
+    "VerificationResult",
+    "get_fact_extractor",
+]

backend/app/services/memory/semantic/extraction.py

@@ -0,0 +1,313 @@
+# app/services/memory/semantic/extraction.py
+"""
+Fact Extraction from Episodes.
+
+Provides utilities for extracting semantic facts (subject-predicate-object triples)
+from episodic memories and other text sources.
+"""
+
+import logging
+import re
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+
+from app.services.memory.types import Episode, FactCreate, Outcome
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ExtractionContext:
+    """Context for fact extraction."""
+
+    project_id: Any | None = None
+    source_episode_id: Any | None = None
+    min_confidence: float = 0.5
+    max_facts_per_source: int = 10
+
+
+@dataclass
+class ExtractedFact:
+    """A fact extracted from text before storage."""
+
+    subject: str
+    predicate: str
+    object: str
+    confidence: float
+    source_text: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_fact_create(
+        self,
+        project_id: Any | None = None,
+        source_episode_ids: list[Any] | None = None,
+    ) -> FactCreate:
+        """Convert to FactCreate for storage."""
+        return FactCreate(
+            subject=self.subject,
+            predicate=self.predicate,
+            object=self.object,
+            confidence=self.confidence,
+            project_id=project_id,
+            source_episode_ids=source_episode_ids or [],
+        )
+
+
+class FactExtractor:
+    """
+    Extracts facts from episodes and text.
+
+    This is a rule-based extractor. In production, this would be
+    replaced or augmented with LLM-based extraction for better accuracy.
+    """
+
+    # Common predicates we can detect
+    PREDICATE_PATTERNS: ClassVar[dict[str, str]] = {
+        "uses": r"(?:uses?|using|utilizes?)",
+        "requires": r"(?:requires?|needs?|depends?\s+on)",
+        "is_a": r"(?:is\s+a|is\s+an|are\s+a|are)",
+        "has": r"(?:has|have|contains?)",
+        "part_of": r"(?:part\s+of|belongs?\s+to|member\s+of)",
+        "causes": r"(?:causes?|leads?\s+to|results?\s+in)",
+        "prevents": r"(?:prevents?|avoids?|stops?)",
+        "solves": r"(?:solves?|fixes?|resolves?)",
+    }
+
+    def __init__(self) -> None:
+        """Initialize extractor."""
+        self._compiled_patterns = {
+            pred: re.compile(pattern, re.IGNORECASE)
+            for pred, pattern in self.PREDICATE_PATTERNS.items()
+        }
+
+    def extract_from_episode(
+        self,
+        episode: Episode,
+        context: ExtractionContext | None = None,
+    ) -> list[ExtractedFact]:
+        """
+        Extract facts from an episode.
+
+        Args:
+            episode: Episode to extract from
+            context: Optional extraction context
+
+        Returns:
+            List of extracted facts
+        """
+        ctx = context or ExtractionContext()
+        facts: list[ExtractedFact] = []
+
+        # Extract from task description
+        task_facts = self._extract_from_text(
+            episode.task_description,
+            source_prefix=episode.task_type,
+        )
+        facts.extend(task_facts)
+
+        # Extract from lessons learned
+        for lesson in episode.lessons_learned:
+            lesson_facts = self._extract_from_lesson(lesson, episode)
+            facts.extend(lesson_facts)
+
+        # Extract outcome-based facts
+        outcome_facts = self._extract_outcome_facts(episode)
+        facts.extend(outcome_facts)
+
+        # Limit and filter
+        facts = [f for f in facts if f.confidence >= ctx.min_confidence]
+        facts = facts[: ctx.max_facts_per_source]
+
+        logger.debug(f"Extracted {len(facts)} facts from episode {episode.id}")
+
+        return facts
+
+    def _extract_from_text(
+        self,
+        text: str,
+        source_prefix: str = "",
+    ) -> list[ExtractedFact]:
+        """Extract facts from free-form text using pattern matching."""
+        facts: list[ExtractedFact] = []
+
+        if not text or len(text) < 10:
+            return facts
+
+        # Split into sentences
+        sentences = re.split(r"[.!?]+", text)
+
+        for sentence in sentences:
+            sentence = sentence.strip()
+            if len(sentence) < 10:
+                continue
+
+            # Try to match predicate patterns
+            for predicate, pattern in self._compiled_patterns.items():
+                match = pattern.search(sentence)
+                if match:
+                    # Extract subject (text before predicate)
+                    subject = sentence[: match.start()].strip()
+                    # Extract object (text after predicate)
+                    obj = sentence[match.end() :].strip()
+
+                    if len(subject) > 2 and len(obj) > 2:
+                        facts.append(
+                            ExtractedFact(
+                                subject=subject[:200],  # Limit length
+                                predicate=predicate,
+                                object=obj[:500],
+                                confidence=0.6,  # Medium confidence for pattern matching
+                                source_text=sentence,
+                            )
+                        )
+                        break  # One fact per sentence
+
+        return facts
+
+    def _extract_from_lesson(
+        self,
+        lesson: str,
+        episode: Episode,
+    ) -> list[ExtractedFact]:
+        """Extract facts from a lesson learned."""
+        facts: list[ExtractedFact] = []
+
+        if not lesson or len(lesson) < 10:
+            return facts
+
+        # Lessons are typically in the form "Always do X" or "Never do Y"
+        # or "When X, do Y"
+
+        # Direct lesson fact
+        facts.append(
+            ExtractedFact(
+                subject=episode.task_type,
+                predicate="lesson_learned",
+                object=lesson,
+                confidence=0.8,  # High confidence for explicit lessons
+                source_text=lesson,
+                metadata={"outcome": episode.outcome.value},
+            )
+        )
+
+        # Extract conditional patterns
+        conditional_match = re.match(
+            r"(?:when|if)\s+(.+?),\s*(.+)",
+            lesson,
+            re.IGNORECASE,
+        )
+        if conditional_match:
+            condition, action = conditional_match.groups()
+            facts.append(
+                ExtractedFact(
+                    subject=condition.strip(),
+                    predicate="requires_action",
+                    object=action.strip(),
+                    confidence=0.7,
+                    source_text=lesson,
+                )
+            )
+
+        # Extract "always/never" patterns
+        always_match = re.match(
+            r"(?:always)\s+(.+)",
+            lesson,
+            re.IGNORECASE,
+        )
+        if always_match:
+            facts.append(
+                ExtractedFact(
+                    subject=episode.task_type,
+                    predicate="best_practice",
+                    object=always_match.group(1).strip(),
+                    confidence=0.85,
+                    source_text=lesson,
+                )
+            )
+
+        never_match = re.match(
+            r"(?:never|avoid)\s+(.+)",
+            lesson,
+            re.IGNORECASE,
+        )
+        if never_match:
+            facts.append(
+                ExtractedFact(
+                    subject=episode.task_type,
+                    predicate="anti_pattern",
+                    object=never_match.group(1).strip(),
+                    confidence=0.85,
+                    source_text=lesson,
+                )
+            )
+
+        return facts
+
+    def _extract_outcome_facts(
+        self,
+        episode: Episode,
+    ) -> list[ExtractedFact]:
+        """Extract facts based on episode outcome."""
+        facts: list[ExtractedFact] = []
+
+        # Create fact based on outcome
+        if episode.outcome == Outcome.SUCCESS:
+            if episode.outcome_details:
+                facts.append(
+                    ExtractedFact(
+                        subject=episode.task_type,
+                        predicate="successful_approach",
+                        object=episode.outcome_details[:500],
+                        confidence=0.75,
+                        source_text=episode.outcome_details,
+                    )
+                )
+        elif episode.outcome == Outcome.FAILURE:
+            if episode.outcome_details:
+                facts.append(
+                    ExtractedFact(
+                        subject=episode.task_type,
+                        predicate="known_failure_mode",
+                        object=episode.outcome_details[:500],
+                        confidence=0.8,  # High confidence for failures
+                        source_text=episode.outcome_details,
+                    )
+                )
+
+        return facts
+
+    def extract_from_text(
+        self,
+        text: str,
+        context: ExtractionContext | None = None,
+    ) -> list[ExtractedFact]:
+        """
+        Extract facts from arbitrary text.
+
+        Args:
+            text: Text to extract from
+            context: Optional extraction context
+
+        Returns:
+            List of extracted facts
+        """
+        ctx = context or ExtractionContext()
+
+        facts = self._extract_from_text(text)
+
+        # Filter by confidence
+        facts = [f for f in facts if f.confidence >= ctx.min_confidence]
+
+        return facts[: ctx.max_facts_per_source]
+
+
+# Singleton extractor instance
+_extractor: FactExtractor | None = None
+
+
+def get_fact_extractor() -> FactExtractor:
+    """Get the singleton fact extractor instance."""
+    global _extractor
+    if _extractor is None:
+        _extractor = FactExtractor()
+    return _extractor

backend/app/services/memory/semantic/memory.py

@@ -0,0 +1,742 @@
+# app/services/memory/semantic/memory.py
+"""
+Semantic Memory Implementation.
+
+Provides fact storage and retrieval using subject-predicate-object triples.
+Supports semantic search, confidence scoring, and fact reinforcement.
+"""
+
+import logging
+import time
+from datetime import UTC, datetime
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import and_, desc, or_, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.memory.fact import Fact as FactModel
+from app.services.memory.config import get_memory_settings
+from app.services.memory.types import Episode, Fact, FactCreate, RetrievalResult
+
+logger = logging.getLogger(__name__)
+
+
+def _model_to_fact(model: FactModel) -> Fact:
+    """Convert SQLAlchemy model to Fact dataclass."""
+    # SQLAlchemy Column types are inferred as Column[T] by mypy, but at runtime
+    # they return actual values. We use type: ignore to handle this mismatch.
+    return Fact(
+        id=model.id,  # type: ignore[arg-type]
+        project_id=model.project_id,  # type: ignore[arg-type]
+        subject=model.subject,  # type: ignore[arg-type]
+        predicate=model.predicate,  # type: ignore[arg-type]
+        object=model.object,  # type: ignore[arg-type]
+        confidence=model.confidence,  # type: ignore[arg-type]
+        source_episode_ids=model.source_episode_ids or [],  # type: ignore[arg-type]
+        first_learned=model.first_learned,  # type: ignore[arg-type]
+        last_reinforced=model.last_reinforced,  # type: ignore[arg-type]
+        reinforcement_count=model.reinforcement_count,  # type: ignore[arg-type]
+        embedding=None,  # Don't expose raw embedding
+        created_at=model.created_at,  # type: ignore[arg-type]
+        updated_at=model.updated_at,  # type: ignore[arg-type]
+    )
+
+
+class SemanticMemory:
+    """
+    Semantic Memory Service.
+
+    Provides fact storage and retrieval:
+    - Store facts as subject-predicate-object triples
+    - Semantic search over facts
+    - Entity-based retrieval
+    - Confidence scoring and decay
+    - Fact reinforcement on repeated learning
+    - Conflict resolution
+
+    Performance target: <100ms P95 for retrieval
+    """
+
+    def __init__(
+        self,
+        session: AsyncSession,
+        embedding_generator: Any | None = None,
+    ) -> None:
+        """
+        Initialize semantic memory.
+
+        Args:
+            session: Database session
+            embedding_generator: Optional embedding generator for semantic search
+        """
+        self._session = session
+        self._embedding_generator = embedding_generator
+        self._settings = get_memory_settings()
+
+    @classmethod
+    async def create(
+        cls,
+        session: AsyncSession,
+        embedding_generator: Any | None = None,
+    ) -> "SemanticMemory":
+        """
+        Factory method to create SemanticMemory.
+
+        Args:
+            session: Database session
+            embedding_generator: Optional embedding generator
+
+        Returns:
+            Configured SemanticMemory instance
+        """
+        return cls(session=session, embedding_generator=embedding_generator)
+
+    # =========================================================================
+    # Fact Storage
+    # =========================================================================
+
+    async def store_fact(self, fact: FactCreate) -> Fact:
+        """
+        Store a new fact or reinforce an existing one.
+
+        If a fact with the same triple (subject, predicate, object) exists
+        in the same scope, it will be reinforced instead of duplicated.
+
+        Args:
+            fact: Fact data to store
+
+        Returns:
+            The created or reinforced fact
+        """
+        # Check for existing fact with same triple
+        existing = await self._find_existing_fact(
+            project_id=fact.project_id,
+            subject=fact.subject,
+            predicate=fact.predicate,
+            object=fact.object,
+        )
+
+        if existing is not None:
+            # Reinforce existing fact
+            return await self.reinforce_fact(
+                existing.id,  # type: ignore[arg-type]
+                source_episode_ids=fact.source_episode_ids,
+            )
+
+        # Create new fact
+        now = datetime.now(UTC)
+
+        # Generate embedding if possible
+        embedding = None
+        if self._embedding_generator is not None:
+            embedding_text = self._create_embedding_text(fact)
+            embedding = await self._embedding_generator.generate(embedding_text)
+
+        model = FactModel(
+            project_id=fact.project_id,
+            subject=fact.subject,
+            predicate=fact.predicate,
+            object=fact.object,
+            confidence=fact.confidence,
+            source_episode_ids=fact.source_episode_ids,
+            first_learned=now,
+            last_reinforced=now,
+            reinforcement_count=1,
+            embedding=embedding,
+        )
+
+        self._session.add(model)
+        await self._session.flush()
+        await self._session.refresh(model)
+
+        logger.info(
+            f"Stored new fact: {fact.subject} - {fact.predicate} - {fact.object[:50]}..."
+        )
+
+        return _model_to_fact(model)
+
+    async def _find_existing_fact(
+        self,
+        project_id: UUID | None,
+        subject: str,
+        predicate: str,
+        object: str,
+    ) -> FactModel | None:
+        """Find an existing fact with the same triple in the same scope."""
+        query = select(FactModel).where(
+            and_(
+                FactModel.subject == subject,
+                FactModel.predicate == predicate,
+                FactModel.object == object,
+            )
+        )
+
+        if project_id is not None:
+            query = query.where(FactModel.project_id == project_id)
+        else:
+            query = query.where(FactModel.project_id.is_(None))
+
+        result = await self._session.execute(query)
+        return result.scalar_one_or_none()
+
+    def _create_embedding_text(self, fact: FactCreate) -> str:
+        """Create text for embedding from fact data."""
+        return f"{fact.subject} {fact.predicate} {fact.object}"
+
+    # =========================================================================
+    # Fact Retrieval
+    # =========================================================================
+
+    async def search_facts(
+        self,
+        query: str,
+        project_id: UUID | None = None,
+        limit: int = 10,
+        min_confidence: float | None = None,
+    ) -> list[Fact]:
+        """
+        Search for facts semantically similar to the query.
+
+        Args:
+            query: Search query
+            project_id: Optional project to search within
+            limit: Maximum results
+            min_confidence: Optional minimum confidence filter
+
+        Returns:
+            List of matching facts
+        """
+        result = await self._search_facts_with_metadata(
+            query=query,
+            project_id=project_id,
+            limit=limit,
+            min_confidence=min_confidence,
+        )
+        return result.items
+
+    async def _search_facts_with_metadata(
+        self,
+        query: str,
+        project_id: UUID | None = None,
+        limit: int = 10,
+        min_confidence: float | None = None,
+    ) -> RetrievalResult[Fact]:
+        """Search facts with full result metadata."""
+        start_time = time.perf_counter()
+
+        min_conf = min_confidence or self._settings.semantic_min_confidence
+
+        # Build base query
+        stmt = (
+            select(FactModel)
+            .where(FactModel.confidence >= min_conf)
+            .order_by(desc(FactModel.confidence), desc(FactModel.last_reinforced))
+            .limit(limit)
+        )
+
+        # Apply project filter
+        if project_id is not None:
+            # Include both project-specific and global facts
+            stmt = stmt.where(
+                or_(
+                    FactModel.project_id == project_id,
+                    FactModel.project_id.is_(None),
+                )
+            )
+
+        # TODO: Implement proper vector similarity search when pgvector is integrated
+        # For now, do text-based search on subject/predicate/object
+        search_terms = query.lower().split()
+        if search_terms:
+            conditions = []
+            for term in search_terms[:5]:  # Limit to 5 terms
+                term_pattern = f"%{term}%"
+                conditions.append(
+                    or_(
+                        FactModel.subject.ilike(term_pattern),
+                        FactModel.predicate.ilike(term_pattern),
+                        FactModel.object.ilike(term_pattern),
+                    )
+                )
+            if conditions:
+                stmt = stmt.where(or_(*conditions))
+
+        result = await self._session.execute(stmt)
+        models = list(result.scalars().all())
+
+        latency_ms = (time.perf_counter() - start_time) * 1000
+
+        return RetrievalResult(
+            items=[_model_to_fact(m) for m in models],
+            total_count=len(models),
+            query=query,
+            retrieval_type="semantic",
+            latency_ms=latency_ms,
+            metadata={"min_confidence": min_conf},
+        )
+
+    async def get_by_entity(
+        self,
+        entity: str,
+        project_id: UUID | None = None,
+        limit: int = 20,
+    ) -> list[Fact]:
+        """
+        Get facts related to an entity (as subject or object).
+
+        Args:
+            entity: Entity to search for
+            project_id: Optional project to search within
+            limit: Maximum results
+
+        Returns:
+            List of facts mentioning the entity
+        """
+        start_time = time.perf_counter()
+
+        stmt = (
+            select(FactModel)
+            .where(
+                or_(
+                    FactModel.subject.ilike(f"%{entity}%"),
+                    FactModel.object.ilike(f"%{entity}%"),
+                )
+            )
+            .order_by(desc(FactModel.confidence), desc(FactModel.last_reinforced))
+            .limit(limit)
+        )
+
+        if project_id is not None:
+            stmt = stmt.where(
+                or_(
+                    FactModel.project_id == project_id,
+                    FactModel.project_id.is_(None),
+                )
+            )
+
+        result = await self._session.execute(stmt)
+        models = list(result.scalars().all())
+
+        latency_ms = (time.perf_counter() - start_time) * 1000
+        logger.debug(
+            f"get_by_entity({entity}) returned {len(models)} facts in {latency_ms:.1f}ms"
+        )
+
+        return [_model_to_fact(m) for m in models]
+
+    async def get_by_subject(
+        self,
+        subject: str,
+        project_id: UUID | None = None,
+        predicate: str | None = None,
+        limit: int = 20,
+    ) -> list[Fact]:
+        """
+        Get facts with a specific subject.
+
+        Args:
+            subject: Subject to search for
+            project_id: Optional project to search within
+            predicate: Optional predicate filter
+            limit: Maximum results
+
+        Returns:
+            List of facts with matching subject
+        """
+        stmt = (
+            select(FactModel)
+            .where(FactModel.subject == subject)
+            .order_by(desc(FactModel.confidence))
+            .limit(limit)
+        )
+
+        if predicate is not None:
+            stmt = stmt.where(FactModel.predicate == predicate)
+
+        if project_id is not None:
+            stmt = stmt.where(
+                or_(
+                    FactModel.project_id == project_id,
+                    FactModel.project_id.is_(None),
+                )
+            )
+
+        result = await self._session.execute(stmt)
+        models = list(result.scalars().all())
+
+        return [_model_to_fact(m) for m in models]
+
+    async def get_by_id(self, fact_id: UUID) -> Fact | None:
+        """Get a fact by ID."""
+        query = select(FactModel).where(FactModel.id == fact_id)
+        result = await self._session.execute(query)
+        model = result.scalar_one_or_none()
+        return _model_to_fact(model) if model else None
+
+    # =========================================================================
+    # Fact Reinforcement
+    # =========================================================================
+
+    async def reinforce_fact(
+        self,
+        fact_id: UUID,
+        confidence_boost: float = 0.1,
+        source_episode_ids: list[UUID] | None = None,
+    ) -> Fact:
+        """
+        Reinforce a fact, increasing its confidence.
+
+        Args:
+            fact_id: Fact to reinforce
+            confidence_boost: Amount to increase confidence (default 0.1)
+            source_episode_ids: Additional source episodes
+
+        Returns:
+            Updated fact
+
+        Raises:
+            ValueError: If fact not found
+        """
+        query = select(FactModel).where(FactModel.id == fact_id)
+        result = await self._session.execute(query)
+        model = result.scalar_one_or_none()
+
+        if model is None:
+            raise ValueError(f"Fact not found: {fact_id}")
+
+        # Calculate new confidence (max 1.0)
+        current_confidence: float = model.confidence  # type: ignore[assignment]
+        new_confidence = min(1.0, current_confidence + confidence_boost)
+
+        # Merge source episode IDs
+        current_sources: list[UUID] = model.source_episode_ids or []  # type: ignore[assignment]
+        if source_episode_ids:
+            # Add new sources, avoiding duplicates
+            new_sources = list(set(current_sources + source_episode_ids))
+        else:
+            new_sources = current_sources
+
+        now = datetime.now(UTC)
+        stmt = (
+            update(FactModel)
+            .where(FactModel.id == fact_id)
+            .values(
+                confidence=new_confidence,
+                source_episode_ids=new_sources,
+                last_reinforced=now,
+                reinforcement_count=FactModel.reinforcement_count + 1,
+                updated_at=now,
+            )
+            .returning(FactModel)
+        )
+
+        result = await self._session.execute(stmt)
+        updated_model = result.scalar_one()
+        await self._session.flush()
+
+        logger.info(
+            f"Reinforced fact {fact_id}: confidence {current_confidence:.2f} -> {new_confidence:.2f}"
+        )
+
+        return _model_to_fact(updated_model)
+
+    async def deprecate_fact(
+        self,
+        fact_id: UUID,
+        reason: str,
+        new_confidence: float = 0.0,
+    ) -> Fact | None:
+        """
+        Deprecate a fact by lowering its confidence.
+
+        Args:
+            fact_id: Fact to deprecate
+            reason: Reason for deprecation
+            new_confidence: New confidence level (default 0.0)
+
+        Returns:
+            Updated fact or None if not found
+        """
+        query = select(FactModel).where(FactModel.id == fact_id)
+        result = await self._session.execute(query)
+        model = result.scalar_one_or_none()
+
+        if model is None:
+            return None
+
+        now = datetime.now(UTC)
+        stmt = (
+            update(FactModel)
+            .where(FactModel.id == fact_id)
+            .values(
+                confidence=max(0.0, new_confidence),
+                updated_at=now,
+            )
+            .returning(FactModel)
+        )
+
+        result = await self._session.execute(stmt)
+        updated_model = result.scalar_one_or_none()
+        await self._session.flush()
+
+        logger.info(f"Deprecated fact {fact_id}: {reason}")
+
+        return _model_to_fact(updated_model) if updated_model else None
+
+    # =========================================================================
+    # Fact Extraction from Episodes
+    # =========================================================================
+
+    async def extract_facts_from_episode(
+        self,
+        episode: Episode,
+    ) -> list[Fact]:
+        """
+        Extract facts from an episode.
+
+        This is a placeholder for LLM-based fact extraction.
+        In production, this would call an LLM to analyze the episode
+        and extract subject-predicate-object triples.
+
+        Args:
+            episode: Episode to extract facts from
+
+        Returns:
+            List of extracted facts
+        """
+        # For now, extract basic facts from lessons learned
+        extracted_facts: list[Fact] = []
+
+        for lesson in episode.lessons_learned:
+            if len(lesson) > 10:  # Skip very short lessons
+                fact_create = FactCreate(
+                    subject=episode.task_type,
+                    predicate="lesson_learned",
+                    object=lesson,
+                    confidence=0.7,  # Lessons start with moderate confidence
+                    project_id=episode.project_id,
+                    source_episode_ids=[episode.id],
+                )
+                fact = await self.store_fact(fact_create)
+                extracted_facts.append(fact)
+
+        logger.debug(
+            f"Extracted {len(extracted_facts)} facts from episode {episode.id}"
+        )
+
+        return extracted_facts
+
+    # =========================================================================
+    # Conflict Resolution
+    # =========================================================================
+
+    async def resolve_conflict(
+        self,
+        fact_ids: list[UUID],
+        keep_fact_id: UUID | None = None,
+    ) -> Fact | None:
+        """
+        Resolve a conflict between multiple facts.
+
+        If keep_fact_id is specified, that fact is kept and others are deprecated.
+        Otherwise, the fact with highest confidence is kept.
+
+        Args:
+            fact_ids: IDs of conflicting facts
+            keep_fact_id: Optional ID of fact to keep
+
+        Returns:
+            The winning fact, or None if no facts found
+        """
+        if not fact_ids:
+            return None
+
+        # Load all facts
+        query = select(FactModel).where(FactModel.id.in_(fact_ids))
+        result = await self._session.execute(query)
+        models = list(result.scalars().all())
+
+        if not models:
+            return None
+
+        # Determine winner
+        if keep_fact_id is not None:
+            winner = next((m for m in models if m.id == keep_fact_id), None)
+            if winner is None:
+                # Fallback to highest confidence
+                winner = max(models, key=lambda m: m.confidence)
+        else:
+            # Keep the fact with highest confidence
+            winner = max(models, key=lambda m: m.confidence)
+
+        # Deprecate losers
+        for model in models:
+            if model.id != winner.id:
+                await self.deprecate_fact(
+                    model.id,  # type: ignore[arg-type]
+                    reason=f"Conflict resolution: superseded by {winner.id}",
+                )
+
+        logger.info(
+            f"Resolved conflict between {len(fact_ids)} facts, keeping {winner.id}"
+        )
+
+        return _model_to_fact(winner)
+
+    # =========================================================================
+    # Confidence Decay
+    # =========================================================================
+
+    async def apply_confidence_decay(
+        self,
+        project_id: UUID | None = None,
+        decay_factor: float = 0.01,
+    ) -> int:
+        """
+        Apply confidence decay to facts that haven't been reinforced recently.
+
+        Args:
+            project_id: Optional project to apply decay to
+            decay_factor: Decay factor per day (default 0.01)
+
+        Returns:
+            Number of facts affected
+        """
+        now = datetime.now(UTC)
+        decay_days = self._settings.semantic_confidence_decay_days
+        min_conf = self._settings.semantic_min_confidence
+
+        # Calculate cutoff date
+        from datetime import timedelta
+
+        cutoff = now - timedelta(days=decay_days)
+
+        # Find facts needing decay
+        query = select(FactModel).where(
+            and_(
+                FactModel.last_reinforced < cutoff,
+                FactModel.confidence > min_conf,
+            )
+        )
+
+        if project_id is not None:
+            query = query.where(FactModel.project_id == project_id)
+
+        result = await self._session.execute(query)
+        models = list(result.scalars().all())
+
+        # Apply decay
+        updated_count = 0
+        for model in models:
+            # Calculate days since last reinforcement
+            days_since: float = (now - model.last_reinforced).days
+
+            # Calculate decay: exponential decay based on days
+            decay = decay_factor * (days_since - decay_days)
+            new_confidence = max(min_conf, model.confidence - decay)
+
+            if new_confidence != model.confidence:
+                await self._session.execute(
+                    update(FactModel)
+                    .where(FactModel.id == model.id)
+                    .values(confidence=new_confidence, updated_at=now)
+                )
+                updated_count += 1
+
+        await self._session.flush()
+        logger.info(f"Applied confidence decay to {updated_count} facts")
+
+        return updated_count
+
+    # =========================================================================
+    # Statistics
+    # =========================================================================
+
+    async def get_stats(self, project_id: UUID | None = None) -> dict[str, Any]:
+        """
+        Get statistics about semantic memory.
+
+        Args:
+            project_id: Optional project to get stats for
+
+        Returns:
+            Dictionary with statistics
+        """
+        # Get all facts for this scope
+        query = select(FactModel)
+        if project_id is not None:
+            query = query.where(
+                or_(
+                    FactModel.project_id == project_id,
+                    FactModel.project_id.is_(None),
+                )
+            )
+
+        result = await self._session.execute(query)
+        models = list(result.scalars().all())
+
+        if not models:
+            return {
+                "total_facts": 0,
+                "avg_confidence": 0.0,
+                "avg_reinforcement_count": 0.0,
+                "high_confidence_count": 0,
+                "low_confidence_count": 0,
+            }
+
+        confidences = [m.confidence for m in models]
+        reinforcements = [m.reinforcement_count for m in models]
+
+        return {
+            "total_facts": len(models),
+            "avg_confidence": sum(confidences) / len(confidences),
+            "avg_reinforcement_count": sum(reinforcements) / len(reinforcements),
+            "high_confidence_count": sum(1 for c in confidences if c >= 0.8),
+            "low_confidence_count": sum(1 for c in confidences if c < 0.5),
+        }
+
+    async def count(self, project_id: UUID | None = None) -> int:
+        """
+        Count facts in scope.
+
+        Args:
+            project_id: Optional project to count for
+
+        Returns:
+            Number of facts
+        """
+        query = select(FactModel)
+        if project_id is not None:
+            query = query.where(
+                or_(
+                    FactModel.project_id == project_id,
+                    FactModel.project_id.is_(None),
+                )
+            )
+
+        result = await self._session.execute(query)
+        return len(list(result.scalars().all()))
+
+    async def delete(self, fact_id: UUID) -> bool:
+        """
+        Delete a fact.
+
+        Args:
+            fact_id: Fact to delete
+
+        Returns:
+            True if deleted, False if not found
+        """
+        query = select(FactModel).where(FactModel.id == fact_id)
+        result = await self._session.execute(query)
+        model = result.scalar_one_or_none()
+
+        if model is None:
+            return False
+
+        await self._session.delete(model)
+        await self._session.flush()
+
+        logger.info(f"Deleted fact {fact_id}")
+        return True

backend/app/services/memory/semantic/verification.py

@@ -0,0 +1,363 @@
+# app/services/memory/semantic/verification.py
+"""
+Fact Verification.
+
+Provides utilities for verifying facts, detecting conflicts,
+and managing fact consistency.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+from uuid import UUID
+
+from sqlalchemy import and_, or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.memory.fact import Fact as FactModel
+from app.services.memory.types import Fact
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class VerificationResult:
+    """Result of fact verification."""
+
+    is_valid: bool
+    confidence_adjustment: float = 0.0
+    conflicts: list["FactConflict"] = field(default_factory=list)
+    supporting_facts: list[Fact] = field(default_factory=list)
+    messages: list[str] = field(default_factory=list)
+
+
+@dataclass
+class FactConflict:
+    """Represents a conflict between two facts."""
+
+    fact_a_id: UUID
+    fact_b_id: UUID
+    conflict_type: str  # "contradiction", "superseded", "partial_overlap"
+    description: str
+    suggested_resolution: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "fact_a_id": str(self.fact_a_id),
+            "fact_b_id": str(self.fact_b_id),
+            "conflict_type": self.conflict_type,
+            "description": self.description,
+            "suggested_resolution": self.suggested_resolution,
+        }
+
+
+class FactVerifier:
+    """
+    Verifies facts and detects conflicts.
+
+    Provides methods to:
+    - Check if a fact conflicts with existing facts
+    - Find supporting evidence for a fact
+    - Detect contradictions in the fact base
+    """
+
+    # Predicates that are opposites/contradictions
+    CONTRADICTORY_PREDICATES: ClassVar[set[tuple[str, str]]] = {
+        ("uses", "does_not_use"),
+        ("requires", "does_not_require"),
+        ("is_a", "is_not_a"),
+        ("causes", "prevents"),
+        ("allows", "prevents"),
+        ("supports", "does_not_support"),
+        ("best_practice", "anti_pattern"),
+    }
+
+    def __init__(self, session: AsyncSession) -> None:
+        """Initialize verifier with database session."""
+        self._session = session
+
+    async def verify_fact(
+        self,
+        subject: str,
+        predicate: str,
+        obj: str,
+        project_id: UUID | None = None,
+    ) -> VerificationResult:
+        """
+        Verify a fact against existing facts.
+
+        Args:
+            subject: Fact subject
+            predicate: Fact predicate
+            obj: Fact object
+            project_id: Optional project scope
+
+        Returns:
+            VerificationResult with verification details
+        """
+        result = VerificationResult(is_valid=True)
+
+        # Check for direct contradictions
+        conflicts = await self._find_contradictions(
+            subject=subject,
+            predicate=predicate,
+            obj=obj,
+            project_id=project_id,
+        )
+        result.conflicts = conflicts
+
+        if conflicts:
+            result.is_valid = False
+            result.messages.append(f"Found {len(conflicts)} conflicting fact(s)")
+            # Reduce confidence based on conflicts
+            result.confidence_adjustment = -0.1 * len(conflicts)
+
+        # Find supporting facts
+        supporting = await self._find_supporting_facts(
+            subject=subject,
+            predicate=predicate,
+            project_id=project_id,
+        )
+        result.supporting_facts = supporting
+
+        if supporting:
+            result.messages.append(f"Found {len(supporting)} supporting fact(s)")
+            # Boost confidence based on support
+            result.confidence_adjustment += 0.05 * min(len(supporting), 3)
+
+        return result
+
+    async def _find_contradictions(
+        self,
+        subject: str,
+        predicate: str,
+        obj: str,
+        project_id: UUID | None = None,
+    ) -> list[FactConflict]:
+        """Find facts that contradict the given fact."""
+        conflicts: list[FactConflict] = []
+
+        # Find opposite predicates
+        opposite_predicates = self._get_opposite_predicates(predicate)
+
+        if not opposite_predicates:
+            return conflicts
+
+        # Search for contradicting facts
+        query = select(FactModel).where(
+            and_(
+                FactModel.subject == subject,
+                FactModel.predicate.in_(opposite_predicates),
+            )
+        )
+
+        if project_id is not None:
+            query = query.where(
+                or_(
+                    FactModel.project_id == project_id,
+                    FactModel.project_id.is_(None),
+                )
+            )
+
+        result = await self._session.execute(query)
+        models = list(result.scalars().all())
+
+        for model in models:
+            conflicts.append(
+                FactConflict(
+                    fact_a_id=model.id,  # type: ignore[arg-type]
+                    fact_b_id=UUID(
+                        "00000000-0000-0000-0000-000000000000"
+                    ),  # Placeholder for new fact
+                    conflict_type="contradiction",
+                    description=(
+                        f"'{subject} {predicate} {obj}' contradicts "
+                        f"'{model.subject} {model.predicate} {model.object}'"
+                    ),
+                    suggested_resolution="Keep fact with higher confidence",
+                )
+            )
+
+        return conflicts
+
+    def _get_opposite_predicates(self, predicate: str) -> list[str]:
+        """Get predicates that are opposite to the given predicate."""
+        opposites: list[str] = []
+
+        for pair in self.CONTRADICTORY_PREDICATES:
+            if predicate in pair:
+                opposites.extend(p for p in pair if p != predicate)
+
+        return opposites
+
+    async def _find_supporting_facts(
+        self,
+        subject: str,
+        predicate: str,
+        project_id: UUID | None = None,
+    ) -> list[Fact]:
+        """Find facts that support the given fact."""
+        # Find facts with same subject and predicate
+        query = (
+            select(FactModel)
+            .where(
+                and_(
+                    FactModel.subject == subject,
+                    FactModel.predicate == predicate,
+                    FactModel.confidence >= 0.5,
+                )
+            )
+            .limit(10)
+        )
+
+        if project_id is not None:
+            query = query.where(
+                or_(
+                    FactModel.project_id == project_id,
+                    FactModel.project_id.is_(None),
+                )
+            )
+
+        result = await self._session.execute(query)
+        models = list(result.scalars().all())
+
+        return [self._model_to_fact(m) for m in models]
+
+    async def find_all_conflicts(
+        self,
+        project_id: UUID | None = None,
+    ) -> list[FactConflict]:
+        """
+        Find all conflicts in the fact base.
+
+        Args:
+            project_id: Optional project scope
+
+        Returns:
+            List of all detected conflicts
+        """
+        conflicts: list[FactConflict] = []
+
+        # Get all facts
+        query = select(FactModel)
+        if project_id is not None:
+            query = query.where(
+                or_(
+                    FactModel.project_id == project_id,
+                    FactModel.project_id.is_(None),
+                )
+            )
+
+        result = await self._session.execute(query)
+        models = list(result.scalars().all())
+
+        # Check each pair for conflicts
+        for i, fact_a in enumerate(models):
+            for fact_b in models[i + 1 :]:
+                conflict = self._check_pair_conflict(fact_a, fact_b)
+                if conflict:
+                    conflicts.append(conflict)
+
+        logger.info(f"Found {len(conflicts)} conflicts in fact base")
+
+        return conflicts
+
+    def _check_pair_conflict(
+        self,
+        fact_a: FactModel,
+        fact_b: FactModel,
+    ) -> FactConflict | None:
+        """Check if two facts conflict."""
+        # Same subject?
+        if fact_a.subject != fact_b.subject:
+            return None
+
+        # Contradictory predicates?
+        opposite = self._get_opposite_predicates(fact_a.predicate)  # type: ignore[arg-type]
+        if fact_b.predicate not in opposite:
+            return None
+
+        return FactConflict(
+            fact_a_id=fact_a.id,  # type: ignore[arg-type]
+            fact_b_id=fact_b.id,  # type: ignore[arg-type]
+            conflict_type="contradiction",
+            description=(
+                f"'{fact_a.subject} {fact_a.predicate} {fact_a.object}' "
+                f"contradicts '{fact_b.subject} {fact_b.predicate} {fact_b.object}'"
+            ),
+            suggested_resolution="Deprecate fact with lower confidence",
+        )
+
+    async def get_fact_reliability_score(
+        self,
+        fact_id: UUID,
+    ) -> float:
+        """
+        Calculate a reliability score for a fact.
+
+        Based on:
+        - Confidence score
+        - Number of reinforcements
+        - Number of supporting facts
+        - Absence of conflicts
+
+        Args:
+            fact_id: Fact to score
+
+        Returns:
+            Reliability score (0.0 to 1.0)
+        """
+        query = select(FactModel).where(FactModel.id == fact_id)
+        result = await self._session.execute(query)
+        model = result.scalar_one_or_none()
+
+        if model is None:
+            return 0.0
+
+        # Base score from confidence - explicitly typed to avoid Column type issues
+        score: float = float(model.confidence)
+
+        # Boost for reinforcements (diminishing returns)
+        reinforcement_boost = min(0.2, float(model.reinforcement_count) * 0.02)
+        score += reinforcement_boost
+
+        # Find supporting facts
+        supporting = await self._find_supporting_facts(
+            subject=model.subject,  # type: ignore[arg-type]
+            predicate=model.predicate,  # type: ignore[arg-type]
+            project_id=model.project_id,  # type: ignore[arg-type]
+        )
+        support_boost = min(0.1, len(supporting) * 0.02)
+        score += support_boost
+
+        # Check for conflicts
+        conflicts = await self._find_contradictions(
+            subject=model.subject,  # type: ignore[arg-type]
+            predicate=model.predicate,  # type: ignore[arg-type]
+            obj=model.object,  # type: ignore[arg-type]
+            project_id=model.project_id,  # type: ignore[arg-type]
+        )
+        conflict_penalty = min(0.3, len(conflicts) * 0.1)
+        score -= conflict_penalty
+
+        # Clamp to valid range
+        return max(0.0, min(1.0, score))
+
+    def _model_to_fact(self, model: FactModel) -> Fact:
+        """Convert SQLAlchemy model to Fact dataclass."""
+        return Fact(
+            id=model.id,  # type: ignore[arg-type]
+            project_id=model.project_id,  # type: ignore[arg-type]
+            subject=model.subject,  # type: ignore[arg-type]
+            predicate=model.predicate,  # type: ignore[arg-type]
+            object=model.object,  # type: ignore[arg-type]
+            confidence=model.confidence,  # type: ignore[arg-type]
+            source_episode_ids=model.source_episode_ids or [],  # type: ignore[arg-type]
+            first_learned=model.first_learned,  # type: ignore[arg-type]
+            last_reinforced=model.last_reinforced,  # type: ignore[arg-type]
+            reinforcement_count=model.reinforcement_count,  # type: ignore[arg-type]
+            embedding=None,
+            created_at=model.created_at,  # type: ignore[arg-type]
+            updated_at=model.updated_at,  # type: ignore[arg-type]
+        )

backend/app/services/memory/types.py

@@ -0,0 +1,327 @@
+"""
+Memory System Types
+
+Core type definitions and interfaces for the Agent Memory System.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+from uuid import UUID
+
+
+def _utcnow() -> datetime:
+    """Get current UTC time as timezone-aware datetime."""
+    return datetime.now(UTC)
+
+
+class MemoryType(str, Enum):
+    """Types of memory in the agent memory system."""
+
+    WORKING = "working"
+    EPISODIC = "episodic"
+    SEMANTIC = "semantic"
+    PROCEDURAL = "procedural"
+
+
+class ScopeLevel(str, Enum):
+    """Hierarchical scoping levels for memory."""
+
+    GLOBAL = "global"
+    PROJECT = "project"
+    AGENT_TYPE = "agent_type"
+    AGENT_INSTANCE = "agent_instance"
+    SESSION = "session"
+
+
+class Outcome(str, Enum):
+    """Outcome of a task or episode."""
+
+    SUCCESS = "success"
+    FAILURE = "failure"
+    PARTIAL = "partial"
+
+
+class ConsolidationStatus(str, Enum):
+    """Status of a memory consolidation job."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class ConsolidationType(str, Enum):
+    """Types of memory consolidation."""
+
+    WORKING_TO_EPISODIC = "working_to_episodic"
+    EPISODIC_TO_SEMANTIC = "episodic_to_semantic"
+    EPISODIC_TO_PROCEDURAL = "episodic_to_procedural"
+    PRUNING = "pruning"
+
+
+@dataclass
+class ScopeContext:
+    """Represents a memory scope with its hierarchy."""
+
+    scope_type: ScopeLevel
+    scope_id: str
+    parent: "ScopeContext | None" = None
+
+    def get_hierarchy(self) -> list["ScopeContext"]:
+        """Get the full scope hierarchy from root to this scope."""
+        hierarchy: list[ScopeContext] = []
+        current: ScopeContext | None = self
+        while current is not None:
+            hierarchy.insert(0, current)
+            current = current.parent
+        return hierarchy
+
+    def to_key_prefix(self) -> str:
+        """Convert scope to a key prefix for storage."""
+        return f"{self.scope_type.value}:{self.scope_id}"
+
+
+@dataclass
+class MemoryItem:
+    """Base class for all memory items."""
+
+    id: UUID
+    memory_type: MemoryType
+    scope_type: ScopeLevel
+    scope_id: str
+    created_at: datetime
+    updated_at: datetime
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def get_age_seconds(self) -> float:
+        """Get the age of this memory item in seconds."""
+        return (_utcnow() - self.created_at).total_seconds()
+
+
+@dataclass
+class WorkingMemoryItem:
+    """A key-value item in working memory."""
+
+    id: UUID
+    scope_type: ScopeLevel
+    scope_id: str
+    key: str
+    value: Any
+    expires_at: datetime | None = None
+    created_at: datetime = field(default_factory=_utcnow)
+    updated_at: datetime = field(default_factory=_utcnow)
+
+    def is_expired(self) -> bool:
+        """Check if this item has expired."""
+        if self.expires_at is None:
+            return False
+        return _utcnow() > self.expires_at
+
+
+@dataclass
+class TaskState:
+    """Current state of a task in working memory."""
+
+    task_id: str
+    task_type: str
+    description: str
+    status: str = "in_progress"
+    current_step: int = 0
+    total_steps: int = 0
+    progress_percent: float = 0.0
+    context: dict[str, Any] = field(default_factory=dict)
+    started_at: datetime = field(default_factory=_utcnow)
+    updated_at: datetime = field(default_factory=_utcnow)
+
+
+@dataclass
+class Episode:
+    """An episodic memory - a recorded experience."""
+
+    id: UUID
+    project_id: UUID
+    agent_instance_id: UUID | None
+    agent_type_id: UUID | None
+    session_id: str
+    task_type: str
+    task_description: str
+    actions: list[dict[str, Any]]
+    context_summary: str
+    outcome: Outcome
+    outcome_details: str
+    duration_seconds: float
+    tokens_used: int
+    lessons_learned: list[str]
+    importance_score: float
+    embedding: list[float] | None
+    occurred_at: datetime
+    created_at: datetime
+    updated_at: datetime
+
+
+@dataclass
+class EpisodeCreate:
+    """Data required to create a new episode."""
+
+    project_id: UUID
+    session_id: str
+    task_type: str
+    task_description: str
+    actions: list[dict[str, Any]]
+    context_summary: str
+    outcome: Outcome
+    outcome_details: str
+    duration_seconds: float
+    tokens_used: int
+    lessons_learned: list[str] = field(default_factory=list)
+    importance_score: float = 0.5
+    agent_instance_id: UUID | None = None
+    agent_type_id: UUID | None = None
+
+
+@dataclass
+class Fact:
+    """A semantic memory fact - a piece of knowledge."""
+
+    id: UUID
+    project_id: UUID | None  # None for global facts
+    subject: str
+    predicate: str
+    object: str
+    confidence: float
+    source_episode_ids: list[UUID]
+    first_learned: datetime
+    last_reinforced: datetime
+    reinforcement_count: int
+    embedding: list[float] | None
+    created_at: datetime
+    updated_at: datetime
+
+
+@dataclass
+class FactCreate:
+    """Data required to create a new fact."""
+
+    subject: str
+    predicate: str
+    object: str
+    confidence: float = 0.8
+    project_id: UUID | None = None
+    source_episode_ids: list[UUID] = field(default_factory=list)
+
+
+@dataclass
+class Procedure:
+    """A procedural memory - a learned skill or procedure."""
+
+    id: UUID
+    project_id: UUID | None
+    agent_type_id: UUID | None
+    name: str
+    trigger_pattern: str
+    steps: list[dict[str, Any]]
+    success_count: int
+    failure_count: int
+    last_used: datetime | None
+    embedding: list[float] | None
+    created_at: datetime
+    updated_at: datetime
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate the success rate of this procedure."""
+        total = self.success_count + self.failure_count
+        if total == 0:
+            return 0.0
+        return self.success_count / total
+
+
+@dataclass
+class ProcedureCreate:
+    """Data required to create a new procedure."""
+
+    name: str
+    trigger_pattern: str
+    steps: list[dict[str, Any]]
+    project_id: UUID | None = None
+    agent_type_id: UUID | None = None
+
+
+@dataclass
+class Step:
+    """A single step in a procedure."""
+
+    order: int
+    action: str
+    parameters: dict[str, Any] = field(default_factory=dict)
+    expected_outcome: str = ""
+    fallback_action: str | None = None
+
+
+class MemoryStore[T: MemoryItem](ABC):
+    """Abstract base class for memory storage backends."""
+
+    @abstractmethod
+    async def store(self, item: T) -> T:
+        """Store a memory item."""
+        ...
+
+    @abstractmethod
+    async def get(self, item_id: UUID) -> T | None:
+        """Get a memory item by ID."""
+        ...
+
+    @abstractmethod
+    async def delete(self, item_id: UUID) -> bool:
+        """Delete a memory item."""
+        ...
+
+    @abstractmethod
+    async def list(
+        self,
+        scope_type: ScopeLevel | None = None,
+        scope_id: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[T]:
+        """List memory items with optional scope filtering."""
+        ...
+
+    @abstractmethod
+    async def count(
+        self,
+        scope_type: ScopeLevel | None = None,
+        scope_id: str | None = None,
+    ) -> int:
+        """Count memory items with optional scope filtering."""
+        ...
+
+
+@dataclass
+class RetrievalResult[T]:
+    """Result of a memory retrieval operation."""
+
+    items: list[T]
+    total_count: int
+    query: str
+    retrieval_type: str
+    latency_ms: float
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class MemoryStats:
+    """Statistics about memory usage."""
+
+    memory_type: MemoryType
+    scope_type: ScopeLevel | None
+    scope_id: str | None
+    item_count: int
+    total_size_bytes: int
+    oldest_item_age_seconds: float
+    newest_item_age_seconds: float
+    avg_item_size_bytes: float
+    metadata: dict[str, Any] = field(default_factory=dict)

backend/app/services/memory/working/__init__.py

@@ -0,0 +1,16 @@
+# app/services/memory/working/__init__.py
+"""
+Working Memory Implementation.
+
+Provides short-term memory storage with Redis primary and in-memory fallback.
+"""
+
+from .memory import WorkingMemory
+from .storage import InMemoryStorage, RedisStorage, WorkingMemoryStorage
+
+__all__ = [
+    "InMemoryStorage",
+    "RedisStorage",
+    "WorkingMemory",
+    "WorkingMemoryStorage",
+]

backend/app/services/memory/working/memory.py

@@ -0,0 +1,543 @@
+# app/services/memory/working/memory.py
+"""
+Working Memory Implementation.
+
+Provides session-scoped ephemeral memory with:
+- Key-value storage with TTL
+- Task state tracking
+- Scratchpad for reasoning steps
+- Checkpoint/snapshot support
+"""
+
+import logging
+import uuid
+from dataclasses import asdict
+from datetime import UTC, datetime
+from typing import Any
+
+from app.services.memory.config import get_memory_settings
+from app.services.memory.exceptions import (
+    MemoryConnectionError,
+    MemoryNotFoundError,
+)
+from app.services.memory.types import ScopeContext, ScopeLevel, TaskState
+
+from .storage import InMemoryStorage, RedisStorage, WorkingMemoryStorage
+
+logger = logging.getLogger(__name__)
+
+
+# Reserved key prefixes for internal use
+_TASK_STATE_KEY = "_task_state"
+_SCRATCHPAD_KEY = "_scratchpad"
+_CHECKPOINT_PREFIX = "_checkpoint:"
+_METADATA_KEY = "_metadata"
+
+
+class WorkingMemory:
+    """
+    Session-scoped working memory.
+
+    Provides ephemeral storage for agent's current task context:
+    - Variables and intermediate data
+    - Task state (current step, status, progress)
+    - Scratchpad for reasoning steps
+    - Checkpoints for recovery
+
+    Uses Redis as primary storage with in-memory fallback.
+    """
+
+    def __init__(
+        self,
+        scope: ScopeContext,
+        storage: WorkingMemoryStorage,
+        default_ttl_seconds: int | None = None,
+    ) -> None:
+        """
+        Initialize working memory for a scope.
+
+        Args:
+            scope: The scope context (session, agent instance, etc.)
+            storage: Storage backend (use create() factory for auto-configuration)
+            default_ttl_seconds: Default TTL for keys (None = no expiration)
+        """
+        self._scope = scope
+        self._storage: WorkingMemoryStorage = storage
+        self._default_ttl = default_ttl_seconds
+        self._using_fallback = False
+        self._initialized = False
+
+    @classmethod
+    async def create(
+        cls,
+        scope: ScopeContext,
+        default_ttl_seconds: int | None = None,
+    ) -> "WorkingMemory":
+        """
+        Factory method to create WorkingMemory with auto-configured storage.
+
+        Attempts Redis first, falls back to in-memory if unavailable.
+        """
+        settings = get_memory_settings()
+        key_prefix = f"wm:{scope.to_key_prefix()}:"
+        storage: WorkingMemoryStorage
+
+        # Try Redis first
+        if settings.working_memory_backend == "redis":
+            redis_storage = RedisStorage(key_prefix=key_prefix)
+            try:
+                if await redis_storage.is_healthy():
+                    logger.debug(f"Using Redis storage for scope {scope.scope_id}")
+                    instance = cls(
+                        scope=scope,
+                        storage=redis_storage,
+                        default_ttl_seconds=default_ttl_seconds
+                        or settings.working_memory_default_ttl_seconds,
+                    )
+                    await instance._initialize()
+                    return instance
+            except MemoryConnectionError:
+                logger.warning("Redis unavailable, falling back to in-memory storage")
+                await redis_storage.close()
+
+        # Fall back to in-memory
+        storage = InMemoryStorage(
+            max_keys=settings.working_memory_max_items_per_session
+        )
+        instance = cls(
+            scope=scope,
+            storage=storage,
+            default_ttl_seconds=default_ttl_seconds
+            or settings.working_memory_default_ttl_seconds,
+        )
+        instance._using_fallback = True
+        await instance._initialize()
+        return instance
+
+    @classmethod
+    async def for_session(
+        cls,
+        session_id: str,
+        project_id: str | None = None,
+        agent_instance_id: str | None = None,
+    ) -> "WorkingMemory":
+        """
+        Convenience factory for session-scoped working memory.
+
+        Args:
+            session_id: Unique session identifier
+            project_id: Optional project context
+            agent_instance_id: Optional agent instance context
+        """
+        # Build scope hierarchy
+        parent = None
+        if project_id:
+            parent = ScopeContext(
+                scope_type=ScopeLevel.PROJECT,
+                scope_id=project_id,
+            )
+            if agent_instance_id:
+                parent = ScopeContext(
+                    scope_type=ScopeLevel.AGENT_INSTANCE,
+                    scope_id=agent_instance_id,
+                    parent=parent,
+                )
+
+        scope = ScopeContext(
+            scope_type=ScopeLevel.SESSION,
+            scope_id=session_id,
+            parent=parent,
+        )
+
+        return await cls.create(scope=scope)
+
+    async def _initialize(self) -> None:
+        """Initialize working memory metadata."""
+        if self._initialized:
+            return
+
+        metadata = {
+            "scope_type": self._scope.scope_type.value,
+            "scope_id": self._scope.scope_id,
+            "created_at": datetime.now(UTC).isoformat(),
+            "using_fallback": self._using_fallback,
+        }
+        await self._storage.set(_METADATA_KEY, metadata)
+        self._initialized = True
+
+    @property
+    def scope(self) -> ScopeContext:
+        """Get the scope context."""
+        return self._scope
+
+    @property
+    def is_using_fallback(self) -> bool:
+        """Check if using fallback in-memory storage."""
+        return self._using_fallback
+
+    # =========================================================================
+    # Basic Key-Value Operations
+    # =========================================================================
+
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        ttl_seconds: int | None = None,
+    ) -> None:
+        """
+        Store a value.
+
+        Args:
+            key: The key to store under
+            value: The value to store (must be JSON-serializable)
+            ttl_seconds: Optional TTL (uses default if not specified)
+        """
+        if key.startswith("_"):
+            raise ValueError("Keys starting with '_' are reserved for internal use")
+
+        ttl = ttl_seconds if ttl_seconds is not None else self._default_ttl
+        await self._storage.set(key, value, ttl)
+
+    async def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get a value.
+
+        Args:
+            key: The key to retrieve
+            default: Default value if key not found
+
+        Returns:
+            The stored value or default
+        """
+        result = await self._storage.get(key)
+        return result if result is not None else default
+
+    async def delete(self, key: str) -> bool:
+        """
+        Delete a key.
+
+        Args:
+            key: The key to delete
+
+        Returns:
+            True if the key existed
+        """
+        if key.startswith("_"):
+            raise ValueError("Cannot delete internal keys directly")
+        return await self._storage.delete(key)
+
+    async def exists(self, key: str) -> bool:
+        """
+        Check if a key exists.
+
+        Args:
+            key: The key to check
+
+        Returns:
+            True if the key exists
+        """
+        return await self._storage.exists(key)
+
+    async def list_keys(self, pattern: str = "*") -> list[str]:
+        """
+        List keys matching a pattern.
+
+        Args:
+            pattern: Glob-style pattern (default "*" for all)
+
+        Returns:
+            List of matching keys (excludes internal keys)
+        """
+        all_keys = await self._storage.list_keys(pattern)
+        return [k for k in all_keys if not k.startswith("_")]
+
+    async def get_all(self) -> dict[str, Any]:
+        """
+        Get all user key-value pairs.
+
+        Returns:
+            Dictionary of all key-value pairs (excludes internal keys)
+        """
+        all_data = await self._storage.get_all()
+        return {k: v for k, v in all_data.items() if not k.startswith("_")}
+
+    async def clear(self) -> int:
+        """
+        Clear all user keys (preserves internal state).
+
+        Returns:
+            Number of keys deleted
+        """
+        # Save internal state
+        task_state = await self._storage.get(_TASK_STATE_KEY)
+        scratchpad = await self._storage.get(_SCRATCHPAD_KEY)
+        metadata = await self._storage.get(_METADATA_KEY)
+
+        count = await self._storage.clear()
+
+        # Restore internal state
+        if metadata is not None:
+            await self._storage.set(_METADATA_KEY, metadata)
+        if task_state is not None:
+            await self._storage.set(_TASK_STATE_KEY, task_state)
+        if scratchpad is not None:
+            await self._storage.set(_SCRATCHPAD_KEY, scratchpad)
+
+        # Adjust count for preserved keys
+        preserved = sum(1 for x in [task_state, scratchpad, metadata] if x is not None)
+        return max(0, count - preserved)
+
+    # =========================================================================
+    # Task State Operations
+    # =========================================================================
+
+    async def set_task_state(self, state: TaskState) -> None:
+        """
+        Set the current task state.
+
+        Args:
+            state: The task state to store
+        """
+        state.updated_at = datetime.now(UTC)
+        await self._storage.set(_TASK_STATE_KEY, asdict(state))
+
+    async def get_task_state(self) -> TaskState | None:
+        """
+        Get the current task state.
+
+        Returns:
+            The current TaskState or None if not set
+        """
+        data = await self._storage.get(_TASK_STATE_KEY)
+        if data is None:
+            return None
+
+        # Convert datetime strings back to datetime objects
+        if isinstance(data.get("started_at"), str):
+            data["started_at"] = datetime.fromisoformat(data["started_at"])
+        if isinstance(data.get("updated_at"), str):
+            data["updated_at"] = datetime.fromisoformat(data["updated_at"])
+
+        return TaskState(**data)
+
+    async def update_task_progress(
+        self,
+        current_step: int | None = None,
+        progress_percent: float | None = None,
+        status: str | None = None,
+    ) -> TaskState | None:
+        """
+        Update task progress fields.
+
+        Args:
+            current_step: New current step number
+            progress_percent: New progress percentage (0.0 to 100.0)
+            status: New status string
+
+        Returns:
+            Updated TaskState or None if no task state exists
+        """
+        state = await self.get_task_state()
+        if state is None:
+            return None
+
+        if current_step is not None:
+            state.current_step = current_step
+        if progress_percent is not None:
+            state.progress_percent = min(100.0, max(0.0, progress_percent))
+        if status is not None:
+            state.status = status
+
+        await self.set_task_state(state)
+        return state
+
+    # =========================================================================
+    # Scratchpad Operations
+    # =========================================================================
+
+    async def append_scratchpad(self, content: str) -> None:
+        """
+        Append content to the scratchpad.
+
+        Args:
+            content: Text to append
+        """
+        settings = get_memory_settings()
+        entries = await self._storage.get(_SCRATCHPAD_KEY) or []
+
+        # Check capacity
+        if len(entries) >= settings.working_memory_max_items_per_session:
+            # Remove oldest entries
+            entries = entries[-(settings.working_memory_max_items_per_session - 1) :]
+
+        entry = {
+            "content": content,
+            "timestamp": datetime.now(UTC).isoformat(),
+        }
+        entries.append(entry)
+        await self._storage.set(_SCRATCHPAD_KEY, entries)
+
+    async def get_scratchpad(self) -> list[str]:
+        """
+        Get all scratchpad entries.
+
+        Returns:
+            List of scratchpad content strings (ordered by time)
+        """
+        entries = await self._storage.get(_SCRATCHPAD_KEY) or []
+        return [e["content"] for e in entries]
+
+    async def get_scratchpad_with_timestamps(self) -> list[dict[str, Any]]:
+        """
+        Get all scratchpad entries with timestamps.
+
+        Returns:
+            List of dicts with 'content' and 'timestamp' keys
+        """
+        return await self._storage.get(_SCRATCHPAD_KEY) or []
+
+    async def clear_scratchpad(self) -> int:
+        """
+        Clear the scratchpad.
+
+        Returns:
+            Number of entries cleared
+        """
+        entries = await self._storage.get(_SCRATCHPAD_KEY) or []
+        count = len(entries)
+        await self._storage.set(_SCRATCHPAD_KEY, [])
+        return count
+
+    # =========================================================================
+    # Checkpoint Operations
+    # =========================================================================
+
+    async def create_checkpoint(self, description: str = "") -> str:
+        """
+        Create a checkpoint of current state.
+
+        Args:
+            description: Optional description of the checkpoint
+
+        Returns:
+            Checkpoint ID for later restoration
+        """
+        checkpoint_id = str(uuid.uuid4())[:8]
+        checkpoint_key = f"{_CHECKPOINT_PREFIX}{checkpoint_id}"
+
+        # Capture all current state
+        all_data = await self._storage.get_all()
+
+        checkpoint = {
+            "id": checkpoint_id,
+            "description": description,
+            "created_at": datetime.now(UTC).isoformat(),
+            "data": all_data,
+        }
+
+        await self._storage.set(checkpoint_key, checkpoint)
+        logger.debug(f"Created checkpoint {checkpoint_id}")
+        return checkpoint_id
+
+    async def restore_checkpoint(self, checkpoint_id: str) -> None:
+        """
+        Restore state from a checkpoint.
+
+        Args:
+            checkpoint_id: ID of the checkpoint to restore
+
+        Raises:
+            MemoryNotFoundError: If checkpoint not found
+        """
+        checkpoint_key = f"{_CHECKPOINT_PREFIX}{checkpoint_id}"
+        checkpoint = await self._storage.get(checkpoint_key)
+
+        if checkpoint is None:
+            raise MemoryNotFoundError(f"Checkpoint {checkpoint_id} not found")
+
+        # Clear current state
+        await self._storage.clear()
+
+        # Restore all data from checkpoint
+        for key, value in checkpoint["data"].items():
+            await self._storage.set(key, value)
+
+        # Keep the checkpoint itself
+        await self._storage.set(checkpoint_key, checkpoint)
+
+        logger.debug(f"Restored checkpoint {checkpoint_id}")
+
+    async def list_checkpoints(self) -> list[dict[str, Any]]:
+        """
+        List all available checkpoints.
+
+        Returns:
+            List of checkpoint metadata (id, description, created_at)
+        """
+        checkpoint_keys = await self._storage.list_keys(f"{_CHECKPOINT_PREFIX}*")
+        checkpoints = []
+
+        for key in checkpoint_keys:
+            data = await self._storage.get(key)
+            if data:
+                checkpoints.append(
+                    {
+                        "id": data["id"],
+                        "description": data["description"],
+                        "created_at": data["created_at"],
+                    }
+                )
+
+        # Sort by creation time
+        checkpoints.sort(key=lambda x: x["created_at"])
+        return checkpoints
+
+    async def delete_checkpoint(self, checkpoint_id: str) -> bool:
+        """
+        Delete a checkpoint.
+
+        Args:
+            checkpoint_id: ID of the checkpoint to delete
+
+        Returns:
+            True if checkpoint existed
+        """
+        checkpoint_key = f"{_CHECKPOINT_PREFIX}{checkpoint_id}"
+        return await self._storage.delete(checkpoint_key)
+
+    # =========================================================================
+    # Health and Lifecycle
+    # =========================================================================
+
+    async def is_healthy(self) -> bool:
+        """Check if the working memory storage is healthy."""
+        return await self._storage.is_healthy()
+
+    async def close(self) -> None:
+        """Close the working memory storage."""
+        if self._storage:
+            await self._storage.close()
+
+    async def get_stats(self) -> dict[str, Any]:
+        """
+        Get working memory statistics.
+
+        Returns:
+            Dictionary with stats about current state
+        """
+        all_keys = await self._storage.list_keys("*")
+        user_keys = [k for k in all_keys if not k.startswith("_")]
+        checkpoint_keys = [k for k in all_keys if k.startswith(_CHECKPOINT_PREFIX)]
+        scratchpad = await self._storage.get(_SCRATCHPAD_KEY) or []
+
+        return {
+            "scope_type": self._scope.scope_type.value,
+            "scope_id": self._scope.scope_id,
+            "using_fallback": self._using_fallback,
+            "total_keys": len(all_keys),
+            "user_keys": len(user_keys),
+            "checkpoint_count": len(checkpoint_keys),
+            "scratchpad_entries": len(scratchpad),
+            "has_task_state": await self._storage.exists(_TASK_STATE_KEY),
+        }

backend/app/services/memory/working/storage.py

@@ -0,0 +1,406 @@
+# app/services/memory/working/storage.py
+"""
+Working Memory Storage Backends.
+
+Provides abstract storage interface and implementations:
+- RedisStorage: Primary storage using Redis with connection pooling
+- InMemoryStorage: Fallback storage when Redis is unavailable
+"""
+
+import asyncio
+import fnmatch
+import json
+import logging
+from abc import ABC, abstractmethod
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from app.services.memory.config import get_memory_settings
+from app.services.memory.exceptions import (
+    MemoryConnectionError,
+    MemoryStorageError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class WorkingMemoryStorage(ABC):
+    """Abstract base class for working memory storage backends."""
+
+    @abstractmethod
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        ttl_seconds: int | None = None,
+    ) -> None:
+        """Store a value with optional TTL."""
+        ...
+
+    @abstractmethod
+    async def get(self, key: str) -> Any | None:
+        """Get a value by key, returns None if not found or expired."""
+        ...
+
+    @abstractmethod
+    async def delete(self, key: str) -> bool:
+        """Delete a key, returns True if existed."""
+        ...
+
+    @abstractmethod
+    async def exists(self, key: str) -> bool:
+        """Check if a key exists and is not expired."""
+        ...
+
+    @abstractmethod
+    async def list_keys(self, pattern: str = "*") -> list[str]:
+        """List all keys matching a pattern."""
+        ...
+
+    @abstractmethod
+    async def get_all(self) -> dict[str, Any]:
+        """Get all key-value pairs."""
+        ...
+
+    @abstractmethod
+    async def clear(self) -> int:
+        """Clear all keys, returns count of deleted keys."""
+        ...
+
+    @abstractmethod
+    async def is_healthy(self) -> bool:
+        """Check if the storage backend is healthy."""
+        ...
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Close the storage connection."""
+        ...
+
+
+class InMemoryStorage(WorkingMemoryStorage):
+    """
+    In-memory storage backend for working memory.
+
+    Used as fallback when Redis is unavailable. Data is not persisted
+    across restarts and is not shared between processes.
+    """
+
+    def __init__(self, max_keys: int = 10000) -> None:
+        """Initialize in-memory storage."""
+        self._data: dict[str, Any] = {}
+        self._expirations: dict[str, datetime] = {}
+        self._max_keys = max_keys
+        self._lock = asyncio.Lock()
+
+    def _is_expired(self, key: str) -> bool:
+        """Check if a key has expired."""
+        if key not in self._expirations:
+            return False
+        return datetime.now(UTC) > self._expirations[key]
+
+    def _cleanup_expired(self) -> None:
+        """Remove all expired keys."""
+        now = datetime.now(UTC)
+        expired_keys = [
+            key for key, exp_time in self._expirations.items() if now > exp_time
+        ]
+        for key in expired_keys:
+            self._data.pop(key, None)
+            self._expirations.pop(key, None)
+
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        ttl_seconds: int | None = None,
+    ) -> None:
+        """Store a value with optional TTL."""
+        async with self._lock:
+            # Cleanup expired keys periodically
+            if len(self._data) % 100 == 0:
+                self._cleanup_expired()
+
+            # Check capacity
+            if key not in self._data and len(self._data) >= self._max_keys:
+                # Evict expired keys first
+                self._cleanup_expired()
+                if len(self._data) >= self._max_keys:
+                    raise MemoryStorageError(
+                        f"Working memory capacity exceeded: {self._max_keys} keys"
+                    )
+
+            self._data[key] = value
+            if ttl_seconds is not None:
+                self._expirations[key] = datetime.now(UTC) + timedelta(
+                    seconds=ttl_seconds
+                )
+            elif key in self._expirations:
+                # Remove existing expiration if no TTL specified
+                del self._expirations[key]
+
+    async def get(self, key: str) -> Any | None:
+        """Get a value by key."""
+        async with self._lock:
+            if key not in self._data:
+                return None
+            if self._is_expired(key):
+                del self._data[key]
+                del self._expirations[key]
+                return None
+            return self._data[key]
+
+    async def delete(self, key: str) -> bool:
+        """Delete a key."""
+        async with self._lock:
+            existed = key in self._data
+            self._data.pop(key, None)
+            self._expirations.pop(key, None)
+            return existed
+
+    async def exists(self, key: str) -> bool:
+        """Check if a key exists and is not expired."""
+        async with self._lock:
+            if key not in self._data:
+                return False
+            if self._is_expired(key):
+                del self._data[key]
+                del self._expirations[key]
+                return False
+            return True
+
+    async def list_keys(self, pattern: str = "*") -> list[str]:
+        """List all keys matching a pattern."""
+        async with self._lock:
+            self._cleanup_expired()
+            if pattern == "*":
+                return list(self._data.keys())
+            return [key for key in self._data.keys() if fnmatch.fnmatch(key, pattern)]
+
+    async def get_all(self) -> dict[str, Any]:
+        """Get all key-value pairs."""
+        async with self._lock:
+            self._cleanup_expired()
+            return dict(self._data)
+
+    async def clear(self) -> int:
+        """Clear all keys."""
+        async with self._lock:
+            count = len(self._data)
+            self._data.clear()
+            self._expirations.clear()
+            return count
+
+    async def is_healthy(self) -> bool:
+        """In-memory storage is always healthy."""
+        return True
+
+    async def close(self) -> None:
+        """No cleanup needed for in-memory storage."""
+
+
+class RedisStorage(WorkingMemoryStorage):
+    """
+    Redis storage backend for working memory.
+
+    Primary storage with connection pooling, automatic reconnection,
+    and proper serialization of Python objects.
+    """
+
+    def __init__(
+        self,
+        key_prefix: str = "",
+        connection_timeout: float = 5.0,
+        socket_timeout: float = 5.0,
+    ) -> None:
+        """
+        Initialize Redis storage.
+
+        Args:
+            key_prefix: Prefix for all keys (e.g., "session:abc123:")
+            connection_timeout: Timeout for establishing connections
+            socket_timeout: Timeout for socket operations
+        """
+        self._key_prefix = key_prefix
+        self._connection_timeout = connection_timeout
+        self._socket_timeout = socket_timeout
+        self._redis: Any = None
+        self._lock = asyncio.Lock()
+
+    def _make_key(self, key: str) -> str:
+        """Add prefix to key."""
+        return f"{self._key_prefix}{key}"
+
+    def _strip_prefix(self, key: str) -> str:
+        """Remove prefix from key."""
+        if key.startswith(self._key_prefix):
+            return key[len(self._key_prefix) :]
+        return key
+
+    def _serialize(self, value: Any) -> str:
+        """Serialize a Python value to JSON string."""
+        return json.dumps(value, default=str)
+
+    def _deserialize(self, data: str | bytes | None) -> Any | None:
+        """Deserialize a JSON string to Python value."""
+        if data is None:
+            return None
+        if isinstance(data, bytes):
+            data = data.decode("utf-8")
+        return json.loads(data)
+
+    async def _get_client(self) -> Any:
+        """Get or create Redis client."""
+        if self._redis is not None:
+            return self._redis
+
+        async with self._lock:
+            if self._redis is not None:
+                return self._redis
+
+            try:
+                import redis.asyncio as aioredis
+            except ImportError as e:
+                raise MemoryConnectionError(
+                    "redis package not installed. Install with: pip install redis"
+                ) from e
+
+            settings = get_memory_settings()
+            redis_url = settings.redis_url
+
+            try:
+                self._redis = await aioredis.from_url(
+                    redis_url,
+                    encoding="utf-8",
+                    decode_responses=True,
+                    socket_connect_timeout=self._connection_timeout,
+                    socket_timeout=self._socket_timeout,
+                )
+                # Test connection
+                await self._redis.ping()
+                logger.info("Connected to Redis for working memory")
+                return self._redis
+            except Exception as e:
+                self._redis = None
+                raise MemoryConnectionError(f"Failed to connect to Redis: {e}") from e
+
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        ttl_seconds: int | None = None,
+    ) -> None:
+        """Store a value with optional TTL."""
+        try:
+            client = await self._get_client()
+            full_key = self._make_key(key)
+            serialized = self._serialize(value)
+
+            if ttl_seconds is not None:
+                await client.setex(full_key, ttl_seconds, serialized)
+            else:
+                await client.set(full_key, serialized)
+        except MemoryConnectionError:
+            raise
+        except Exception as e:
+            raise MemoryStorageError(f"Failed to set key {key}: {e}") from e
+
+    async def get(self, key: str) -> Any | None:
+        """Get a value by key."""
+        try:
+            client = await self._get_client()
+            full_key = self._make_key(key)
+            data = await client.get(full_key)
+            return self._deserialize(data)
+        except MemoryConnectionError:
+            raise
+        except Exception as e:
+            raise MemoryStorageError(f"Failed to get key {key}: {e}") from e
+
+    async def delete(self, key: str) -> bool:
+        """Delete a key."""
+        try:
+            client = await self._get_client()
+            full_key = self._make_key(key)
+            result = await client.delete(full_key)
+            return bool(result)
+        except MemoryConnectionError:
+            raise
+        except Exception as e:
+            raise MemoryStorageError(f"Failed to delete key {key}: {e}") from e
+
+    async def exists(self, key: str) -> bool:
+        """Check if a key exists."""
+        try:
+            client = await self._get_client()
+            full_key = self._make_key(key)
+            result = await client.exists(full_key)
+            return bool(result)
+        except MemoryConnectionError:
+            raise
+        except Exception as e:
+            raise MemoryStorageError(f"Failed to check key {key}: {e}") from e
+
+    async def list_keys(self, pattern: str = "*") -> list[str]:
+        """List all keys matching a pattern."""
+        try:
+            client = await self._get_client()
+            full_pattern = self._make_key(pattern)
+            keys = await client.keys(full_pattern)
+            return [self._strip_prefix(key) for key in keys]
+        except MemoryConnectionError:
+            raise
+        except Exception as e:
+            raise MemoryStorageError(f"Failed to list keys: {e}") from e
+
+    async def get_all(self) -> dict[str, Any]:
+        """Get all key-value pairs."""
+        try:
+            client = await self._get_client()
+            full_pattern = self._make_key("*")
+            keys = await client.keys(full_pattern)
+
+            if not keys:
+                return {}
+
+            values = await client.mget(*keys)
+            result = {}
+            for key, value in zip(keys, values, strict=False):
+                stripped_key = self._strip_prefix(key)
+                result[stripped_key] = self._deserialize(value)
+            return result
+        except MemoryConnectionError:
+            raise
+        except Exception as e:
+            raise MemoryStorageError(f"Failed to get all keys: {e}") from e
+
+    async def clear(self) -> int:
+        """Clear all keys with this prefix."""
+        try:
+            client = await self._get_client()
+            full_pattern = self._make_key("*")
+            keys = await client.keys(full_pattern)
+
+            if not keys:
+                return 0
+
+            return await client.delete(*keys)
+        except MemoryConnectionError:
+            raise
+        except Exception as e:
+            raise MemoryStorageError(f"Failed to clear keys: {e}") from e
+
+    async def is_healthy(self) -> bool:
+        """Check if Redis connection is healthy."""
+        try:
+            client = await self._get_client()
+            await client.ping()
+            return True
+        except Exception:
+            return False
+
+    async def close(self) -> None:
+        """Close the Redis connection."""
+        if self._redis is not None:
+            await self._redis.close()
+            self._redis = None

backend/app/tasks/__init__.py

@@ -10,14 +10,16 @@ Modules:
     sync: Issue synchronization tasks (incremental/full sync, webhooks)
     workflow: Workflow state management tasks
     cost: Cost tracking and budget monitoring tasks
+    memory_consolidation: Memory consolidation tasks
 """
 
-from app.tasks import agent, cost, git, sync, workflow
+from app.tasks import agent, cost, git, memory_consolidation, sync, workflow
 
 __all__ = [
     "agent",
     "cost",
     "git",
+    "memory_consolidation",
     "sync",
     "workflow",
 ]

backend/app/tasks/memory_consolidation.py

@@ -0,0 +1,234 @@
+# app/tasks/memory_consolidation.py
+"""
+Memory consolidation Celery tasks.
+
+Handles scheduled and on-demand memory consolidation:
+- Session consolidation (on session end)
+- Nightly consolidation (scheduled)
+- On-demand project consolidation
+"""
+
+import logging
+from typing import Any
+
+from app.celery_app import celery_app
+
+logger = logging.getLogger(__name__)
+
+
+@celery_app.task(
+    bind=True,
+    name="app.tasks.memory_consolidation.consolidate_session",
+    autoretry_for=(Exception,),
+    retry_backoff=True,
+    retry_kwargs={"max_retries": 3},
+)
+def consolidate_session(
+    self,
+    project_id: str,
+    session_id: str,
+    task_type: str = "session_task",
+    agent_instance_id: str | None = None,
+    agent_type_id: str | None = None,
+) -> dict[str, Any]:
+    """
+    Consolidate a session's working memory to episodic memory.
+
+    This task is triggered when an agent session ends to transfer
+    relevant session data into persistent episodic memory.
+
+    Args:
+        project_id: UUID of the project
+        session_id: Session identifier
+        task_type: Type of task performed
+        agent_instance_id: Optional agent instance UUID
+        agent_type_id: Optional agent type UUID
+
+    Returns:
+        dict with consolidation results
+    """
+    logger.info(f"Consolidating session {session_id} for project {project_id}")
+
+    # TODO: Implement actual consolidation
+    # This will involve:
+    # 1. Getting database session from async context
+    # 2. Loading working memory for session
+    # 3. Calling consolidation service
+    # 4. Returning results
+
+    # Placeholder implementation
+    return {
+        "status": "pending",
+        "project_id": project_id,
+        "session_id": session_id,
+        "episode_created": False,
+    }
+
+
+@celery_app.task(
+    bind=True,
+    name="app.tasks.memory_consolidation.run_nightly_consolidation",
+    autoretry_for=(Exception,),
+    retry_backoff=True,
+    retry_kwargs={"max_retries": 3},
+)
+def run_nightly_consolidation(
+    self,
+    project_id: str,
+    agent_type_id: str | None = None,
+) -> dict[str, Any]:
+    """
+    Run nightly memory consolidation for a project.
+
+    This task performs the full consolidation workflow:
+    1. Extract facts from recent episodes to semantic memory
+    2. Learn procedures from successful episode patterns
+    3. Prune old, low-value memories
+
+    Args:
+        project_id: UUID of the project to consolidate
+        agent_type_id: Optional agent type to filter by
+
+    Returns:
+        dict with consolidation results
+    """
+    logger.info(f"Running nightly consolidation for project {project_id}")
+
+    # TODO: Implement actual consolidation
+    # This will involve:
+    # 1. Getting database session from async context
+    # 2. Creating consolidation service instance
+    # 3. Running run_nightly_consolidation
+    # 4. Returning results
+
+    # Placeholder implementation
+    return {
+        "status": "pending",
+        "project_id": project_id,
+        "total_facts_created": 0,
+        "total_procedures_created": 0,
+        "total_pruned": 0,
+    }
+
+
+@celery_app.task(
+    bind=True,
+    name="app.tasks.memory_consolidation.consolidate_episodes_to_facts",
+    autoretry_for=(Exception,),
+    retry_backoff=True,
+    retry_kwargs={"max_retries": 3},
+)
+def consolidate_episodes_to_facts(
+    self,
+    project_id: str,
+    since_hours: int = 24,
+    limit: int | None = None,
+) -> dict[str, Any]:
+    """
+    Extract facts from episodic memories.
+
+    Args:
+        project_id: UUID of the project
+        since_hours: Process episodes from last N hours
+        limit: Maximum episodes to process
+
+    Returns:
+        dict with extraction results
+    """
+    logger.info(f"Consolidating episodes to facts for project {project_id}")
+
+    # TODO: Implement actual consolidation
+    # Placeholder implementation
+    return {
+        "status": "pending",
+        "project_id": project_id,
+        "items_processed": 0,
+        "items_created": 0,
+    }
+
+
+@celery_app.task(
+    bind=True,
+    name="app.tasks.memory_consolidation.consolidate_episodes_to_procedures",
+    autoretry_for=(Exception,),
+    retry_backoff=True,
+    retry_kwargs={"max_retries": 3},
+)
+def consolidate_episodes_to_procedures(
+    self,
+    project_id: str,
+    agent_type_id: str | None = None,
+    since_days: int = 7,
+) -> dict[str, Any]:
+    """
+    Learn procedures from episodic patterns.
+
+    Args:
+        project_id: UUID of the project
+        agent_type_id: Optional agent type filter
+        since_days: Process episodes from last N days
+
+    Returns:
+        dict with procedure learning results
+    """
+    logger.info(f"Consolidating episodes to procedures for project {project_id}")
+
+    # TODO: Implement actual consolidation
+    # Placeholder implementation
+    return {
+        "status": "pending",
+        "project_id": project_id,
+        "items_processed": 0,
+        "items_created": 0,
+    }
+
+
+@celery_app.task(
+    bind=True,
+    name="app.tasks.memory_consolidation.prune_old_memories",
+    autoretry_for=(Exception,),
+    retry_backoff=True,
+    retry_kwargs={"max_retries": 3},
+)
+def prune_old_memories(
+    self,
+    project_id: str,
+    max_age_days: int = 90,
+    min_importance: float = 0.2,
+) -> dict[str, Any]:
+    """
+    Prune old, low-value memories.
+
+    Args:
+        project_id: UUID of the project
+        max_age_days: Maximum age in days
+        min_importance: Minimum importance to keep
+
+    Returns:
+        dict with pruning results
+    """
+    logger.info(f"Pruning old memories for project {project_id}")
+
+    # TODO: Implement actual pruning
+    # Placeholder implementation
+    return {
+        "status": "pending",
+        "project_id": project_id,
+        "items_pruned": 0,
+    }
+
+
+# =========================================================================
+# Celery Beat Schedule Configuration
+# =========================================================================
+
+# This would typically be configured in celery_app.py or a separate config file
+# Example schedule for nightly consolidation:
+#
+# app.conf.beat_schedule = {
+#     'nightly-memory-consolidation': {
+#         'task': 'app.tasks.memory_consolidation.run_nightly_consolidation',
+#         'schedule': crontab(hour=2, minute=0),  # 2 AM daily
+#         'args': (None,),  # Will process all projects
+#     },
+# }

backend/tests/unit/models/__init__.py

@@ -0,0 +1,2 @@
+# tests/unit/models/__init__.py
+"""Unit tests for database models."""

backend/tests/unit/models/memory/__init__.py

@@ -0,0 +1,2 @@
+# tests/unit/models/memory/__init__.py
+"""Unit tests for memory database models."""

backend/tests/unit/models/memory/test_enums.py

@@ -0,0 +1,71 @@
+# tests/unit/models/memory/test_enums.py
+"""Unit tests for memory model enums."""
+
+from app.models.memory.enums import (
+    ConsolidationStatus,
+    ConsolidationType,
+    EpisodeOutcome,
+    ScopeType,
+)
+
+
+class TestScopeType:
+    """Tests for ScopeType enum."""
+
+    def test_all_values_exist(self) -> None:
+        """Test all expected scope types exist."""
+        assert ScopeType.GLOBAL.value == "global"
+        assert ScopeType.PROJECT.value == "project"
+        assert ScopeType.AGENT_TYPE.value == "agent_type"
+        assert ScopeType.AGENT_INSTANCE.value == "agent_instance"
+        assert ScopeType.SESSION.value == "session"
+
+    def test_scope_count(self) -> None:
+        """Test we have exactly 5 scope types."""
+        assert len(ScopeType) == 5
+
+
+class TestEpisodeOutcome:
+    """Tests for EpisodeOutcome enum."""
+
+    def test_all_values_exist(self) -> None:
+        """Test all expected outcome values exist."""
+        assert EpisodeOutcome.SUCCESS.value == "success"
+        assert EpisodeOutcome.FAILURE.value == "failure"
+        assert EpisodeOutcome.PARTIAL.value == "partial"
+
+    def test_outcome_count(self) -> None:
+        """Test we have exactly 3 outcome types."""
+        assert len(EpisodeOutcome) == 3
+
+
+class TestConsolidationType:
+    """Tests for ConsolidationType enum."""
+
+    def test_all_values_exist(self) -> None:
+        """Test all expected consolidation types exist."""
+        assert ConsolidationType.WORKING_TO_EPISODIC.value == "working_to_episodic"
+        assert ConsolidationType.EPISODIC_TO_SEMANTIC.value == "episodic_to_semantic"
+        assert (
+            ConsolidationType.EPISODIC_TO_PROCEDURAL.value == "episodic_to_procedural"
+        )
+        assert ConsolidationType.PRUNING.value == "pruning"
+
+    def test_consolidation_count(self) -> None:
+        """Test we have exactly 4 consolidation types."""
+        assert len(ConsolidationType) == 4
+
+
+class TestConsolidationStatus:
+    """Tests for ConsolidationStatus enum."""
+
+    def test_all_values_exist(self) -> None:
+        """Test all expected status values exist."""
+        assert ConsolidationStatus.PENDING.value == "pending"
+        assert ConsolidationStatus.RUNNING.value == "running"
+        assert ConsolidationStatus.COMPLETED.value == "completed"
+        assert ConsolidationStatus.FAILED.value == "failed"
+
+    def test_status_count(self) -> None:
+        """Test we have exactly 4 status types."""
+        assert len(ConsolidationStatus) == 4

backend/tests/unit/models/memory/test_models.py

@@ -0,0 +1,249 @@
+# tests/unit/models/memory/test_models.py
+"""Unit tests for memory database models."""
+
+from datetime import UTC, datetime, timedelta
+
+import pytest
+
+from app.models.memory import (
+    ConsolidationStatus,
+    ConsolidationType,
+    Episode,
+    EpisodeOutcome,
+    Fact,
+    MemoryConsolidationLog,
+    Procedure,
+    ScopeType,
+    WorkingMemory,
+)
+
+
+class TestWorkingMemoryModel:
+    """Tests for WorkingMemory model."""
+
+    def test_tablename(self) -> None:
+        """Test table name is correct."""
+        assert WorkingMemory.__tablename__ == "working_memory"
+
+    def test_has_required_columns(self) -> None:
+        """Test all required columns exist."""
+        columns = WorkingMemory.__table__.columns
+        assert "id" in columns
+        assert "scope_type" in columns
+        assert "scope_id" in columns
+        assert "key" in columns
+        assert "value" in columns
+        assert "expires_at" in columns
+        assert "created_at" in columns
+        assert "updated_at" in columns
+
+    def test_has_unique_constraint(self) -> None:
+        """Test unique constraint on scope+key."""
+        indexes = {idx.name: idx for idx in WorkingMemory.__table__.indexes}
+        assert "ix_working_memory_scope_key" in indexes
+        assert indexes["ix_working_memory_scope_key"].unique
+
+
+class TestEpisodeModel:
+    """Tests for Episode model."""
+
+    def test_tablename(self) -> None:
+        """Test table name is correct."""
+        assert Episode.__tablename__ == "episodes"
+
+    def test_has_required_columns(self) -> None:
+        """Test all required columns exist."""
+        columns = Episode.__table__.columns
+        required = [
+            "id",
+            "project_id",
+            "agent_instance_id",
+            "agent_type_id",
+            "session_id",
+            "task_type",
+            "task_description",
+            "actions",
+            "context_summary",
+            "outcome",
+            "outcome_details",
+            "duration_seconds",
+            "tokens_used",
+            "lessons_learned",
+            "importance_score",
+            "embedding",
+            "occurred_at",
+            "created_at",
+            "updated_at",
+        ]
+        for col in required:
+            assert col in columns, f"Missing column: {col}"
+
+    def test_has_foreign_keys(self) -> None:
+        """Test foreign key relationships exist."""
+        columns = Episode.__table__.columns
+        assert columns["project_id"].foreign_keys
+        assert columns["agent_instance_id"].foreign_keys
+        assert columns["agent_type_id"].foreign_keys
+
+    def test_has_relationships(self) -> None:
+        """Test ORM relationships exist."""
+        mapper = Episode.__mapper__
+        assert "project" in mapper.relationships
+        assert "agent_instance" in mapper.relationships
+        assert "agent_type" in mapper.relationships
+
+
+class TestFactModel:
+    """Tests for Fact model."""
+
+    def test_tablename(self) -> None:
+        """Test table name is correct."""
+        assert Fact.__tablename__ == "facts"
+
+    def test_has_required_columns(self) -> None:
+        """Test all required columns exist."""
+        columns = Fact.__table__.columns
+        required = [
+            "id",
+            "project_id",
+            "subject",
+            "predicate",
+            "object",
+            "confidence",
+            "source_episode_ids",
+            "first_learned",
+            "last_reinforced",
+            "reinforcement_count",
+            "embedding",
+            "created_at",
+            "updated_at",
+        ]
+        for col in required:
+            assert col in columns, f"Missing column: {col}"
+
+    def test_project_id_nullable(self) -> None:
+        """Test project_id is nullable for global facts."""
+        columns = Fact.__table__.columns
+        assert columns["project_id"].nullable
+
+
+class TestProcedureModel:
+    """Tests for Procedure model."""
+
+    def test_tablename(self) -> None:
+        """Test table name is correct."""
+        assert Procedure.__tablename__ == "procedures"
+
+    def test_has_required_columns(self) -> None:
+        """Test all required columns exist."""
+        columns = Procedure.__table__.columns
+        required = [
+            "id",
+            "project_id",
+            "agent_type_id",
+            "name",
+            "trigger_pattern",
+            "steps",
+            "success_count",
+            "failure_count",
+            "last_used",
+            "embedding",
+            "created_at",
+            "updated_at",
+        ]
+        for col in required:
+            assert col in columns, f"Missing column: {col}"
+
+    def test_success_rate_property(self) -> None:
+        """Test success_rate calculated property."""
+        proc = Procedure()
+        proc.success_count = 8
+        proc.failure_count = 2
+        assert proc.success_rate == 0.8
+
+    def test_success_rate_zero_total(self) -> None:
+        """Test success_rate with zero total uses."""
+        proc = Procedure()
+        proc.success_count = 0
+        proc.failure_count = 0
+        assert proc.success_rate == 0.0
+
+    def test_total_uses_property(self) -> None:
+        """Test total_uses calculated property."""
+        proc = Procedure()
+        proc.success_count = 5
+        proc.failure_count = 3
+        assert proc.total_uses == 8
+
+
+class TestMemoryConsolidationLogModel:
+    """Tests for MemoryConsolidationLog model."""
+
+    def test_tablename(self) -> None:
+        """Test table name is correct."""
+        assert MemoryConsolidationLog.__tablename__ == "memory_consolidation_log"
+
+    def test_has_required_columns(self) -> None:
+        """Test all required columns exist."""
+        columns = MemoryConsolidationLog.__table__.columns
+        required = [
+            "id",
+            "consolidation_type",
+            "source_count",
+            "result_count",
+            "started_at",
+            "completed_at",
+            "status",
+            "error",
+            "created_at",
+            "updated_at",
+        ]
+        for col in required:
+            assert col in columns, f"Missing column: {col}"
+
+    def test_duration_seconds_property_completed(self) -> None:
+        """Test duration_seconds with completed job."""
+        log = MemoryConsolidationLog()
+        log.started_at = datetime.now(UTC)
+        log.completed_at = log.started_at + timedelta(seconds=10)
+        assert log.duration_seconds == pytest.approx(10.0)
+
+    def test_duration_seconds_property_incomplete(self) -> None:
+        """Test duration_seconds with incomplete job."""
+        log = MemoryConsolidationLog()
+        log.started_at = datetime.now(UTC)
+        log.completed_at = None
+        assert log.duration_seconds is None
+
+    def test_default_status(self) -> None:
+        """Test default status is PENDING."""
+        columns = MemoryConsolidationLog.__table__.columns
+        assert columns["status"].default.arg == ConsolidationStatus.PENDING
+
+
+class TestModelExports:
+    """Tests for model package exports."""
+
+    def test_all_models_exported(self) -> None:
+        """Test all models are exported from package."""
+        from app.models.memory import (
+            Episode,
+            Fact,
+            MemoryConsolidationLog,
+            Procedure,
+            WorkingMemory,
+        )
+
+        # Verify these are the actual classes
+        assert Episode.__tablename__ == "episodes"
+        assert Fact.__tablename__ == "facts"
+        assert Procedure.__tablename__ == "procedures"
+        assert WorkingMemory.__tablename__ == "working_memory"
+        assert MemoryConsolidationLog.__tablename__ == "memory_consolidation_log"
+
+    def test_enums_exported(self) -> None:
+        """Test all enums are exported."""
+        assert ScopeType.GLOBAL.value == "global"
+        assert EpisodeOutcome.SUCCESS.value == "success"
+        assert ConsolidationType.WORKING_TO_EPISODIC.value == "working_to_episodic"
+        assert ConsolidationStatus.PENDING.value == "pending"

backend/tests/unit/services/context/types/test_memory.py

@@ -0,0 +1,262 @@
+# tests/unit/services/context/types/test_memory.py
+"""Tests for MemoryContext type."""
+
+from datetime import UTC, datetime
+from unittest.mock import MagicMock
+from uuid import uuid4
+
+import pytest
+
+from app.services.context.types import ContextType
+from app.services.context.types.memory import MemoryContext, MemorySubtype
+
+
+class TestMemorySubtype:
+    """Tests for MemorySubtype enum."""
+
+    def test_all_types_defined(self) -> None:
+        """All memory subtypes should be defined."""
+        assert MemorySubtype.WORKING == "working"
+        assert MemorySubtype.EPISODIC == "episodic"
+        assert MemorySubtype.SEMANTIC == "semantic"
+        assert MemorySubtype.PROCEDURAL == "procedural"
+
+    def test_enum_values(self) -> None:
+        """Enum values should match strings."""
+        assert MemorySubtype.WORKING.value == "working"
+        assert MemorySubtype("episodic") == MemorySubtype.EPISODIC
+
+
+class TestMemoryContext:
+    """Tests for MemoryContext class."""
+
+    def test_get_type_returns_memory(self) -> None:
+        """get_type should return MEMORY."""
+        ctx = MemoryContext(content="test", source="test_source")
+        assert ctx.get_type() == ContextType.MEMORY
+
+    def test_default_values(self) -> None:
+        """Default values should be set correctly."""
+        ctx = MemoryContext(content="test", source="test_source")
+        assert ctx.memory_subtype == MemorySubtype.EPISODIC
+        assert ctx.memory_id is None
+        assert ctx.relevance_score == 0.0
+        assert ctx.importance == 0.5
+
+    def test_to_dict_includes_memory_fields(self) -> None:
+        """to_dict should include memory-specific fields."""
+        ctx = MemoryContext(
+            content="test content",
+            source="test_source",
+            memory_subtype=MemorySubtype.SEMANTIC,
+            memory_id="mem-123",
+            relevance_score=0.8,
+            subject="User",
+            predicate="prefers",
+            object_value="dark mode",
+        )
+
+        data = ctx.to_dict()
+
+        assert data["memory_subtype"] == "semantic"
+        assert data["memory_id"] == "mem-123"
+        assert data["relevance_score"] == 0.8
+        assert data["subject"] == "User"
+        assert data["predicate"] == "prefers"
+        assert data["object_value"] == "dark mode"
+
+    def test_from_dict(self) -> None:
+        """from_dict should create correct MemoryContext."""
+        data = {
+            "content": "test content",
+            "source": "test_source",
+            "timestamp": "2024-01-01T00:00:00+00:00",
+            "memory_subtype": "semantic",
+            "memory_id": "mem-123",
+            "relevance_score": 0.8,
+            "subject": "Test",
+        }
+
+        ctx = MemoryContext.from_dict(data)
+
+        assert ctx.content == "test content"
+        assert ctx.memory_subtype == MemorySubtype.SEMANTIC
+        assert ctx.memory_id == "mem-123"
+        assert ctx.subject == "Test"
+
+
+class TestMemoryContextFromWorkingMemory:
+    """Tests for MemoryContext.from_working_memory."""
+
+    def test_creates_working_memory_context(self) -> None:
+        """Should create working memory context from key/value."""
+        ctx = MemoryContext.from_working_memory(
+            key="user_preferences",
+            value={"theme": "dark"},
+            source="working:sess-123",
+            query="preferences",
+        )
+
+        assert ctx.memory_subtype == MemorySubtype.WORKING
+        assert ctx.key == "user_preferences"
+        assert "{'theme': 'dark'}" in ctx.content
+        assert ctx.relevance_score == 1.0  # Working memory is always relevant
+        assert ctx.importance == 0.8  # Higher importance
+
+    def test_string_value(self) -> None:
+        """Should handle string values."""
+        ctx = MemoryContext.from_working_memory(
+            key="current_task",
+            value="Build authentication",
+        )
+
+        assert ctx.content == "Build authentication"
+
+
+class TestMemoryContextFromEpisodicMemory:
+    """Tests for MemoryContext.from_episodic_memory."""
+
+    def test_creates_episodic_memory_context(self) -> None:
+        """Should create episodic memory context from episode."""
+        episode = MagicMock()
+        episode.id = uuid4()
+        episode.task_description = "Implemented login feature"
+        episode.task_type = "feature_implementation"
+        episode.outcome = MagicMock(value="success")
+        episode.importance_score = 0.9
+        episode.session_id = "sess-123"
+        episode.occurred_at = datetime.now(UTC)
+        episode.lessons_learned = ["Use proper validation"]
+
+        ctx = MemoryContext.from_episodic_memory(episode, query="login")
+
+        assert ctx.memory_subtype == MemorySubtype.EPISODIC
+        assert ctx.memory_id == str(episode.id)
+        assert ctx.content == "Implemented login feature"
+        assert ctx.task_type == "feature_implementation"
+        assert ctx.outcome == "success"
+        assert ctx.importance == 0.9
+
+    def test_handles_missing_outcome(self) -> None:
+        """Should handle episodes with no outcome."""
+        episode = MagicMock()
+        episode.id = uuid4()
+        episode.task_description = "WIP task"
+        episode.outcome = None
+        episode.importance_score = 0.5
+        episode.occurred_at = None
+
+        ctx = MemoryContext.from_episodic_memory(episode)
+
+        assert ctx.outcome is None
+
+
+class TestMemoryContextFromSemanticMemory:
+    """Tests for MemoryContext.from_semantic_memory."""
+
+    def test_creates_semantic_memory_context(self) -> None:
+        """Should create semantic memory context from fact."""
+        fact = MagicMock()
+        fact.id = uuid4()
+        fact.subject = "User"
+        fact.predicate = "prefers"
+        fact.object = "dark mode"
+        fact.confidence = 0.95
+
+        ctx = MemoryContext.from_semantic_memory(fact, query="user preferences")
+
+        assert ctx.memory_subtype == MemorySubtype.SEMANTIC
+        assert ctx.memory_id == str(fact.id)
+        assert ctx.content == "User prefers dark mode"
+        assert ctx.subject == "User"
+        assert ctx.predicate == "prefers"
+        assert ctx.object_value == "dark mode"
+        assert ctx.relevance_score == 0.95
+
+
+class TestMemoryContextFromProceduralMemory:
+    """Tests for MemoryContext.from_procedural_memory."""
+
+    def test_creates_procedural_memory_context(self) -> None:
+        """Should create procedural memory context from procedure."""
+        procedure = MagicMock()
+        procedure.id = uuid4()
+        procedure.name = "Deploy to Production"
+        procedure.trigger_pattern = "When deploying to production"
+        procedure.steps = [
+            {"action": "run_tests"},
+            {"action": "build_docker"},
+            {"action": "deploy"},
+        ]
+        procedure.success_rate = 0.85
+        procedure.success_count = 10
+        procedure.failure_count = 2
+
+        ctx = MemoryContext.from_procedural_memory(procedure, query="deploy")
+
+        assert ctx.memory_subtype == MemorySubtype.PROCEDURAL
+        assert ctx.memory_id == str(procedure.id)
+        assert "Deploy to Production" in ctx.content
+        assert "When deploying to production" in ctx.content
+        assert ctx.trigger == "When deploying to production"
+        assert ctx.success_rate == 0.85
+        assert ctx.metadata["steps_count"] == 3
+        assert ctx.metadata["execution_count"] == 12
+
+
+class TestMemoryContextHelpers:
+    """Tests for MemoryContext helper methods."""
+
+    def test_is_working_memory(self) -> None:
+        """is_working_memory should return True for working memory."""
+        ctx = MemoryContext(
+            content="test",
+            source="test",
+            memory_subtype=MemorySubtype.WORKING,
+        )
+        assert ctx.is_working_memory() is True
+        assert ctx.is_episodic_memory() is False
+
+    def test_is_episodic_memory(self) -> None:
+        """is_episodic_memory should return True for episodic memory."""
+        ctx = MemoryContext(
+            content="test",
+            source="test",
+            memory_subtype=MemorySubtype.EPISODIC,
+        )
+        assert ctx.is_episodic_memory() is True
+        assert ctx.is_semantic_memory() is False
+
+    def test_is_semantic_memory(self) -> None:
+        """is_semantic_memory should return True for semantic memory."""
+        ctx = MemoryContext(
+            content="test",
+            source="test",
+            memory_subtype=MemorySubtype.SEMANTIC,
+        )
+        assert ctx.is_semantic_memory() is True
+        assert ctx.is_procedural_memory() is False
+
+    def test_is_procedural_memory(self) -> None:
+        """is_procedural_memory should return True for procedural memory."""
+        ctx = MemoryContext(
+            content="test",
+            source="test",
+            memory_subtype=MemorySubtype.PROCEDURAL,
+        )
+        assert ctx.is_procedural_memory() is True
+        assert ctx.is_working_memory() is False
+
+    def test_get_formatted_source(self) -> None:
+        """get_formatted_source should return formatted string."""
+        ctx = MemoryContext(
+            content="test",
+            source="episodic:12345678-1234-1234-1234-123456789012",
+            memory_subtype=MemorySubtype.EPISODIC,
+            memory_id="12345678-1234-1234-1234-123456789012",
+        )
+
+        formatted = ctx.get_formatted_source()
+
+        assert "[episodic]" in formatted
+        assert "12345678..." in formatted

backend/tests/unit/services/memory/__init__.py

@@ -0,0 +1 @@
+"""Tests for the Agent Memory System."""

backend/tests/unit/services/memory/cache/__init__.py

@@ -0,0 +1,2 @@
+# tests/unit/services/memory/cache/__init__.py
+"""Tests for memory caching layer."""

backend/tests/unit/services/memory/cache/test_cache_manager.py

@@ -0,0 +1,331 @@
+# tests/unit/services/memory/cache/test_cache_manager.py
+"""Tests for CacheManager."""
+
+from unittest.mock import MagicMock, patch
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.cache.cache_manager import (
+    CacheManager,
+    CacheStats,
+    get_cache_manager,
+    reset_cache_manager,
+)
+from app.services.memory.cache.embedding_cache import EmbeddingCache
+from app.services.memory.cache.hot_cache import HotMemoryCache
+
+pytestmark = pytest.mark.asyncio(loop_scope="function")
+
+
+@pytest.fixture(autouse=True)
+def reset_singleton() -> None:
+    """Reset singleton before each test."""
+    reset_cache_manager()
+
+
+class TestCacheStats:
+    """Tests for CacheStats."""
+
+    def test_to_dict(self) -> None:
+        """Should convert to dictionary."""
+        from datetime import UTC, datetime
+
+        stats = CacheStats(
+            hot_cache={"hits": 10},
+            embedding_cache={"hits": 20},
+            overall_hit_rate=0.75,
+            last_cleanup=datetime.now(UTC),
+            cleanup_count=5,
+        )
+
+        result = stats.to_dict()
+
+        assert result["hot_cache"] == {"hits": 10}
+        assert result["overall_hit_rate"] == 0.75
+        assert result["cleanup_count"] == 5
+        assert result["last_cleanup"] is not None
+
+
+class TestCacheManager:
+    """Tests for CacheManager."""
+
+    @pytest.fixture
+    def manager(self) -> CacheManager:
+        """Create a cache manager."""
+        return CacheManager()
+
+    def test_is_enabled(self, manager: CacheManager) -> None:
+        """Should check if caching is enabled."""
+        # Default is enabled from settings
+        assert manager.is_enabled is True
+
+    def test_has_hot_cache(self, manager: CacheManager) -> None:
+        """Should have hot memory cache."""
+        assert manager.hot_cache is not None
+        assert isinstance(manager.hot_cache, HotMemoryCache)
+
+    def test_has_embedding_cache(self, manager: CacheManager) -> None:
+        """Should have embedding cache."""
+        assert manager.embedding_cache is not None
+        assert isinstance(manager.embedding_cache, EmbeddingCache)
+
+    def test_cache_memory(self, manager: CacheManager) -> None:
+        """Should cache memory in hot cache."""
+        memory_id = uuid4()
+        memory = {"task": "test", "data": "value"}
+
+        manager.cache_memory("episodic", memory_id, memory)
+        result = manager.get_memory("episodic", memory_id)
+
+        assert result == memory
+
+    def test_cache_memory_with_scope(self, manager: CacheManager) -> None:
+        """Should cache memory with scope."""
+        memory_id = uuid4()
+        memory = {"task": "test"}
+
+        manager.cache_memory("semantic", memory_id, memory, scope="proj-123")
+        result = manager.get_memory("semantic", memory_id, scope="proj-123")
+
+        assert result == memory
+
+    async def test_cache_embedding(self, manager: CacheManager) -> None:
+        """Should cache embedding."""
+        content = "test content"
+        embedding = [0.1, 0.2, 0.3]
+
+        content_hash = await manager.cache_embedding(content, embedding)
+        result = await manager.get_embedding(content)
+
+        assert result == embedding
+        assert len(content_hash) == 32
+
+    async def test_invalidate_memory(self, manager: CacheManager) -> None:
+        """Should invalidate memory from hot cache."""
+        memory_id = uuid4()
+        manager.cache_memory("episodic", memory_id, {"data": "test"})
+
+        count = await manager.invalidate_memory("episodic", memory_id)
+
+        assert count >= 1
+        assert manager.get_memory("episodic", memory_id) is None
+
+    async def test_invalidate_by_type(self, manager: CacheManager) -> None:
+        """Should invalidate all entries of a type."""
+        manager.cache_memory("episodic", uuid4(), {"data": "1"})
+        manager.cache_memory("episodic", uuid4(), {"data": "2"})
+        manager.cache_memory("semantic", uuid4(), {"data": "3"})
+
+        count = await manager.invalidate_by_type("episodic")
+
+        assert count >= 2
+
+    async def test_invalidate_by_scope(self, manager: CacheManager) -> None:
+        """Should invalidate all entries in a scope."""
+        manager.cache_memory("episodic", uuid4(), {"data": "1"}, scope="proj-1")
+        manager.cache_memory("semantic", uuid4(), {"data": "2"}, scope="proj-1")
+        manager.cache_memory("episodic", uuid4(), {"data": "3"}, scope="proj-2")
+
+        count = await manager.invalidate_by_scope("proj-1")
+
+        assert count >= 2
+
+    async def test_invalidate_embedding(self, manager: CacheManager) -> None:
+        """Should invalidate cached embedding."""
+        content = "test content"
+        await manager.cache_embedding(content, [0.1, 0.2])
+
+        result = await manager.invalidate_embedding(content)
+
+        assert result is True
+        assert await manager.get_embedding(content) is None
+
+    async def test_clear_all(self, manager: CacheManager) -> None:
+        """Should clear all caches."""
+        manager.cache_memory("episodic", uuid4(), {"data": "test"})
+        await manager.cache_embedding("content", [0.1])
+
+        count = await manager.clear_all()
+
+        assert count >= 2
+
+    async def test_cleanup_expired(self, manager: CacheManager) -> None:
+        """Should clean up expired entries."""
+        count = await manager.cleanup_expired()
+
+        # May be 0 if no expired entries
+        assert count >= 0
+        assert manager._cleanup_count == 1
+        assert manager._last_cleanup is not None
+
+    def test_get_stats(self, manager: CacheManager) -> None:
+        """Should return aggregated statistics."""
+        manager.cache_memory("episodic", uuid4(), {"data": "test"})
+
+        stats = manager.get_stats()
+
+        assert "hot_cache" in stats.to_dict()
+        assert "embedding_cache" in stats.to_dict()
+        assert "overall_hit_rate" in stats.to_dict()
+
+    def test_get_hot_memories(self, manager: CacheManager) -> None:
+        """Should return most accessed memories."""
+        id1 = uuid4()
+        id2 = uuid4()
+
+        manager.cache_memory("episodic", id1, {"data": "1"})
+        manager.cache_memory("episodic", id2, {"data": "2"})
+
+        # Access first multiple times
+        for _ in range(5):
+            manager.get_memory("episodic", id1)
+
+        hot = manager.get_hot_memories(limit=2)
+
+        assert len(hot) == 2
+
+    def test_reset_stats(self, manager: CacheManager) -> None:
+        """Should reset all statistics."""
+        manager.cache_memory("episodic", uuid4(), {"data": "test"})
+        manager.get_memory("episodic", uuid4())  # Miss
+
+        manager.reset_stats()
+
+        stats = manager.get_stats()
+        assert stats.hot_cache.get("hits", 0) == 0
+
+    async def test_warmup(self, manager: CacheManager) -> None:
+        """Should warm up cache with memories."""
+        memories = [
+            ("episodic", uuid4(), {"data": "1"}),
+            ("episodic", uuid4(), {"data": "2"}),
+            ("semantic", uuid4(), {"data": "3"}),
+        ]
+
+        count = await manager.warmup(memories)
+
+        assert count == 3
+
+
+class TestCacheManagerWithRetrieval:
+    """Tests for CacheManager with retrieval cache."""
+
+    @pytest.fixture
+    def mock_retrieval_cache(self) -> MagicMock:
+        """Create mock retrieval cache."""
+        cache = MagicMock()
+        cache.invalidate_by_memory = MagicMock(return_value=1)
+        cache.clear = MagicMock(return_value=5)
+        cache.get_stats = MagicMock(return_value={"entries": 10})
+        return cache
+
+    @pytest.fixture
+    def manager_with_retrieval(
+        self,
+        mock_retrieval_cache: MagicMock,
+    ) -> CacheManager:
+        """Create manager with retrieval cache."""
+        manager = CacheManager()
+        manager.set_retrieval_cache(mock_retrieval_cache)
+        return manager
+
+    async def test_invalidate_clears_retrieval(
+        self,
+        manager_with_retrieval: CacheManager,
+        mock_retrieval_cache: MagicMock,
+    ) -> None:
+        """Should invalidate retrieval cache entries."""
+        memory_id = uuid4()
+
+        await manager_with_retrieval.invalidate_memory("episodic", memory_id)
+
+        mock_retrieval_cache.invalidate_by_memory.assert_called_once_with(memory_id)
+
+    def test_stats_includes_retrieval(
+        self,
+        manager_with_retrieval: CacheManager,
+    ) -> None:
+        """Should include retrieval cache stats."""
+        stats = manager_with_retrieval.get_stats()
+
+        assert "retrieval_cache" in stats.to_dict()
+
+
+class TestCacheManagerDisabled:
+    """Tests for CacheManager when disabled."""
+
+    @pytest.fixture
+    def disabled_manager(self) -> CacheManager:
+        """Create a disabled cache manager."""
+        with patch(
+            "app.services.memory.cache.cache_manager.get_memory_settings"
+        ) as mock_settings:
+            settings = MagicMock()
+            settings.cache_enabled = False
+            settings.cache_max_items = 1000
+            settings.cache_ttl_seconds = 300
+            mock_settings.return_value = settings
+
+            return CacheManager()
+
+    def test_get_memory_returns_none(self, disabled_manager: CacheManager) -> None:
+        """Should return None when disabled."""
+        disabled_manager.cache_memory("episodic", uuid4(), {"data": "test"})
+        result = disabled_manager.get_memory("episodic", uuid4())
+
+        assert result is None
+
+    async def test_get_embedding_returns_none(
+        self,
+        disabled_manager: CacheManager,
+    ) -> None:
+        """Should return None for embeddings when disabled."""
+        result = await disabled_manager.get_embedding("content")
+
+        assert result is None
+
+    async def test_warmup_returns_zero(self, disabled_manager: CacheManager) -> None:
+        """Should return 0 from warmup when disabled."""
+        count = await disabled_manager.warmup([("episodic", uuid4(), {})])
+
+        assert count == 0
+
+
+class TestGetCacheManager:
+    """Tests for get_cache_manager factory."""
+
+    def test_returns_singleton(self) -> None:
+        """Should return same instance."""
+        manager1 = get_cache_manager()
+        manager2 = get_cache_manager()
+
+        assert manager1 is manager2
+
+    def test_reset_creates_new(self) -> None:
+        """Should create new instance after reset."""
+        manager1 = get_cache_manager()
+        reset_cache_manager()
+        manager2 = get_cache_manager()
+
+        assert manager1 is not manager2
+
+    def test_reset_parameter(self) -> None:
+        """Should create new instance with reset=True."""
+        manager1 = get_cache_manager()
+        manager2 = get_cache_manager(reset=True)
+
+        assert manager1 is not manager2
+
+
+class TestResetCacheManager:
+    """Tests for reset_cache_manager."""
+
+    def test_resets_singleton(self) -> None:
+        """Should reset the singleton."""
+        get_cache_manager()
+        reset_cache_manager()
+
+        # Next call should create new instance
+        manager = get_cache_manager()
+        assert manager is not None

backend/tests/unit/services/memory/cache/test_embedding_cache.py

@@ -0,0 +1,391 @@
+# tests/unit/services/memory/cache/test_embedding_cache.py
+"""Tests for EmbeddingCache."""
+
+import time
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from app.services.memory.cache.embedding_cache import (
+    CachedEmbeddingGenerator,
+    EmbeddingCache,
+    EmbeddingCacheStats,
+    EmbeddingEntry,
+    create_embedding_cache,
+)
+
+pytestmark = pytest.mark.asyncio(loop_scope="function")
+
+
+class TestEmbeddingEntry:
+    """Tests for EmbeddingEntry."""
+
+    def test_creates_entry(self) -> None:
+        """Should create entry with embedding."""
+        from datetime import UTC, datetime
+
+        entry = EmbeddingEntry(
+            embedding=[0.1, 0.2, 0.3],
+            content_hash="abc123",
+            model="text-embedding-3-small",
+            created_at=datetime.now(UTC),
+        )
+
+        assert entry.embedding == [0.1, 0.2, 0.3]
+        assert entry.content_hash == "abc123"
+        assert entry.ttl_seconds == 3600.0
+
+    def test_is_expired(self) -> None:
+        """Should detect expired entries."""
+        from datetime import UTC, datetime, timedelta
+
+        old_time = datetime.now(UTC) - timedelta(seconds=4000)
+        entry = EmbeddingEntry(
+            embedding=[0.1],
+            content_hash="abc",
+            model="default",
+            created_at=old_time,
+            ttl_seconds=3600.0,
+        )
+
+        assert entry.is_expired() is True
+
+    def test_not_expired(self) -> None:
+        """Should detect non-expired entries."""
+        from datetime import UTC, datetime
+
+        entry = EmbeddingEntry(
+            embedding=[0.1],
+            content_hash="abc",
+            model="default",
+            created_at=datetime.now(UTC),
+        )
+
+        assert entry.is_expired() is False
+
+
+class TestEmbeddingCacheStats:
+    """Tests for EmbeddingCacheStats."""
+
+    def test_hit_rate_calculation(self) -> None:
+        """Should calculate hit rate correctly."""
+        stats = EmbeddingCacheStats(hits=90, misses=10)
+
+        assert stats.hit_rate == 0.9
+
+    def test_hit_rate_zero_requests(self) -> None:
+        """Should return 0 for no requests."""
+        stats = EmbeddingCacheStats()
+
+        assert stats.hit_rate == 0.0
+
+    def test_to_dict(self) -> None:
+        """Should convert to dictionary."""
+        stats = EmbeddingCacheStats(hits=10, misses=5, bytes_saved=1000)
+
+        result = stats.to_dict()
+
+        assert result["hits"] == 10
+        assert result["bytes_saved"] == 1000
+
+
+class TestEmbeddingCache:
+    """Tests for EmbeddingCache."""
+
+    @pytest.fixture
+    def cache(self) -> EmbeddingCache:
+        """Create an embedding cache."""
+        return EmbeddingCache(max_size=100, default_ttl_seconds=300.0)
+
+    async def test_put_and_get(self, cache: EmbeddingCache) -> None:
+        """Should store and retrieve embeddings."""
+        content = "Hello world"
+        embedding = [0.1, 0.2, 0.3, 0.4]
+
+        content_hash = await cache.put(content, embedding)
+        result = await cache.get(content)
+
+        assert result == embedding
+        assert len(content_hash) == 32
+
+    async def test_get_missing(self, cache: EmbeddingCache) -> None:
+        """Should return None for missing content."""
+        result = await cache.get("nonexistent content")
+
+        assert result is None
+
+    async def test_get_by_hash(self, cache: EmbeddingCache) -> None:
+        """Should get by content hash."""
+        content = "Test content"
+        embedding = [0.1, 0.2]
+
+        content_hash = await cache.put(content, embedding)
+        result = await cache.get_by_hash(content_hash)
+
+        assert result == embedding
+
+    async def test_model_separation(self, cache: EmbeddingCache) -> None:
+        """Should separate embeddings by model."""
+        content = "Same content"
+        emb1 = [0.1, 0.2]
+        emb2 = [0.3, 0.4]
+
+        await cache.put(content, emb1, model="model-a")
+        await cache.put(content, emb2, model="model-b")
+
+        result1 = await cache.get(content, model="model-a")
+        result2 = await cache.get(content, model="model-b")
+
+        assert result1 == emb1
+        assert result2 == emb2
+
+    async def test_lru_eviction(self) -> None:
+        """Should evict LRU entries when at capacity."""
+        cache = EmbeddingCache(max_size=3)
+
+        await cache.put("content1", [0.1])
+        await cache.put("content2", [0.2])
+        await cache.put("content3", [0.3])
+
+        # Access first to make it recent
+        await cache.get("content1")
+
+        # Add fourth, should evict second (LRU)
+        await cache.put("content4", [0.4])
+
+        assert await cache.get("content1") is not None
+        assert await cache.get("content2") is None  # Evicted
+        assert await cache.get("content3") is not None
+        assert await cache.get("content4") is not None
+
+    async def test_ttl_expiration(self) -> None:
+        """Should expire entries after TTL."""
+        cache = EmbeddingCache(max_size=100, default_ttl_seconds=0.1)
+
+        await cache.put("content", [0.1, 0.2])
+
+        time.sleep(0.2)
+
+        result = await cache.get("content")
+
+        assert result is None
+
+    async def test_put_batch(self, cache: EmbeddingCache) -> None:
+        """Should cache multiple embeddings."""
+        items = [
+            ("content1", [0.1]),
+            ("content2", [0.2]),
+            ("content3", [0.3]),
+        ]
+
+        hashes = await cache.put_batch(items)
+
+        assert len(hashes) == 3
+        assert await cache.get("content1") == [0.1]
+        assert await cache.get("content2") == [0.2]
+
+    async def test_invalidate(self, cache: EmbeddingCache) -> None:
+        """Should invalidate cached embedding."""
+        await cache.put("content", [0.1, 0.2])
+
+        result = await cache.invalidate("content")
+
+        assert result is True
+        assert await cache.get("content") is None
+
+    async def test_invalidate_by_hash(self, cache: EmbeddingCache) -> None:
+        """Should invalidate by hash."""
+        content_hash = await cache.put("content", [0.1, 0.2])
+
+        result = await cache.invalidate_by_hash(content_hash)
+
+        assert result is True
+        assert await cache.get("content") is None
+
+    async def test_invalidate_by_model(self, cache: EmbeddingCache) -> None:
+        """Should invalidate all embeddings for a model."""
+        await cache.put("content1", [0.1], model="model-a")
+        await cache.put("content2", [0.2], model="model-a")
+        await cache.put("content3", [0.3], model="model-b")
+
+        count = await cache.invalidate_by_model("model-a")
+
+        assert count == 2
+        assert await cache.get("content1", model="model-a") is None
+        assert await cache.get("content3", model="model-b") is not None
+
+    async def test_clear(self, cache: EmbeddingCache) -> None:
+        """Should clear all entries."""
+        await cache.put("content1", [0.1])
+        await cache.put("content2", [0.2])
+
+        count = await cache.clear()
+
+        assert count == 2
+        assert cache.size == 0
+
+    def test_cleanup_expired(self) -> None:
+        """Should remove expired entries."""
+        cache = EmbeddingCache(max_size=100, default_ttl_seconds=0.1)
+
+        # Use synchronous put for setup
+        cache._put_memory("hash1", "default", [0.1])
+        cache._put_memory("hash2", "default", [0.2], ttl_seconds=10)
+
+        time.sleep(0.2)
+
+        count = cache.cleanup_expired()
+
+        assert count == 1
+
+    def test_get_stats(self, cache: EmbeddingCache) -> None:
+        """Should return accurate statistics."""
+        # Put synchronously for setup
+        cache._put_memory("hash1", "default", [0.1])
+
+        stats = cache.get_stats()
+
+        assert stats.current_size == 1
+
+    def test_hash_content(self) -> None:
+        """Should produce consistent hashes."""
+        hash1 = EmbeddingCache.hash_content("test content")
+        hash2 = EmbeddingCache.hash_content("test content")
+        hash3 = EmbeddingCache.hash_content("different content")
+
+        assert hash1 == hash2
+        assert hash1 != hash3
+        assert len(hash1) == 32
+
+
+class TestEmbeddingCacheWithRedis:
+    """Tests for EmbeddingCache with Redis."""
+
+    @pytest.fixture
+    def mock_redis(self) -> MagicMock:
+        """Create mock Redis."""
+        redis = MagicMock()
+        redis.get = AsyncMock(return_value=None)
+        redis.setex = AsyncMock()
+        redis.delete = AsyncMock()
+        redis.scan_iter = MagicMock(return_value=iter([]))
+        return redis
+
+    @pytest.fixture
+    def cache_with_redis(self, mock_redis: MagicMock) -> EmbeddingCache:
+        """Create cache with mock Redis."""
+        return EmbeddingCache(
+            max_size=100,
+            default_ttl_seconds=300.0,
+            redis=mock_redis,
+        )
+
+    async def test_put_stores_in_redis(
+        self,
+        cache_with_redis: EmbeddingCache,
+        mock_redis: MagicMock,
+    ) -> None:
+        """Should store in Redis when available."""
+        await cache_with_redis.put("content", [0.1, 0.2])
+
+        mock_redis.setex.assert_called_once()
+
+    async def test_get_checks_redis_on_miss(
+        self,
+        cache_with_redis: EmbeddingCache,
+        mock_redis: MagicMock,
+    ) -> None:
+        """Should check Redis when memory cache misses."""
+        import json
+
+        mock_redis.get.return_value = json.dumps([0.1, 0.2])
+
+        result = await cache_with_redis.get("content")
+
+        assert result == [0.1, 0.2]
+        mock_redis.get.assert_called_once()
+
+
+class TestCachedEmbeddingGenerator:
+    """Tests for CachedEmbeddingGenerator."""
+
+    @pytest.fixture
+    def mock_generator(self) -> MagicMock:
+        """Create mock embedding generator."""
+        gen = MagicMock()
+        gen.generate = AsyncMock(return_value=[0.1, 0.2, 0.3])
+        gen.generate_batch = AsyncMock(return_value=[[0.1], [0.2], [0.3]])
+        return gen
+
+    @pytest.fixture
+    def cache(self) -> EmbeddingCache:
+        """Create embedding cache."""
+        return EmbeddingCache(max_size=100)
+
+    @pytest.fixture
+    def cached_gen(
+        self,
+        mock_generator: MagicMock,
+        cache: EmbeddingCache,
+    ) -> CachedEmbeddingGenerator:
+        """Create cached generator."""
+        return CachedEmbeddingGenerator(mock_generator, cache)
+
+    async def test_generate_caches_result(
+        self,
+        cached_gen: CachedEmbeddingGenerator,
+        mock_generator: MagicMock,
+    ) -> None:
+        """Should cache generated embedding."""
+        result1 = await cached_gen.generate("test text")
+        result2 = await cached_gen.generate("test text")
+
+        assert result1 == [0.1, 0.2, 0.3]
+        assert result2 == [0.1, 0.2, 0.3]
+        mock_generator.generate.assert_called_once()  # Only called once
+
+    async def test_generate_batch_uses_cache(
+        self,
+        cached_gen: CachedEmbeddingGenerator,
+        mock_generator: MagicMock,
+        cache: EmbeddingCache,
+    ) -> None:
+        """Should use cache for batch generation."""
+        # Pre-cache one embedding
+        await cache.put("text1", [0.5])
+
+        # Mock returns 2 embeddings for the 2 uncached texts
+        mock_generator.generate_batch = AsyncMock(return_value=[[0.2], [0.3]])
+
+        results = await cached_gen.generate_batch(["text1", "text2", "text3"])
+
+        assert len(results) == 3
+        assert results[0] == [0.5]  # From cache
+        assert results[1] == [0.2]  # Generated
+        assert results[2] == [0.3]  # Generated
+
+    async def test_get_stats(self, cached_gen: CachedEmbeddingGenerator) -> None:
+        """Should return generator statistics."""
+        await cached_gen.generate("text1")
+        await cached_gen.generate("text1")  # Cache hit
+
+        stats = cached_gen.get_stats()
+
+        assert stats["call_count"] == 2
+        assert stats["cache_hit_count"] == 1
+
+
+class TestCreateEmbeddingCache:
+    """Tests for factory function."""
+
+    def test_creates_cache(self) -> None:
+        """Should create cache with defaults."""
+        cache = create_embedding_cache()
+
+        assert cache.max_size == 50000
+
+    def test_creates_cache_with_options(self) -> None:
+        """Should create cache with custom options."""
+        cache = create_embedding_cache(max_size=1000, default_ttl_seconds=600.0)
+
+        assert cache.max_size == 1000

backend/tests/unit/services/memory/cache/test_hot_cache.py

@@ -0,0 +1,355 @@
+# tests/unit/services/memory/cache/test_hot_cache.py
+"""Tests for HotMemoryCache."""
+
+import time
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.cache.hot_cache import (
+    CacheEntry,
+    CacheKey,
+    HotCacheStats,
+    HotMemoryCache,
+    create_hot_cache,
+)
+
+
+class TestCacheKey:
+    """Tests for CacheKey."""
+
+    def test_creates_key(self) -> None:
+        """Should create key with required fields."""
+        key = CacheKey(memory_type="episodic", memory_id="123")
+
+        assert key.memory_type == "episodic"
+        assert key.memory_id == "123"
+        assert key.scope is None
+
+    def test_creates_key_with_scope(self) -> None:
+        """Should create key with scope."""
+        key = CacheKey(memory_type="semantic", memory_id="456", scope="proj-123")
+
+        assert key.scope == "proj-123"
+
+    def test_hash_and_equality(self) -> None:
+        """Keys with same values should be equal and have same hash."""
+        key1 = CacheKey(memory_type="episodic", memory_id="123", scope="proj-1")
+        key2 = CacheKey(memory_type="episodic", memory_id="123", scope="proj-1")
+
+        assert key1 == key2
+        assert hash(key1) == hash(key2)
+
+    def test_str_representation(self) -> None:
+        """Should produce readable string."""
+        key = CacheKey(memory_type="episodic", memory_id="123", scope="proj-1")
+
+        assert str(key) == "episodic:proj-1:123"
+
+    def test_str_without_scope(self) -> None:
+        """Should produce string without scope."""
+        key = CacheKey(memory_type="episodic", memory_id="123")
+
+        assert str(key) == "episodic:123"
+
+
+class TestCacheEntry:
+    """Tests for CacheEntry."""
+
+    def test_creates_entry(self) -> None:
+        """Should create entry with value."""
+        entry = CacheEntry(
+            value={"data": "test"},
+            created_at=pytest.importorskip("datetime").datetime.now(
+                pytest.importorskip("datetime").UTC
+            ),
+            last_accessed_at=pytest.importorskip("datetime").datetime.now(
+                pytest.importorskip("datetime").UTC
+            ),
+        )
+
+        assert entry.value == {"data": "test"}
+        assert entry.access_count == 1
+        assert entry.ttl_seconds == 300.0
+
+    def test_is_expired(self) -> None:
+        """Should detect expired entries."""
+        from datetime import UTC, datetime, timedelta
+
+        old_time = datetime.now(UTC) - timedelta(seconds=400)
+        entry = CacheEntry(
+            value="test",
+            created_at=old_time,
+            last_accessed_at=old_time,
+            ttl_seconds=300.0,
+        )
+
+        assert entry.is_expired() is True
+
+    def test_not_expired(self) -> None:
+        """Should detect non-expired entries."""
+        from datetime import UTC, datetime
+
+        entry = CacheEntry(
+            value="test",
+            created_at=datetime.now(UTC),
+            last_accessed_at=datetime.now(UTC),
+            ttl_seconds=300.0,
+        )
+
+        assert entry.is_expired() is False
+
+    def test_touch_updates_access(self) -> None:
+        """Touch should update access time and count."""
+        from datetime import UTC, datetime, timedelta
+
+        old_time = datetime.now(UTC) - timedelta(seconds=10)
+        entry = CacheEntry(
+            value="test",
+            created_at=old_time,
+            last_accessed_at=old_time,
+            access_count=5,
+        )
+
+        entry.touch()
+
+        assert entry.access_count == 6
+        assert entry.last_accessed_at > old_time
+
+
+class TestHotCacheStats:
+    """Tests for HotCacheStats."""
+
+    def test_hit_rate_calculation(self) -> None:
+        """Should calculate hit rate correctly."""
+        stats = HotCacheStats(hits=80, misses=20)
+
+        assert stats.hit_rate == 0.8
+
+    def test_hit_rate_zero_requests(self) -> None:
+        """Should return 0 for no requests."""
+        stats = HotCacheStats()
+
+        assert stats.hit_rate == 0.0
+
+    def test_to_dict(self) -> None:
+        """Should convert to dictionary."""
+        stats = HotCacheStats(hits=10, misses=5, evictions=2)
+
+        result = stats.to_dict()
+
+        assert result["hits"] == 10
+        assert result["misses"] == 5
+        assert result["evictions"] == 2
+        assert "hit_rate" in result
+
+
+class TestHotMemoryCache:
+    """Tests for HotMemoryCache."""
+
+    @pytest.fixture
+    def cache(self) -> HotMemoryCache[dict]:
+        """Create a hot memory cache."""
+        return HotMemoryCache[dict](max_size=100, default_ttl_seconds=300.0)
+
+    def test_put_and_get(self, cache: HotMemoryCache[dict]) -> None:
+        """Should store and retrieve values."""
+        key = CacheKey(memory_type="episodic", memory_id="123")
+        value = {"data": "test"}
+
+        cache.put(key, value)
+        result = cache.get(key)
+
+        assert result == value
+
+    def test_get_missing_key(self, cache: HotMemoryCache[dict]) -> None:
+        """Should return None for missing keys."""
+        key = CacheKey(memory_type="episodic", memory_id="nonexistent")
+
+        result = cache.get(key)
+
+        assert result is None
+
+    def test_put_by_id(self, cache: HotMemoryCache[dict]) -> None:
+        """Should store by type and ID."""
+        memory_id = uuid4()
+        value = {"data": "test"}
+
+        cache.put_by_id("episodic", memory_id, value)
+        result = cache.get_by_id("episodic", memory_id)
+
+        assert result == value
+
+    def test_put_by_id_with_scope(self, cache: HotMemoryCache[dict]) -> None:
+        """Should store with scope."""
+        memory_id = uuid4()
+        value = {"data": "test"}
+
+        cache.put_by_id("semantic", memory_id, value, scope="proj-123")
+        result = cache.get_by_id("semantic", memory_id, scope="proj-123")
+
+        assert result == value
+
+    def test_lru_eviction(self) -> None:
+        """Should evict LRU entries when at capacity."""
+        cache = HotMemoryCache[str](max_size=3)
+
+        # Fill cache
+        cache.put_by_id("test", "1", "first")
+        cache.put_by_id("test", "2", "second")
+        cache.put_by_id("test", "3", "third")
+
+        # Access first to make it recent
+        cache.get_by_id("test", "1")
+
+        # Add fourth, should evict second (LRU)
+        cache.put_by_id("test", "4", "fourth")
+
+        assert cache.get_by_id("test", "1") is not None  # Accessed, kept
+        assert cache.get_by_id("test", "2") is None  # Evicted (LRU)
+        assert cache.get_by_id("test", "3") is not None
+        assert cache.get_by_id("test", "4") is not None
+
+    def test_ttl_expiration(self) -> None:
+        """Should expire entries after TTL."""
+        cache = HotMemoryCache[str](max_size=100, default_ttl_seconds=0.1)
+
+        cache.put_by_id("test", "1", "value")
+
+        # Wait for expiration
+        time.sleep(0.2)
+
+        result = cache.get_by_id("test", "1")
+
+        assert result is None
+
+    def test_invalidate(self, cache: HotMemoryCache[dict]) -> None:
+        """Should invalidate specific entry."""
+        key = CacheKey(memory_type="episodic", memory_id="123")
+        cache.put(key, {"data": "test"})
+
+        result = cache.invalidate(key)
+
+        assert result is True
+        assert cache.get(key) is None
+
+    def test_invalidate_by_id(self, cache: HotMemoryCache[dict]) -> None:
+        """Should invalidate by ID."""
+        memory_id = uuid4()
+        cache.put_by_id("episodic", memory_id, {"data": "test"})
+
+        result = cache.invalidate_by_id("episodic", memory_id)
+
+        assert result is True
+        assert cache.get_by_id("episodic", memory_id) is None
+
+    def test_invalidate_by_type(self, cache: HotMemoryCache[dict]) -> None:
+        """Should invalidate all entries of a type."""
+        cache.put_by_id("episodic", "1", {"data": "1"})
+        cache.put_by_id("episodic", "2", {"data": "2"})
+        cache.put_by_id("semantic", "3", {"data": "3"})
+
+        count = cache.invalidate_by_type("episodic")
+
+        assert count == 2
+        assert cache.get_by_id("episodic", "1") is None
+        assert cache.get_by_id("episodic", "2") is None
+        assert cache.get_by_id("semantic", "3") is not None
+
+    def test_invalidate_by_scope(self, cache: HotMemoryCache[dict]) -> None:
+        """Should invalidate all entries in a scope."""
+        cache.put_by_id("episodic", "1", {"data": "1"}, scope="proj-1")
+        cache.put_by_id("semantic", "2", {"data": "2"}, scope="proj-1")
+        cache.put_by_id("episodic", "3", {"data": "3"}, scope="proj-2")
+
+        count = cache.invalidate_by_scope("proj-1")
+
+        assert count == 2
+        assert cache.get_by_id("episodic", "3", scope="proj-2") is not None
+
+    def test_invalidate_pattern(self, cache: HotMemoryCache[dict]) -> None:
+        """Should invalidate entries matching pattern."""
+        cache.put_by_id("episodic", "123", {"data": "1"})
+        cache.put_by_id("episodic", "124", {"data": "2"})
+        cache.put_by_id("semantic", "125", {"data": "3"})
+
+        count = cache.invalidate_pattern("episodic:*")
+
+        assert count == 2
+
+    def test_clear(self, cache: HotMemoryCache[dict]) -> None:
+        """Should clear all entries."""
+        cache.put_by_id("episodic", "1", {"data": "1"})
+        cache.put_by_id("semantic", "2", {"data": "2"})
+
+        count = cache.clear()
+
+        assert count == 2
+        assert cache.size == 0
+
+    def test_cleanup_expired(self) -> None:
+        """Should remove expired entries."""
+        cache = HotMemoryCache[str](max_size=100, default_ttl_seconds=0.1)
+
+        cache.put_by_id("test", "1", "value1")
+        cache.put_by_id("test", "2", "value2", ttl_seconds=10)
+
+        time.sleep(0.2)
+
+        count = cache.cleanup_expired()
+
+        assert count == 1  # Only the first one expired
+        assert cache.size == 1
+
+    def test_get_hot_memories(self, cache: HotMemoryCache[dict]) -> None:
+        """Should return most accessed memories."""
+        cache.put_by_id("episodic", "1", {"data": "1"})
+        cache.put_by_id("episodic", "2", {"data": "2"})
+
+        # Access first one multiple times
+        for _ in range(5):
+            cache.get_by_id("episodic", "1")
+
+        hot = cache.get_hot_memories(limit=2)
+
+        assert len(hot) == 2
+        assert hot[0][1] >= hot[1][1]  # Sorted by access count
+
+    def test_get_stats(self, cache: HotMemoryCache[dict]) -> None:
+        """Should return accurate statistics."""
+        cache.put_by_id("episodic", "1", {"data": "1"})
+        cache.get_by_id("episodic", "1")  # Hit
+        cache.get_by_id("episodic", "2")  # Miss
+
+        stats = cache.get_stats()
+
+        assert stats.hits == 1
+        assert stats.misses == 1
+        assert stats.current_size == 1
+
+    def test_reset_stats(self, cache: HotMemoryCache[dict]) -> None:
+        """Should reset statistics."""
+        cache.put_by_id("episodic", "1", {"data": "1"})
+        cache.get_by_id("episodic", "1")
+
+        cache.reset_stats()
+        stats = cache.get_stats()
+
+        assert stats.hits == 0
+        assert stats.misses == 0
+
+
+class TestCreateHotCache:
+    """Tests for factory function."""
+
+    def test_creates_cache(self) -> None:
+        """Should create cache with defaults."""
+        cache = create_hot_cache()
+
+        assert cache.max_size == 10000
+
+    def test_creates_cache_with_options(self) -> None:
+        """Should create cache with custom options."""
+        cache = create_hot_cache(max_size=500, default_ttl_seconds=60.0)
+
+        assert cache.max_size == 500

backend/tests/unit/services/memory/consolidation/__init__.py

@@ -0,0 +1,2 @@
+# tests/unit/services/memory/consolidation/__init__.py
+"""Tests for memory consolidation."""

backend/tests/unit/services/memory/consolidation/test_service.py

@@ -0,0 +1,736 @@
+# tests/unit/services/memory/consolidation/test_service.py
+"""Unit tests for memory consolidation service."""
+
+from datetime import UTC, datetime, timedelta
+from unittest.mock import AsyncMock, MagicMock, patch
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.consolidation.service import (
+    ConsolidationConfig,
+    ConsolidationResult,
+    MemoryConsolidationService,
+    NightlyConsolidationResult,
+    SessionConsolidationResult,
+)
+from app.services.memory.types import Episode, Outcome, TaskState
+
+
+def _utcnow() -> datetime:
+    """Get current UTC time."""
+    return datetime.now(UTC)
+
+
+def make_episode(
+    outcome: Outcome = Outcome.SUCCESS,
+    occurred_at: datetime | None = None,
+    task_type: str = "test_task",
+    lessons_learned: list[str] | None = None,
+    importance_score: float = 0.5,
+    actions: list[dict] | None = None,
+) -> Episode:
+    """Create a test episode."""
+    return Episode(
+        id=uuid4(),
+        project_id=uuid4(),
+        agent_instance_id=uuid4(),
+        agent_type_id=uuid4(),
+        session_id="test-session",
+        task_type=task_type,
+        task_description="Test task description",
+        actions=actions or [{"action": "test"}],
+        context_summary="Test context",
+        outcome=outcome,
+        outcome_details="Test outcome",
+        duration_seconds=10.0,
+        tokens_used=100,
+        lessons_learned=lessons_learned or [],
+        importance_score=importance_score,
+        embedding=None,
+        occurred_at=occurred_at or _utcnow(),
+        created_at=_utcnow(),
+        updated_at=_utcnow(),
+    )
+
+
+def make_task_state(
+    current_step: int = 5,
+    total_steps: int = 10,
+    progress_percent: float = 50.0,
+    status: str = "in_progress",
+    description: str = "Test Task",
+) -> TaskState:
+    """Create a test task state."""
+    now = _utcnow()
+    return TaskState(
+        task_id="test-task-id",
+        task_type="test_task",
+        description=description,
+        current_step=current_step,
+        total_steps=total_steps,
+        status=status,
+        progress_percent=progress_percent,
+        started_at=now - timedelta(hours=1),
+        updated_at=now,
+    )
+
+
+class TestConsolidationConfig:
+    """Tests for ConsolidationConfig."""
+
+    def test_default_values(self) -> None:
+        """Test default configuration values."""
+        config = ConsolidationConfig()
+
+        assert config.min_steps_for_episode == 2
+        assert config.min_duration_seconds == 5.0
+        assert config.min_confidence_for_fact == 0.6
+        assert config.max_facts_per_episode == 10
+        assert config.min_episodes_for_procedure == 3
+        assert config.max_episode_age_days == 90
+        assert config.batch_size == 100
+
+    def test_custom_values(self) -> None:
+        """Test custom configuration values."""
+        config = ConsolidationConfig(
+            min_steps_for_episode=5,
+            batch_size=50,
+        )
+
+        assert config.min_steps_for_episode == 5
+        assert config.batch_size == 50
+
+
+class TestConsolidationResult:
+    """Tests for ConsolidationResult."""
+
+    def test_creation(self) -> None:
+        """Test creating a consolidation result."""
+        result = ConsolidationResult(
+            source_type="episodic",
+            target_type="semantic",
+            items_processed=10,
+            items_created=5,
+        )
+
+        assert result.source_type == "episodic"
+        assert result.target_type == "semantic"
+        assert result.items_processed == 10
+        assert result.items_created == 5
+        assert result.items_skipped == 0
+        assert result.errors == []
+
+    def test_to_dict(self) -> None:
+        """Test converting to dictionary."""
+        result = ConsolidationResult(
+            source_type="episodic",
+            target_type="semantic",
+            items_processed=10,
+            items_created=5,
+            errors=["test error"],
+        )
+
+        d = result.to_dict()
+
+        assert d["source_type"] == "episodic"
+        assert d["target_type"] == "semantic"
+        assert d["items_processed"] == 10
+        assert d["items_created"] == 5
+        assert "test error" in d["errors"]
+
+
+class TestSessionConsolidationResult:
+    """Tests for SessionConsolidationResult."""
+
+    def test_creation(self) -> None:
+        """Test creating a session consolidation result."""
+        result = SessionConsolidationResult(
+            session_id="test-session",
+            episode_created=True,
+            episode_id=uuid4(),
+            scratchpad_entries=5,
+        )
+
+        assert result.session_id == "test-session"
+        assert result.episode_created is True
+        assert result.episode_id is not None
+
+
+class TestNightlyConsolidationResult:
+    """Tests for NightlyConsolidationResult."""
+
+    def test_creation(self) -> None:
+        """Test creating a nightly consolidation result."""
+        result = NightlyConsolidationResult(
+            started_at=_utcnow(),
+        )
+
+        assert result.started_at is not None
+        assert result.completed_at is None
+        assert result.total_episodes_processed == 0
+
+    def test_to_dict(self) -> None:
+        """Test converting to dictionary."""
+        result = NightlyConsolidationResult(
+            started_at=_utcnow(),
+            completed_at=_utcnow(),
+            total_facts_created=5,
+            total_procedures_created=2,
+        )
+
+        d = result.to_dict()
+
+        assert "started_at" in d
+        assert "completed_at" in d
+        assert d["total_facts_created"] == 5
+        assert d["total_procedures_created"] == 2
+
+
+class TestMemoryConsolidationService:
+    """Tests for MemoryConsolidationService."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        return AsyncMock()
+
+    @pytest.fixture
+    def service(self, mock_session: AsyncMock) -> MemoryConsolidationService:
+        """Create a consolidation service with mocked dependencies."""
+        return MemoryConsolidationService(
+            session=mock_session,
+            config=ConsolidationConfig(),
+        )
+
+    # =========================================================================
+    # Session Consolidation Tests
+    # =========================================================================
+
+    @pytest.mark.asyncio
+    async def test_consolidate_session_insufficient_steps(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test session not consolidated when insufficient steps."""
+        mock_working_memory = AsyncMock()
+        task_state = make_task_state(current_step=1)  # Less than min_steps_for_episode
+        mock_working_memory.get_task_state.return_value = task_state
+
+        result = await service.consolidate_session(
+            working_memory=mock_working_memory,
+            project_id=uuid4(),
+            session_id="test-session",
+        )
+
+        assert result.episode_created is False
+        assert result.episode_id is None
+
+    @pytest.mark.asyncio
+    async def test_consolidate_session_no_task_state(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test session not consolidated when no task state."""
+        mock_working_memory = AsyncMock()
+        mock_working_memory.get_task_state.return_value = None
+
+        result = await service.consolidate_session(
+            working_memory=mock_working_memory,
+            project_id=uuid4(),
+            session_id="test-session",
+        )
+
+        assert result.episode_created is False
+
+    @pytest.mark.asyncio
+    async def test_consolidate_session_success(
+        self, service: MemoryConsolidationService, mock_session: AsyncMock
+    ) -> None:
+        """Test successful session consolidation."""
+        mock_working_memory = AsyncMock()
+        task_state = make_task_state(
+            current_step=5,
+            progress_percent=100.0,
+            status="complete",
+        )
+        mock_working_memory.get_task_state.return_value = task_state
+        mock_working_memory.get_scratchpad.return_value = ["step1", "step2"]
+        mock_working_memory.get_all.return_value = {"key1": "value1"}
+
+        # Mock episodic memory
+        mock_episode = make_episode()
+        with patch.object(
+            service, "_get_episodic", new_callable=AsyncMock
+        ) as mock_get_episodic:
+            mock_episodic = AsyncMock()
+            mock_episodic.record_episode.return_value = mock_episode
+            mock_get_episodic.return_value = mock_episodic
+
+            result = await service.consolidate_session(
+                working_memory=mock_working_memory,
+                project_id=uuid4(),
+                session_id="test-session",
+            )
+
+        assert result.episode_created is True
+        assert result.episode_id == mock_episode.id
+        assert result.scratchpad_entries == 2
+
+    # =========================================================================
+    # Outcome Determination Tests
+    # =========================================================================
+
+    def test_determine_session_outcome_success(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test outcome determination for successful session."""
+        task_state = make_task_state(status="complete", progress_percent=100.0)
+        outcome = service._determine_session_outcome(task_state)
+        assert outcome == Outcome.SUCCESS
+
+    def test_determine_session_outcome_failure(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test outcome determination for failed session."""
+        task_state = make_task_state(status="error", progress_percent=25.0)
+        outcome = service._determine_session_outcome(task_state)
+        assert outcome == Outcome.FAILURE
+
+    def test_determine_session_outcome_partial(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test outcome determination for partial session."""
+        task_state = make_task_state(status="stopped", progress_percent=60.0)
+        outcome = service._determine_session_outcome(task_state)
+        assert outcome == Outcome.PARTIAL
+
+    def test_determine_session_outcome_none(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test outcome determination with no task state."""
+        outcome = service._determine_session_outcome(None)
+        assert outcome == Outcome.PARTIAL
+
+    # =========================================================================
+    # Action Building Tests
+    # =========================================================================
+
+    def test_build_actions_from_session(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test building actions from session data."""
+        scratchpad = ["thought 1", "thought 2"]
+        variables = {"var1": "value1"}
+        task_state = make_task_state()
+
+        actions = service._build_actions_from_session(scratchpad, variables, task_state)
+
+        assert len(actions) == 3  # 2 scratchpad + 1 final state
+        assert actions[0]["type"] == "reasoning"
+        assert actions[2]["type"] == "final_state"
+
+    def test_build_context_summary(self, service: MemoryConsolidationService) -> None:
+        """Test building context summary."""
+        task_state = make_task_state(
+            description="Test Task",
+            progress_percent=75.0,
+        )
+        variables = {"key": "value"}
+
+        summary = service._build_context_summary(task_state, variables)
+
+        assert "Test Task" in summary
+        assert "75.0%" in summary
+
+    # =========================================================================
+    # Importance Calculation Tests
+    # =========================================================================
+
+    def test_calculate_session_importance_base(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test base importance calculation."""
+        task_state = make_task_state(total_steps=3)  # Below threshold
+        importance = service._calculate_session_importance(
+            task_state, Outcome.SUCCESS, []
+        )
+
+        assert importance == 0.5  # Base score
+
+    def test_calculate_session_importance_failure(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test importance boost for failures."""
+        task_state = make_task_state(total_steps=3)  # Below threshold
+        importance = service._calculate_session_importance(
+            task_state, Outcome.FAILURE, []
+        )
+
+        assert importance == 0.8  # Base (0.5) + failure boost (0.3)
+
+    def test_calculate_session_importance_complex(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test importance for complex session."""
+        task_state = make_task_state(total_steps=10)
+        actions = [{"step": i} for i in range(6)]
+        importance = service._calculate_session_importance(
+            task_state, Outcome.SUCCESS, actions
+        )
+
+        # Base (0.5) + many steps (0.1) + many actions (0.1)
+        assert importance == 0.7
+
+    # =========================================================================
+    # Episode to Fact Consolidation Tests
+    # =========================================================================
+
+    @pytest.mark.asyncio
+    async def test_consolidate_episodes_to_facts_empty(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test consolidation with no episodes."""
+        with patch.object(
+            service, "_get_episodic", new_callable=AsyncMock
+        ) as mock_get_episodic:
+            mock_episodic = AsyncMock()
+            mock_episodic.get_recent.return_value = []
+            mock_get_episodic.return_value = mock_episodic
+
+            result = await service.consolidate_episodes_to_facts(
+                project_id=uuid4(),
+            )
+
+        assert result.items_processed == 0
+        assert result.items_created == 0
+
+    @pytest.mark.asyncio
+    async def test_consolidate_episodes_to_facts_success(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test successful fact extraction."""
+        episode = make_episode(
+            lessons_learned=["Always check return values"],
+        )
+
+        mock_fact = MagicMock()
+        mock_fact.reinforcement_count = 1  # New fact
+
+        with (
+            patch.object(
+                service, "_get_episodic", new_callable=AsyncMock
+            ) as mock_get_episodic,
+            patch.object(
+                service, "_get_semantic", new_callable=AsyncMock
+            ) as mock_get_semantic,
+        ):
+            mock_episodic = AsyncMock()
+            mock_episodic.get_recent.return_value = [episode]
+            mock_get_episodic.return_value = mock_episodic
+
+            mock_semantic = AsyncMock()
+            mock_semantic.store_fact.return_value = mock_fact
+            mock_get_semantic.return_value = mock_semantic
+
+            result = await service.consolidate_episodes_to_facts(
+                project_id=uuid4(),
+            )
+
+        assert result.items_processed == 1
+        # At least one fact should be created from lesson
+        assert result.items_created >= 0
+
+    # =========================================================================
+    # Episode to Procedure Consolidation Tests
+    # =========================================================================
+
+    @pytest.mark.asyncio
+    async def test_consolidate_episodes_to_procedures_insufficient(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test consolidation with insufficient episodes."""
+        # Only 1 episode - less than min_episodes_for_procedure (3)
+        episode = make_episode()
+
+        with patch.object(
+            service, "_get_episodic", new_callable=AsyncMock
+        ) as mock_get_episodic:
+            mock_episodic = AsyncMock()
+            mock_episodic.get_by_outcome.return_value = [episode]
+            mock_get_episodic.return_value = mock_episodic
+
+            result = await service.consolidate_episodes_to_procedures(
+                project_id=uuid4(),
+            )
+
+        assert result.items_processed == 1
+        assert result.items_created == 0
+        assert result.items_skipped == 1
+
+    @pytest.mark.asyncio
+    async def test_consolidate_episodes_to_procedures_success(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test successful procedure creation."""
+        # Create enough episodes for a procedure
+        episodes = [
+            make_episode(
+                task_type="deploy",
+                actions=[{"type": "step1"}, {"type": "step2"}, {"type": "step3"}],
+            )
+            for _ in range(5)
+        ]
+
+        mock_procedure = MagicMock()
+
+        with (
+            patch.object(
+                service, "_get_episodic", new_callable=AsyncMock
+            ) as mock_get_episodic,
+            patch.object(
+                service, "_get_procedural", new_callable=AsyncMock
+            ) as mock_get_procedural,
+        ):
+            mock_episodic = AsyncMock()
+            mock_episodic.get_by_outcome.return_value = episodes
+            mock_get_episodic.return_value = mock_episodic
+
+            mock_procedural = AsyncMock()
+            mock_procedural.find_matching.return_value = []  # No existing procedure
+            mock_procedural.record_procedure.return_value = mock_procedure
+            mock_get_procedural.return_value = mock_procedural
+
+            result = await service.consolidate_episodes_to_procedures(
+                project_id=uuid4(),
+            )
+
+        assert result.items_processed == 5
+        assert result.items_created == 1
+
+    # =========================================================================
+    # Common Steps Extraction Tests
+    # =========================================================================
+
+    def test_extract_common_steps(self, service: MemoryConsolidationService) -> None:
+        """Test extracting steps from episodes."""
+        episodes = [
+            make_episode(
+                outcome=Outcome.SUCCESS,
+                importance_score=0.8,
+                actions=[
+                    {"type": "step1", "content": "First step"},
+                    {"type": "step2", "content": "Second step"},
+                ],
+            ),
+            make_episode(
+                outcome=Outcome.SUCCESS,
+                importance_score=0.5,
+                actions=[{"type": "simple"}],
+            ),
+        ]
+
+        steps = service._extract_common_steps(episodes)
+
+        assert len(steps) == 2
+        assert steps[0]["order"] == 1
+        assert steps[0]["action"] == "step1"
+
+    # =========================================================================
+    # Pruning Tests
+    # =========================================================================
+
+    def test_should_prune_episode_old_low_importance(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test pruning old, low-importance episode."""
+        old_date = _utcnow() - timedelta(days=100)
+        episode = make_episode(
+            occurred_at=old_date,
+            importance_score=0.1,
+            outcome=Outcome.SUCCESS,
+        )
+        cutoff = _utcnow() - timedelta(days=90)
+
+        should_prune = service._should_prune_episode(episode, cutoff, 0.2)
+
+        assert should_prune is True
+
+    def test_should_prune_episode_recent(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test not pruning recent episode."""
+        recent_date = _utcnow() - timedelta(days=30)
+        episode = make_episode(
+            occurred_at=recent_date,
+            importance_score=0.1,
+        )
+        cutoff = _utcnow() - timedelta(days=90)
+
+        should_prune = service._should_prune_episode(episode, cutoff, 0.2)
+
+        assert should_prune is False
+
+    def test_should_prune_episode_failure_protected(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test not pruning failure (with keep_all_failures=True)."""
+        old_date = _utcnow() - timedelta(days=100)
+        episode = make_episode(
+            occurred_at=old_date,
+            importance_score=0.1,
+            outcome=Outcome.FAILURE,
+        )
+        cutoff = _utcnow() - timedelta(days=90)
+
+        should_prune = service._should_prune_episode(episode, cutoff, 0.2)
+
+        # Config has keep_all_failures=True by default
+        assert should_prune is False
+
+    def test_should_prune_episode_with_lessons_protected(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test not pruning episode with lessons."""
+        old_date = _utcnow() - timedelta(days=100)
+        episode = make_episode(
+            occurred_at=old_date,
+            importance_score=0.1,
+            lessons_learned=["Important lesson"],
+        )
+        cutoff = _utcnow() - timedelta(days=90)
+
+        should_prune = service._should_prune_episode(episode, cutoff, 0.2)
+
+        # Config has keep_all_with_lessons=True by default
+        assert should_prune is False
+
+    def test_should_prune_episode_high_importance_protected(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test not pruning high importance episode."""
+        old_date = _utcnow() - timedelta(days=100)
+        episode = make_episode(
+            occurred_at=old_date,
+            importance_score=0.8,
+        )
+        cutoff = _utcnow() - timedelta(days=90)
+
+        should_prune = service._should_prune_episode(episode, cutoff, 0.2)
+
+        assert should_prune is False
+
+    @pytest.mark.asyncio
+    async def test_prune_old_episodes(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test episode pruning."""
+        old_episode = make_episode(
+            occurred_at=_utcnow() - timedelta(days=100),
+            importance_score=0.1,
+            outcome=Outcome.SUCCESS,
+            lessons_learned=[],
+        )
+
+        with patch.object(
+            service, "_get_episodic", new_callable=AsyncMock
+        ) as mock_get_episodic:
+            mock_episodic = AsyncMock()
+            mock_episodic.get_recent.return_value = [old_episode]
+            mock_episodic.delete.return_value = True
+            mock_get_episodic.return_value = mock_episodic
+
+            result = await service.prune_old_episodes(project_id=uuid4())
+
+        assert result.items_processed == 1
+        assert result.items_pruned == 1
+
+    # =========================================================================
+    # Nightly Consolidation Tests
+    # =========================================================================
+
+    @pytest.mark.asyncio
+    async def test_run_nightly_consolidation(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test nightly consolidation workflow."""
+        with (
+            patch.object(
+                service,
+                "consolidate_episodes_to_facts",
+                new_callable=AsyncMock,
+            ) as mock_facts,
+            patch.object(
+                service,
+                "consolidate_episodes_to_procedures",
+                new_callable=AsyncMock,
+            ) as mock_procedures,
+            patch.object(
+                service,
+                "prune_old_episodes",
+                new_callable=AsyncMock,
+            ) as mock_prune,
+        ):
+            mock_facts.return_value = ConsolidationResult(
+                source_type="episodic",
+                target_type="semantic",
+                items_processed=10,
+                items_created=5,
+            )
+            mock_procedures.return_value = ConsolidationResult(
+                source_type="episodic",
+                target_type="procedural",
+                items_processed=10,
+                items_created=2,
+            )
+            mock_prune.return_value = ConsolidationResult(
+                source_type="episodic",
+                target_type="pruned",
+                items_pruned=3,
+            )
+
+            result = await service.run_nightly_consolidation(project_id=uuid4())
+
+        assert result.completed_at is not None
+        assert result.total_facts_created == 5
+        assert result.total_procedures_created == 2
+        assert result.total_pruned == 3
+        assert result.total_episodes_processed == 20
+
+    @pytest.mark.asyncio
+    async def test_run_nightly_consolidation_with_errors(
+        self, service: MemoryConsolidationService
+    ) -> None:
+        """Test nightly consolidation handles errors."""
+        with (
+            patch.object(
+                service,
+                "consolidate_episodes_to_facts",
+                new_callable=AsyncMock,
+            ) as mock_facts,
+            patch.object(
+                service,
+                "consolidate_episodes_to_procedures",
+                new_callable=AsyncMock,
+            ) as mock_procedures,
+            patch.object(
+                service,
+                "prune_old_episodes",
+                new_callable=AsyncMock,
+            ) as mock_prune,
+        ):
+            mock_facts.return_value = ConsolidationResult(
+                source_type="episodic",
+                target_type="semantic",
+                errors=["fact error"],
+            )
+            mock_procedures.return_value = ConsolidationResult(
+                source_type="episodic",
+                target_type="procedural",
+            )
+            mock_prune.return_value = ConsolidationResult(
+                source_type="episodic",
+                target_type="pruned",
+            )
+
+            result = await service.run_nightly_consolidation(project_id=uuid4())
+
+        assert "fact error" in result.errors

backend/tests/unit/services/memory/episodic/__init__.py

@@ -0,0 +1,2 @@
+# tests/unit/services/memory/episodic/__init__.py
+"""Unit tests for episodic memory service."""

backend/tests/unit/services/memory/episodic/test_memory.py

@@ -0,0 +1,359 @@
+# tests/unit/services/memory/episodic/test_memory.py
+"""Unit tests for EpisodicMemory class."""
+
+from unittest.mock import AsyncMock, MagicMock
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.episodic.memory import EpisodicMemory
+from app.services.memory.episodic.retrieval import RetrievalStrategy
+from app.services.memory.types import EpisodeCreate, Outcome, RetrievalResult
+
+
+class TestEpisodicMemoryInit:
+    """Tests for EpisodicMemory initialization."""
+
+    def test_init_creates_recorder_and_retriever(self) -> None:
+        """Test that init creates recorder and retriever."""
+        mock_session = AsyncMock()
+        memory = EpisodicMemory(session=mock_session)
+
+        assert memory._recorder is not None
+        assert memory._retriever is not None
+        assert memory._session is mock_session
+
+    def test_init_with_embedding_generator(self) -> None:
+        """Test init with embedding generator."""
+        mock_session = AsyncMock()
+        mock_embedding_gen = AsyncMock()
+        memory = EpisodicMemory(
+            session=mock_session, embedding_generator=mock_embedding_gen
+        )
+
+        assert memory._embedding_generator is mock_embedding_gen
+
+    @pytest.mark.asyncio
+    async def test_create_factory_method(self) -> None:
+        """Test create factory method."""
+        mock_session = AsyncMock()
+        memory = await EpisodicMemory.create(session=mock_session)
+
+        assert memory is not None
+        assert memory._session is mock_session
+
+
+class TestEpisodicMemoryRecording:
+    """Tests for episode recording methods."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        session.add = MagicMock()
+        session.flush = AsyncMock()
+        session.refresh = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> EpisodicMemory:
+        """Create an EpisodicMemory instance."""
+        return EpisodicMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_record_episode(
+        self,
+        memory: EpisodicMemory,
+    ) -> None:
+        """Test recording an episode."""
+        episode_data = EpisodeCreate(
+            project_id=uuid4(),
+            session_id="test-session",
+            task_type="test_task",
+            task_description="Test description",
+            actions=[{"action": "test"}],
+            context_summary="Test context",
+            outcome=Outcome.SUCCESS,
+            outcome_details="Success",
+            duration_seconds=30.0,
+            tokens_used=100,
+        )
+
+        result = await memory.record_episode(episode_data)
+
+        assert result.project_id == episode_data.project_id
+        assert result.task_type == "test_task"
+        assert result.outcome == Outcome.SUCCESS
+
+    @pytest.mark.asyncio
+    async def test_record_success(
+        self,
+        memory: EpisodicMemory,
+    ) -> None:
+        """Test convenience method for recording success."""
+        project_id = uuid4()
+        result = await memory.record_success(
+            project_id=project_id,
+            session_id="test-session",
+            task_type="deployment",
+            task_description="Deploy to production",
+            actions=[{"step": "deploy"}],
+            context_summary="Deploying v1.0",
+            outcome_details="Deployed successfully",
+            duration_seconds=60.0,
+            tokens_used=200,
+        )
+
+        assert result.outcome == Outcome.SUCCESS
+        assert result.task_type == "deployment"
+
+    @pytest.mark.asyncio
+    async def test_record_failure(
+        self,
+        memory: EpisodicMemory,
+    ) -> None:
+        """Test convenience method for recording failure."""
+        project_id = uuid4()
+        result = await memory.record_failure(
+            project_id=project_id,
+            session_id="test-session",
+            task_type="deployment",
+            task_description="Deploy to production",
+            actions=[{"step": "deploy"}],
+            context_summary="Deploying v1.0",
+            error_details="Connection timeout",
+            duration_seconds=30.0,
+            tokens_used=100,
+        )
+
+        assert result.outcome == Outcome.FAILURE
+        assert result.outcome_details == "Connection timeout"
+
+
+class TestEpisodicMemoryRetrieval:
+    """Tests for episode retrieval methods."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        session.execute.return_value = mock_result
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> EpisodicMemory:
+        """Create an EpisodicMemory instance."""
+        return EpisodicMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_search_similar(
+        self,
+        memory: EpisodicMemory,
+    ) -> None:
+        """Test semantic search."""
+        project_id = uuid4()
+        results = await memory.search_similar(project_id, "authentication bug")
+
+        assert isinstance(results, list)
+
+    @pytest.mark.asyncio
+    async def test_get_recent(
+        self,
+        memory: EpisodicMemory,
+    ) -> None:
+        """Test getting recent episodes."""
+        project_id = uuid4()
+        results = await memory.get_recent(project_id, limit=5)
+
+        assert isinstance(results, list)
+
+    @pytest.mark.asyncio
+    async def test_get_by_outcome(
+        self,
+        memory: EpisodicMemory,
+    ) -> None:
+        """Test getting episodes by outcome."""
+        project_id = uuid4()
+        results = await memory.get_by_outcome(project_id, Outcome.FAILURE, limit=5)
+
+        assert isinstance(results, list)
+
+    @pytest.mark.asyncio
+    async def test_get_by_task_type(
+        self,
+        memory: EpisodicMemory,
+    ) -> None:
+        """Test getting episodes by task type."""
+        project_id = uuid4()
+        results = await memory.get_by_task_type(project_id, "code_review", limit=5)
+
+        assert isinstance(results, list)
+
+    @pytest.mark.asyncio
+    async def test_get_important(
+        self,
+        memory: EpisodicMemory,
+    ) -> None:
+        """Test getting important episodes."""
+        project_id = uuid4()
+        results = await memory.get_important(project_id, limit=5, min_importance=0.8)
+
+        assert isinstance(results, list)
+
+    @pytest.mark.asyncio
+    async def test_retrieve_with_full_result(
+        self,
+        memory: EpisodicMemory,
+    ) -> None:
+        """Test retrieve with full result metadata."""
+        project_id = uuid4()
+        result = await memory.retrieve(project_id, RetrievalStrategy.RECENCY, limit=10)
+
+        assert isinstance(result, RetrievalResult)
+        assert result.retrieval_type == "recency"
+
+
+class TestEpisodicMemorySummarization:
+    """Tests for episode summarization."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> EpisodicMemory:
+        """Create an EpisodicMemory instance."""
+        return EpisodicMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_summarize_empty_list(
+        self,
+        memory: EpisodicMemory,
+    ) -> None:
+        """Test summarizing empty episode list."""
+        summary = await memory.summarize_episodes([])
+        assert "No episodes to summarize" in summary
+
+    @pytest.mark.asyncio
+    async def test_summarize_not_found(
+        self,
+        memory: EpisodicMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test summarizing when episodes not found."""
+        # Mock get_by_id to return None
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        summary = await memory.summarize_episodes([uuid4(), uuid4()])
+        assert "No episodes found" in summary
+
+
+class TestEpisodicMemoryStats:
+    """Tests for episode statistics."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> EpisodicMemory:
+        """Create an EpisodicMemory instance."""
+        return EpisodicMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_get_stats(
+        self,
+        memory: EpisodicMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test getting episode statistics."""
+        # Mock empty result
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        mock_session.execute.return_value = mock_result
+
+        stats = await memory.get_stats(uuid4())
+
+        assert "total_count" in stats
+        assert "success_count" in stats
+        assert "failure_count" in stats
+
+    @pytest.mark.asyncio
+    async def test_count(
+        self,
+        memory: EpisodicMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test counting episodes."""
+        # Mock result with 3 episodes
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = [1, 2, 3]
+        mock_session.execute.return_value = mock_result
+
+        count = await memory.count(uuid4())
+        assert count == 3
+
+
+class TestEpisodicMemoryModification:
+    """Tests for episode modification methods."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> EpisodicMemory:
+        """Create an EpisodicMemory instance."""
+        return EpisodicMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_get_by_id_not_found(
+        self,
+        memory: EpisodicMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test get_by_id returns None when not found."""
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        result = await memory.get_by_id(uuid4())
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_update_importance_not_found(
+        self,
+        memory: EpisodicMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test update_importance returns None when not found."""
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        result = await memory.update_importance(uuid4(), 0.9)
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_delete_not_found(
+        self,
+        memory: EpisodicMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test delete returns False when not found."""
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        result = await memory.delete(uuid4())
+        assert result is False

backend/tests/unit/services/memory/episodic/test_recorder.py

@@ -0,0 +1,348 @@
+# tests/unit/services/memory/episodic/test_recorder.py
+"""Unit tests for EpisodeRecorder."""
+
+from unittest.mock import AsyncMock, MagicMock
+from uuid import uuid4
+
+import pytest
+
+from app.models.memory.enums import EpisodeOutcome
+from app.services.memory.episodic.recorder import EpisodeRecorder, _outcome_to_db
+from app.services.memory.types import EpisodeCreate, Outcome
+
+
+class TestOutcomeConversion:
+    """Tests for outcome conversion functions."""
+
+    def test_outcome_to_db_success(self) -> None:
+        """Test converting success outcome."""
+        result = _outcome_to_db(Outcome.SUCCESS)
+        assert result == EpisodeOutcome.SUCCESS
+
+    def test_outcome_to_db_failure(self) -> None:
+        """Test converting failure outcome."""
+        result = _outcome_to_db(Outcome.FAILURE)
+        assert result == EpisodeOutcome.FAILURE
+
+    def test_outcome_to_db_partial(self) -> None:
+        """Test converting partial outcome."""
+        result = _outcome_to_db(Outcome.PARTIAL)
+        assert result == EpisodeOutcome.PARTIAL
+
+
+class TestEpisodeRecorderImportanceCalculation:
+    """Tests for importance score calculation."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def recorder(self, mock_session: AsyncMock) -> EpisodeRecorder:
+        """Create a recorder with mocked session."""
+        return EpisodeRecorder(session=mock_session)
+
+    def test_calculate_importance_success_default(
+        self, recorder: EpisodeRecorder
+    ) -> None:
+        """Test importance for successful episode (default)."""
+        episode = EpisodeCreate(
+            project_id=uuid4(),
+            session_id="test-session",
+            task_type="test",
+            task_description="Test task",
+            actions=[],
+            context_summary="Context",
+            outcome=Outcome.SUCCESS,
+            outcome_details="",
+            duration_seconds=10.0,
+            tokens_used=100,
+        )
+        score = recorder._calculate_importance(episode)
+        assert 0.0 <= score <= 1.0
+        assert score == 0.5  # Base score for success
+
+    def test_calculate_importance_failure_higher(
+        self, recorder: EpisodeRecorder
+    ) -> None:
+        """Test that failures get higher importance."""
+        episode = EpisodeCreate(
+            project_id=uuid4(),
+            session_id="test-session",
+            task_type="test",
+            task_description="Test task",
+            actions=[],
+            context_summary="Context",
+            outcome=Outcome.FAILURE,
+            outcome_details="Error occurred",
+            duration_seconds=10.0,
+            tokens_used=100,
+        )
+        score = recorder._calculate_importance(episode)
+        assert score >= 0.7  # Failure adds 0.2 to base 0.5
+
+    def test_calculate_importance_with_lessons(self, recorder: EpisodeRecorder) -> None:
+        """Test that lessons increase importance."""
+        episode = EpisodeCreate(
+            project_id=uuid4(),
+            session_id="test-session",
+            task_type="test",
+            task_description="Test task",
+            actions=[],
+            context_summary="Context",
+            outcome=Outcome.SUCCESS,
+            outcome_details="",
+            duration_seconds=10.0,
+            tokens_used=100,
+            lessons_learned=["Lesson 1", "Lesson 2"],
+        )
+        score = recorder._calculate_importance(episode)
+        assert score > 0.5  # Lessons add to importance
+
+    def test_calculate_importance_long_duration(
+        self, recorder: EpisodeRecorder
+    ) -> None:
+        """Test that longer tasks get higher importance."""
+        episode = EpisodeCreate(
+            project_id=uuid4(),
+            session_id="test-session",
+            task_type="test",
+            task_description="Test task",
+            actions=[],
+            context_summary="Context",
+            outcome=Outcome.SUCCESS,
+            outcome_details="",
+            duration_seconds=400.0,  # > 300 seconds
+            tokens_used=100,
+        )
+        score = recorder._calculate_importance(episode)
+        assert score > 0.5  # Long duration adds to importance
+
+    def test_calculate_importance_clamped_to_max(
+        self, recorder: EpisodeRecorder
+    ) -> None:
+        """Test that importance is clamped to 1.0 max."""
+        episode = EpisodeCreate(
+            project_id=uuid4(),
+            session_id="test-session",
+            task_type="test",
+            task_description="Test task",
+            actions=[],
+            context_summary="Context",
+            outcome=Outcome.FAILURE,  # +0.2
+            outcome_details="Error",
+            duration_seconds=400.0,  # +0.1
+            tokens_used=2000,  # +0.05
+            lessons_learned=["L1", "L2", "L3", "L4", "L5"],  # +0.15
+        )
+        score = recorder._calculate_importance(episode)
+        assert score <= 1.0
+
+
+class TestEpisodeRecorderEmbeddingText:
+    """Tests for embedding text generation."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        return AsyncMock()
+
+    @pytest.fixture
+    def recorder(self, mock_session: AsyncMock) -> EpisodeRecorder:
+        """Create a recorder with mocked session."""
+        return EpisodeRecorder(session=mock_session)
+
+    def test_create_embedding_text_basic(self, recorder: EpisodeRecorder) -> None:
+        """Test basic embedding text creation."""
+        episode = EpisodeCreate(
+            project_id=uuid4(),
+            session_id="test-session",
+            task_type="code_review",
+            task_description="Review PR #123",
+            actions=[],
+            context_summary="Reviewing authentication changes",
+            outcome=Outcome.SUCCESS,
+            outcome_details="",
+            duration_seconds=60.0,
+            tokens_used=500,
+        )
+        text = recorder._create_embedding_text(episode)
+        assert "code_review" in text
+        assert "Review PR #123" in text
+        assert "authentication" in text
+        assert "success" in text
+
+    def test_create_embedding_text_with_details(
+        self, recorder: EpisodeRecorder
+    ) -> None:
+        """Test embedding text includes outcome details."""
+        episode = EpisodeCreate(
+            project_id=uuid4(),
+            session_id="test-session",
+            task_type="deployment",
+            task_description="Deploy to production",
+            actions=[],
+            context_summary="Deploying v1.0.0",
+            outcome=Outcome.FAILURE,
+            outcome_details="Connection timeout to server",
+            duration_seconds=30.0,
+            tokens_used=200,
+        )
+        text = recorder._create_embedding_text(episode)
+        assert "Connection timeout" in text
+
+    def test_create_embedding_text_with_lessons(
+        self, recorder: EpisodeRecorder
+    ) -> None:
+        """Test embedding text includes lessons learned."""
+        episode = EpisodeCreate(
+            project_id=uuid4(),
+            session_id="test-session",
+            task_type="debugging",
+            task_description="Fix memory leak",
+            actions=[],
+            context_summary="Debugging memory issues",
+            outcome=Outcome.SUCCESS,
+            outcome_details="",
+            duration_seconds=120.0,
+            tokens_used=800,
+            lessons_learned=["Always close file handles", "Use context managers"],
+        )
+        text = recorder._create_embedding_text(episode)
+        assert "Always close file handles" in text
+        assert "context managers" in text
+
+
+class TestEpisodeRecorderRecord:
+    """Tests for episode recording."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        session.add = MagicMock()
+        session.flush = AsyncMock()
+        session.refresh = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def recorder(self, mock_session: AsyncMock) -> EpisodeRecorder:
+        """Create a recorder with mocked session."""
+        return EpisodeRecorder(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_record_creates_episode(
+        self,
+        recorder: EpisodeRecorder,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test that record creates an episode."""
+        episode_data = EpisodeCreate(
+            project_id=uuid4(),
+            session_id="test-session",
+            task_type="test_task",
+            task_description="Test description",
+            actions=[{"action": "test"}],
+            context_summary="Test context",
+            outcome=Outcome.SUCCESS,
+            outcome_details="Success",
+            duration_seconds=30.0,
+            tokens_used=100,
+        )
+
+        result = await recorder.record(episode_data)
+
+        # Verify session methods were called
+        mock_session.add.assert_called_once()
+        mock_session.flush.assert_called_once()
+        mock_session.refresh.assert_called_once()
+
+        # Verify result
+        assert result.project_id == episode_data.project_id
+        assert result.session_id == episode_data.session_id
+        assert result.task_type == episode_data.task_type
+        assert result.outcome == Outcome.SUCCESS
+
+    @pytest.mark.asyncio
+    async def test_record_with_embedding_generator(
+        self,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test recording with embedding generator."""
+        mock_embedding_gen = AsyncMock()
+        mock_embedding_gen.generate = AsyncMock(return_value=[0.1] * 1536)
+
+        recorder = EpisodeRecorder(
+            session=mock_session, embedding_generator=mock_embedding_gen
+        )
+
+        episode_data = EpisodeCreate(
+            project_id=uuid4(),
+            session_id="test-session",
+            task_type="test_task",
+            task_description="Test description",
+            actions=[],
+            context_summary="Test context",
+            outcome=Outcome.SUCCESS,
+            outcome_details="",
+            duration_seconds=10.0,
+            tokens_used=50,
+        )
+
+        await recorder.record(episode_data)
+
+        # Verify embedding generator was called
+        mock_embedding_gen.generate.assert_called_once()
+
+
+class TestEpisodeRecorderStats:
+    """Tests for episode statistics."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def recorder(self, mock_session: AsyncMock) -> EpisodeRecorder:
+        """Create a recorder with mocked session."""
+        return EpisodeRecorder(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_get_stats_empty(
+        self,
+        recorder: EpisodeRecorder,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test stats for project with no episodes."""
+        # Mock empty result
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        mock_session.execute.return_value = mock_result
+
+        stats = await recorder.get_stats(uuid4())
+
+        assert stats["total_count"] == 0
+        assert stats["success_count"] == 0
+        assert stats["failure_count"] == 0
+        assert stats["partial_count"] == 0
+        assert stats["avg_importance"] == 0.0
+
+    @pytest.mark.asyncio
+    async def test_count_by_project(
+        self,
+        recorder: EpisodeRecorder,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test counting episodes by project."""
+        # Mock result with 5 episodes
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = [1, 2, 3, 4, 5]
+        mock_session.execute.return_value = mock_result
+
+        count = await recorder.count_by_project(uuid4())
+
+        assert count == 5

backend/tests/unit/services/memory/episodic/test_retrieval.py

@@ -0,0 +1,400 @@
+# tests/unit/services/memory/episodic/test_retrieval.py
+"""Unit tests for episode retrieval strategies."""
+
+from datetime import UTC, datetime, timedelta
+from unittest.mock import AsyncMock, MagicMock
+from uuid import uuid4
+
+import pytest
+
+from app.models.memory.enums import EpisodeOutcome
+from app.services.memory.episodic.retrieval import (
+    EpisodeRetriever,
+    ImportanceRetriever,
+    OutcomeRetriever,
+    RecencyRetriever,
+    RetrievalStrategy,
+    SemanticRetriever,
+    TaskTypeRetriever,
+)
+from app.services.memory.types import Outcome
+
+
+def create_mock_episode_model(
+    project_id=None,
+    outcome=EpisodeOutcome.SUCCESS,
+    task_type="test_task",
+    importance_score=0.5,
+    occurred_at=None,
+):
+    """Create a mock episode model for testing."""
+    mock = MagicMock()
+    mock.id = uuid4()
+    mock.project_id = project_id or uuid4()
+    mock.agent_instance_id = None
+    mock.agent_type_id = None
+    mock.session_id = "test-session"
+    mock.task_type = task_type
+    mock.task_description = "Test description"
+    mock.actions = []
+    mock.context_summary = "Test context"
+    mock.outcome = outcome
+    mock.outcome_details = ""
+    mock.duration_seconds = 30.0
+    mock.tokens_used = 100
+    mock.lessons_learned = []
+    mock.importance_score = importance_score
+    mock.embedding = None
+    mock.occurred_at = occurred_at or datetime.now(UTC)
+    mock.created_at = datetime.now(UTC)
+    mock.updated_at = datetime.now(UTC)
+    return mock
+
+
+class TestRetrievalStrategy:
+    """Tests for RetrievalStrategy enum."""
+
+    def test_strategy_values(self) -> None:
+        """Test that strategy enum has expected values."""
+        assert RetrievalStrategy.SEMANTIC == "semantic"
+        assert RetrievalStrategy.RECENCY == "recency"
+        assert RetrievalStrategy.OUTCOME == "outcome"
+        assert RetrievalStrategy.IMPORTANCE == "importance"
+        assert RetrievalStrategy.HYBRID == "hybrid"
+
+
+class TestRecencyRetriever:
+    """Tests for RecencyRetriever."""
+
+    @pytest.fixture
+    def retriever(self) -> RecencyRetriever:
+        """Create a recency retriever."""
+        return RecencyRetriever()
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        return AsyncMock()
+
+    @pytest.mark.asyncio
+    async def test_retrieve_returns_episodes(
+        self,
+        retriever: RecencyRetriever,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test that retrieve returns episodes."""
+        project_id = uuid4()
+        mock_episodes = [
+            create_mock_episode_model(project_id=project_id),
+            create_mock_episode_model(project_id=project_id),
+        ]
+
+        # Mock query result
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = mock_episodes
+        mock_session.execute.return_value = mock_result
+
+        result = await retriever.retrieve(mock_session, project_id, limit=10)
+
+        assert len(result.items) == 2
+        assert result.retrieval_type == "recency"
+        assert result.latency_ms >= 0
+
+    @pytest.mark.asyncio
+    async def test_retrieve_with_since_filter(
+        self,
+        retriever: RecencyRetriever,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test retrieve with since time filter."""
+        project_id = uuid4()
+        since = datetime.now(UTC) - timedelta(hours=1)
+
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        mock_session.execute.return_value = mock_result
+
+        result = await retriever.retrieve(
+            mock_session, project_id, limit=10, since=since
+        )
+
+        assert result.metadata["since"] == since.isoformat()
+
+
+class TestOutcomeRetriever:
+    """Tests for OutcomeRetriever."""
+
+    @pytest.fixture
+    def retriever(self) -> OutcomeRetriever:
+        """Create an outcome retriever."""
+        return OutcomeRetriever()
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        return AsyncMock()
+
+    @pytest.mark.asyncio
+    async def test_retrieve_by_success(
+        self,
+        retriever: OutcomeRetriever,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test retrieving successful episodes."""
+        project_id = uuid4()
+        mock_episodes = [
+            create_mock_episode_model(
+                project_id=project_id, outcome=EpisodeOutcome.SUCCESS
+            ),
+        ]
+
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = mock_episodes
+        mock_session.execute.return_value = mock_result
+
+        result = await retriever.retrieve(
+            mock_session, project_id, limit=10, outcome=Outcome.SUCCESS
+        )
+
+        assert result.retrieval_type == "outcome"
+        assert result.metadata["outcome"] == "success"
+
+    @pytest.mark.asyncio
+    async def test_retrieve_by_failure(
+        self,
+        retriever: OutcomeRetriever,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test retrieving failed episodes."""
+        project_id = uuid4()
+        mock_episodes = [
+            create_mock_episode_model(
+                project_id=project_id, outcome=EpisodeOutcome.FAILURE
+            ),
+        ]
+
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = mock_episodes
+        mock_session.execute.return_value = mock_result
+
+        result = await retriever.retrieve(
+            mock_session, project_id, limit=10, outcome=Outcome.FAILURE
+        )
+
+        assert result.metadata["outcome"] == "failure"
+
+
+class TestImportanceRetriever:
+    """Tests for ImportanceRetriever."""
+
+    @pytest.fixture
+    def retriever(self) -> ImportanceRetriever:
+        """Create an importance retriever."""
+        return ImportanceRetriever()
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        return AsyncMock()
+
+    @pytest.mark.asyncio
+    async def test_retrieve_by_importance(
+        self,
+        retriever: ImportanceRetriever,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test retrieving by importance score."""
+        project_id = uuid4()
+        mock_episodes = [
+            create_mock_episode_model(project_id=project_id, importance_score=0.9),
+            create_mock_episode_model(project_id=project_id, importance_score=0.8),
+        ]
+
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = mock_episodes
+        mock_session.execute.return_value = mock_result
+
+        result = await retriever.retrieve(
+            mock_session, project_id, limit=10, min_importance=0.7
+        )
+
+        assert result.retrieval_type == "importance"
+        assert result.metadata["min_importance"] == 0.7
+
+
+class TestTaskTypeRetriever:
+    """Tests for TaskTypeRetriever."""
+
+    @pytest.fixture
+    def retriever(self) -> TaskTypeRetriever:
+        """Create a task type retriever."""
+        return TaskTypeRetriever()
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        return AsyncMock()
+
+    @pytest.mark.asyncio
+    async def test_retrieve_by_task_type(
+        self,
+        retriever: TaskTypeRetriever,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test retrieving by task type."""
+        project_id = uuid4()
+        mock_episodes = [
+            create_mock_episode_model(project_id=project_id, task_type="code_review"),
+        ]
+
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = mock_episodes
+        mock_session.execute.return_value = mock_result
+
+        result = await retriever.retrieve(
+            mock_session, project_id, limit=10, task_type="code_review"
+        )
+
+        assert result.metadata["task_type"] == "code_review"
+
+
+class TestSemanticRetriever:
+    """Tests for SemanticRetriever."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        return AsyncMock()
+
+    @pytest.mark.asyncio
+    async def test_retrieve_falls_back_without_query(
+        self,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test that semantic search falls back to recency without query."""
+        retriever = SemanticRetriever()
+        project_id = uuid4()
+
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        mock_session.execute.return_value = mock_result
+
+        result = await retriever.retrieve(mock_session, project_id, limit=10)
+
+        # Should fall back to recency
+        assert result.retrieval_type == "semantic"
+
+    @pytest.mark.asyncio
+    async def test_retrieve_with_embedding_generator(
+        self,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test semantic retrieval with embedding generator."""
+        mock_embedding_gen = AsyncMock()
+        mock_embedding_gen.generate = AsyncMock(return_value=[0.1] * 1536)
+
+        retriever = SemanticRetriever(embedding_generator=mock_embedding_gen)
+        project_id = uuid4()
+
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        mock_session.execute.return_value = mock_result
+
+        result = await retriever.retrieve(
+            mock_session, project_id, limit=10, query_text="test query"
+        )
+
+        assert result.retrieval_type == "semantic"
+
+
+class TestEpisodeRetriever:
+    """Tests for unified EpisodeRetriever."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        session.execute.return_value = mock_result
+        return session
+
+    @pytest.fixture
+    def retriever(self, mock_session: AsyncMock) -> EpisodeRetriever:
+        """Create an episode retriever."""
+        return EpisodeRetriever(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_retrieve_with_recency_strategy(
+        self,
+        retriever: EpisodeRetriever,
+    ) -> None:
+        """Test retrieve with recency strategy."""
+        project_id = uuid4()
+        result = await retriever.retrieve(
+            project_id, RetrievalStrategy.RECENCY, limit=10
+        )
+        assert result.retrieval_type == "recency"
+
+    @pytest.mark.asyncio
+    async def test_retrieve_with_outcome_strategy(
+        self,
+        retriever: EpisodeRetriever,
+    ) -> None:
+        """Test retrieve with outcome strategy."""
+        project_id = uuid4()
+        result = await retriever.retrieve(
+            project_id, RetrievalStrategy.OUTCOME, limit=10
+        )
+        assert result.retrieval_type == "outcome"
+
+    @pytest.mark.asyncio
+    async def test_get_recent_convenience_method(
+        self,
+        retriever: EpisodeRetriever,
+    ) -> None:
+        """Test get_recent convenience method."""
+        project_id = uuid4()
+        result = await retriever.get_recent(project_id, limit=5)
+        assert result.retrieval_type == "recency"
+
+    @pytest.mark.asyncio
+    async def test_get_by_outcome_convenience_method(
+        self,
+        retriever: EpisodeRetriever,
+    ) -> None:
+        """Test get_by_outcome convenience method."""
+        project_id = uuid4()
+        result = await retriever.get_by_outcome(project_id, Outcome.SUCCESS, limit=5)
+        assert result.retrieval_type == "outcome"
+
+    @pytest.mark.asyncio
+    async def test_get_important_convenience_method(
+        self,
+        retriever: EpisodeRetriever,
+    ) -> None:
+        """Test get_important convenience method."""
+        project_id = uuid4()
+        result = await retriever.get_important(project_id, limit=5, min_importance=0.8)
+        assert result.retrieval_type == "importance"
+
+    @pytest.mark.asyncio
+    async def test_search_similar_convenience_method(
+        self,
+        retriever: EpisodeRetriever,
+    ) -> None:
+        """Test search_similar convenience method."""
+        project_id = uuid4()
+        result = await retriever.search_similar(project_id, "test query", limit=5)
+        assert result.retrieval_type == "semantic"
+
+    @pytest.mark.asyncio
+    async def test_unknown_strategy_raises_error(
+        self,
+        retriever: EpisodeRetriever,
+    ) -> None:
+        """Test that unknown strategy raises ValueError."""
+        project_id = uuid4()
+
+        with pytest.raises(ValueError, match="Unknown retrieval strategy"):
+            await retriever.retrieve(project_id, "invalid_strategy", limit=10)  # type: ignore

backend/tests/unit/services/memory/indexing/__init__.py

@@ -0,0 +1,2 @@
+# tests/unit/services/memory/indexing/__init__.py
+"""Unit tests for memory indexing."""

backend/tests/unit/services/memory/indexing/test_index.py

@@ -0,0 +1,497 @@
+# tests/unit/services/memory/indexing/test_index.py
+"""Unit tests for memory indexing."""
+
+from datetime import UTC, datetime, timedelta
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.indexing.index import (
+    EntityIndex,
+    MemoryIndexer,
+    OutcomeIndex,
+    TemporalIndex,
+    VectorIndex,
+    get_memory_indexer,
+)
+from app.services.memory.types import Episode, Fact, MemoryType, Outcome, Procedure
+
+
+def _utcnow() -> datetime:
+    """Get current UTC time."""
+    return datetime.now(UTC)
+
+
+def make_episode(
+    embedding: list[float] | None = None,
+    outcome: Outcome = Outcome.SUCCESS,
+    occurred_at: datetime | None = None,
+) -> Episode:
+    """Create a test episode."""
+    return Episode(
+        id=uuid4(),
+        project_id=uuid4(),
+        agent_instance_id=uuid4(),
+        agent_type_id=uuid4(),
+        session_id="test-session",
+        task_type="test_task",
+        task_description="Test task description",
+        actions=[{"action": "test"}],
+        context_summary="Test context",
+        outcome=outcome,
+        outcome_details="Test outcome",
+        duration_seconds=10.0,
+        tokens_used=100,
+        lessons_learned=["lesson1"],
+        importance_score=0.8,
+        embedding=embedding,
+        occurred_at=occurred_at or _utcnow(),
+        created_at=_utcnow(),
+        updated_at=_utcnow(),
+    )
+
+
+def make_fact(
+    embedding: list[float] | None = None,
+    subject: str = "test_subject",
+    predicate: str = "has_property",
+    obj: str = "test_value",
+) -> Fact:
+    """Create a test fact."""
+    return Fact(
+        id=uuid4(),
+        project_id=uuid4(),
+        subject=subject,
+        predicate=predicate,
+        object=obj,
+        confidence=0.9,
+        source_episode_ids=[uuid4()],
+        first_learned=_utcnow(),
+        last_reinforced=_utcnow(),
+        reinforcement_count=1,
+        embedding=embedding,
+        created_at=_utcnow(),
+        updated_at=_utcnow(),
+    )
+
+
+def make_procedure(
+    embedding: list[float] | None = None,
+    success_count: int = 8,
+    failure_count: int = 2,
+) -> Procedure:
+    """Create a test procedure."""
+    return Procedure(
+        id=uuid4(),
+        project_id=uuid4(),
+        agent_type_id=uuid4(),
+        name="test_procedure",
+        trigger_pattern="test.*",
+        steps=[{"step": 1, "action": "test"}],
+        success_count=success_count,
+        failure_count=failure_count,
+        last_used=_utcnow(),
+        embedding=embedding,
+        created_at=_utcnow(),
+        updated_at=_utcnow(),
+    )
+
+
+class TestVectorIndex:
+    """Tests for VectorIndex."""
+
+    @pytest.fixture
+    def index(self) -> VectorIndex[Episode]:
+        """Create a vector index."""
+        return VectorIndex[Episode](dimension=4)
+
+    @pytest.mark.asyncio
+    async def test_add_item(self, index: VectorIndex[Episode]) -> None:
+        """Test adding an item to the index."""
+        episode = make_episode(embedding=[1.0, 0.0, 0.0, 0.0])
+
+        entry = await index.add(episode)
+
+        assert entry.memory_id == episode.id
+        assert entry.memory_type == MemoryType.EPISODIC
+        assert entry.dimension == 4
+        assert await index.count() == 1
+
+    @pytest.mark.asyncio
+    async def test_remove_item(self, index: VectorIndex[Episode]) -> None:
+        """Test removing an item from the index."""
+        episode = make_episode(embedding=[1.0, 0.0, 0.0, 0.0])
+        await index.add(episode)
+
+        result = await index.remove(episode.id)
+
+        assert result is True
+        assert await index.count() == 0
+
+    @pytest.mark.asyncio
+    async def test_remove_nonexistent(self, index: VectorIndex[Episode]) -> None:
+        """Test removing a nonexistent item."""
+        result = await index.remove(uuid4())
+        assert result is False
+
+    @pytest.mark.asyncio
+    async def test_search_similar(self, index: VectorIndex[Episode]) -> None:
+        """Test searching for similar items."""
+        # Add items with different embeddings
+        e1 = make_episode(embedding=[1.0, 0.0, 0.0, 0.0])
+        e2 = make_episode(embedding=[0.9, 0.1, 0.0, 0.0])
+        e3 = make_episode(embedding=[0.0, 1.0, 0.0, 0.0])
+
+        await index.add(e1)
+        await index.add(e2)
+        await index.add(e3)
+
+        # Search for similar to first
+        results = await index.search([1.0, 0.0, 0.0, 0.0], limit=2)
+
+        assert len(results) == 2
+        # First result should be most similar
+        assert results[0].memory_id == e1.id
+
+    @pytest.mark.asyncio
+    async def test_search_min_similarity(self, index: VectorIndex[Episode]) -> None:
+        """Test minimum similarity threshold."""
+        e1 = make_episode(embedding=[1.0, 0.0, 0.0, 0.0])
+        e2 = make_episode(embedding=[0.0, 1.0, 0.0, 0.0])  # Orthogonal
+
+        await index.add(e1)
+        await index.add(e2)
+
+        # Search with high threshold
+        results = await index.search([1.0, 0.0, 0.0, 0.0], min_similarity=0.9)
+
+        assert len(results) == 1
+        assert results[0].memory_id == e1.id
+
+    @pytest.mark.asyncio
+    async def test_search_empty_query(self, index: VectorIndex[Episode]) -> None:
+        """Test search with empty query."""
+        e1 = make_episode(embedding=[1.0, 0.0, 0.0, 0.0])
+        await index.add(e1)
+
+        results = await index.search([], limit=10)
+        assert len(results) == 0
+
+    @pytest.mark.asyncio
+    async def test_clear(self, index: VectorIndex[Episode]) -> None:
+        """Test clearing the index."""
+        await index.add(make_episode(embedding=[1.0, 0.0, 0.0, 0.0]))
+        await index.add(make_episode(embedding=[0.0, 1.0, 0.0, 0.0]))
+
+        count = await index.clear()
+
+        assert count == 2
+        assert await index.count() == 0
+
+
+class TestTemporalIndex:
+    """Tests for TemporalIndex."""
+
+    @pytest.fixture
+    def index(self) -> TemporalIndex[Episode]:
+        """Create a temporal index."""
+        return TemporalIndex[Episode]()
+
+    @pytest.mark.asyncio
+    async def test_add_item(self, index: TemporalIndex[Episode]) -> None:
+        """Test adding an item."""
+        episode = make_episode()
+        entry = await index.add(episode)
+
+        assert entry.memory_id == episode.id
+        assert await index.count() == 1
+
+    @pytest.mark.asyncio
+    async def test_search_by_time_range(self, index: TemporalIndex[Episode]) -> None:
+        """Test searching by time range."""
+        now = _utcnow()
+        old = make_episode(occurred_at=now - timedelta(hours=2))
+        recent = make_episode(occurred_at=now - timedelta(hours=1))
+        newest = make_episode(occurred_at=now)
+
+        await index.add(old)
+        await index.add(recent)
+        await index.add(newest)
+
+        # Search last hour
+        results = await index.search(
+            query=None,
+            start_time=now - timedelta(hours=1, minutes=30),
+            end_time=now,
+        )
+
+        assert len(results) == 2
+
+    @pytest.mark.asyncio
+    async def test_search_recent(self, index: TemporalIndex[Episode]) -> None:
+        """Test searching for recent items."""
+        now = _utcnow()
+        old = make_episode(occurred_at=now - timedelta(hours=2))
+        recent = make_episode(occurred_at=now - timedelta(minutes=30))
+
+        await index.add(old)
+        await index.add(recent)
+
+        # Search last hour (3600 seconds)
+        results = await index.search(query=None, recent_seconds=3600)
+
+        assert len(results) == 1
+        assert results[0].memory_id == recent.id
+
+    @pytest.mark.asyncio
+    async def test_search_order(self, index: TemporalIndex[Episode]) -> None:
+        """Test result ordering."""
+        now = _utcnow()
+        e1 = make_episode(occurred_at=now - timedelta(hours=2))
+        e2 = make_episode(occurred_at=now - timedelta(hours=1))
+        e3 = make_episode(occurred_at=now)
+
+        await index.add(e1)
+        await index.add(e2)
+        await index.add(e3)
+
+        # Descending order (newest first)
+        results_desc = await index.search(query=None, order="desc", limit=10)
+        assert results_desc[0].memory_id == e3.id
+
+        # Ascending order (oldest first)
+        results_asc = await index.search(query=None, order="asc", limit=10)
+        assert results_asc[0].memory_id == e1.id
+
+
+class TestEntityIndex:
+    """Tests for EntityIndex."""
+
+    @pytest.fixture
+    def index(self) -> EntityIndex[Fact]:
+        """Create an entity index."""
+        return EntityIndex[Fact]()
+
+    @pytest.mark.asyncio
+    async def test_add_item(self, index: EntityIndex[Fact]) -> None:
+        """Test adding an item."""
+        fact = make_fact(subject="user", obj="admin")
+        entry = await index.add(fact)
+
+        assert entry.memory_id == fact.id
+        assert await index.count() == 1
+
+    @pytest.mark.asyncio
+    async def test_search_by_entity(self, index: EntityIndex[Fact]) -> None:
+        """Test searching by entity."""
+        f1 = make_fact(subject="user", obj="admin")
+        f2 = make_fact(subject="system", obj="config")
+
+        await index.add(f1)
+        await index.add(f2)
+
+        results = await index.search(
+            query=None,
+            entity_type="subject",
+            entity_value="user",
+        )
+
+        assert len(results) == 1
+        assert results[0].memory_id == f1.id
+
+    @pytest.mark.asyncio
+    async def test_search_multiple_entities(self, index: EntityIndex[Fact]) -> None:
+        """Test searching with multiple entities."""
+        f1 = make_fact(subject="user", obj="admin")
+        f2 = make_fact(subject="user", obj="guest")
+
+        await index.add(f1)
+        await index.add(f2)
+
+        # Search for facts about "user" subject
+        results = await index.search(
+            query=None,
+            entities=[("subject", "user")],
+        )
+
+        assert len(results) == 2
+
+    @pytest.mark.asyncio
+    async def test_search_match_all(self, index: EntityIndex[Fact]) -> None:
+        """Test matching all entities."""
+        f1 = make_fact(subject="user", obj="admin")
+        f2 = make_fact(subject="user", obj="guest")
+
+        await index.add(f1)
+        await index.add(f2)
+
+        # Search for user+admin (match all)
+        results = await index.search(
+            query=None,
+            entities=[("subject", "user"), ("object", "admin")],
+            match_all=True,
+        )
+
+        assert len(results) == 1
+        assert results[0].memory_id == f1.id
+
+    @pytest.mark.asyncio
+    async def test_get_entities(self, index: EntityIndex[Fact]) -> None:
+        """Test getting entities for a memory."""
+        fact = make_fact(subject="user", obj="admin")
+        await index.add(fact)
+
+        entities = await index.get_entities(fact.id)
+
+        assert ("subject", "user") in entities
+        assert ("object", "admin") in entities
+
+
+class TestOutcomeIndex:
+    """Tests for OutcomeIndex."""
+
+    @pytest.fixture
+    def index(self) -> OutcomeIndex[Episode]:
+        """Create an outcome index."""
+        return OutcomeIndex[Episode]()
+
+    @pytest.mark.asyncio
+    async def test_add_item(self, index: OutcomeIndex[Episode]) -> None:
+        """Test adding an item."""
+        episode = make_episode(outcome=Outcome.SUCCESS)
+        entry = await index.add(episode)
+
+        assert entry.memory_id == episode.id
+        assert entry.outcome == Outcome.SUCCESS
+        assert await index.count() == 1
+
+    @pytest.mark.asyncio
+    async def test_search_by_outcome(self, index: OutcomeIndex[Episode]) -> None:
+        """Test searching by outcome."""
+        success = make_episode(outcome=Outcome.SUCCESS)
+        failure = make_episode(outcome=Outcome.FAILURE)
+
+        await index.add(success)
+        await index.add(failure)
+
+        results = await index.search(query=None, outcome=Outcome.SUCCESS)
+
+        assert len(results) == 1
+        assert results[0].memory_id == success.id
+
+    @pytest.mark.asyncio
+    async def test_search_multiple_outcomes(self, index: OutcomeIndex[Episode]) -> None:
+        """Test searching with multiple outcomes."""
+        success = make_episode(outcome=Outcome.SUCCESS)
+        partial = make_episode(outcome=Outcome.PARTIAL)
+        failure = make_episode(outcome=Outcome.FAILURE)
+
+        await index.add(success)
+        await index.add(partial)
+        await index.add(failure)
+
+        results = await index.search(
+            query=None,
+            outcomes=[Outcome.SUCCESS, Outcome.PARTIAL],
+        )
+
+        assert len(results) == 2
+
+    @pytest.mark.asyncio
+    async def test_get_outcome_stats(self, index: OutcomeIndex[Episode]) -> None:
+        """Test getting outcome statistics."""
+        await index.add(make_episode(outcome=Outcome.SUCCESS))
+        await index.add(make_episode(outcome=Outcome.SUCCESS))
+        await index.add(make_episode(outcome=Outcome.FAILURE))
+
+        stats = await index.get_outcome_stats()
+
+        assert stats[Outcome.SUCCESS] == 2
+        assert stats[Outcome.FAILURE] == 1
+        assert stats[Outcome.PARTIAL] == 0
+
+
+class TestMemoryIndexer:
+    """Tests for MemoryIndexer."""
+
+    @pytest.fixture
+    def indexer(self) -> MemoryIndexer:
+        """Create a memory indexer."""
+        return MemoryIndexer()
+
+    @pytest.mark.asyncio
+    async def test_index_episode(self, indexer: MemoryIndexer) -> None:
+        """Test indexing an episode."""
+        episode = make_episode(embedding=[1.0, 0.0, 0.0, 0.0])
+
+        results = await indexer.index(episode)
+
+        assert "vector" in results
+        assert "temporal" in results
+        assert "entity" in results
+        assert "outcome" in results
+
+    @pytest.mark.asyncio
+    async def test_index_fact(self, indexer: MemoryIndexer) -> None:
+        """Test indexing a fact."""
+        fact = make_fact(embedding=[1.0, 0.0, 0.0, 0.0])
+
+        results = await indexer.index(fact)
+
+        # Facts don't have outcomes
+        assert "vector" in results
+        assert "temporal" in results
+        assert "entity" in results
+        assert "outcome" not in results
+
+    @pytest.mark.asyncio
+    async def test_remove_from_all(self, indexer: MemoryIndexer) -> None:
+        """Test removing from all indices."""
+        episode = make_episode(embedding=[1.0, 0.0, 0.0, 0.0])
+        await indexer.index(episode)
+
+        results = await indexer.remove(episode.id)
+
+        assert results["vector"] is True
+        assert results["temporal"] is True
+        assert results["entity"] is True
+        assert results["outcome"] is True
+
+    @pytest.mark.asyncio
+    async def test_clear_all(self, indexer: MemoryIndexer) -> None:
+        """Test clearing all indices."""
+        await indexer.index(make_episode(embedding=[1.0, 0.0, 0.0, 0.0]))
+        await indexer.index(make_episode(embedding=[0.0, 1.0, 0.0, 0.0]))
+
+        counts = await indexer.clear_all()
+
+        assert counts["vector"] == 2
+        assert counts["temporal"] == 2
+
+    @pytest.mark.asyncio
+    async def test_get_stats(self, indexer: MemoryIndexer) -> None:
+        """Test getting index statistics."""
+        await indexer.index(make_episode(embedding=[1.0, 0.0, 0.0, 0.0]))
+
+        stats = await indexer.get_stats()
+
+        assert stats["vector"] == 1
+        assert stats["temporal"] == 1
+        assert stats["entity"] == 1
+        assert stats["outcome"] == 1
+
+
+class TestGetMemoryIndexer:
+    """Tests for singleton getter."""
+
+    def test_returns_instance(self) -> None:
+        """Test that getter returns instance."""
+        indexer = get_memory_indexer()
+        assert indexer is not None
+        assert isinstance(indexer, MemoryIndexer)
+
+    def test_returns_same_instance(self) -> None:
+        """Test that getter returns same instance."""
+        indexer1 = get_memory_indexer()
+        indexer2 = get_memory_indexer()
+        assert indexer1 is indexer2

backend/tests/unit/services/memory/indexing/test_retrieval.py

@@ -0,0 +1,450 @@
+# tests/unit/services/memory/indexing/test_retrieval.py
+"""Unit tests for memory retrieval."""
+
+from datetime import UTC, datetime, timedelta
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.indexing.index import MemoryIndexer
+from app.services.memory.indexing.retrieval import (
+    RelevanceScorer,
+    RetrievalCache,
+    RetrievalEngine,
+    RetrievalQuery,
+    ScoredResult,
+    get_retrieval_engine,
+)
+from app.services.memory.types import Episode, MemoryType, Outcome
+
+
+def _utcnow() -> datetime:
+    """Get current UTC time."""
+    return datetime.now(UTC)
+
+
+def make_episode(
+    embedding: list[float] | None = None,
+    outcome: Outcome = Outcome.SUCCESS,
+    occurred_at: datetime | None = None,
+    task_type: str = "test_task",
+) -> Episode:
+    """Create a test episode."""
+    return Episode(
+        id=uuid4(),
+        project_id=uuid4(),
+        agent_instance_id=uuid4(),
+        agent_type_id=uuid4(),
+        session_id="test-session",
+        task_type=task_type,
+        task_description="Test task description",
+        actions=[{"action": "test"}],
+        context_summary="Test context",
+        outcome=outcome,
+        outcome_details="Test outcome",
+        duration_seconds=10.0,
+        tokens_used=100,
+        lessons_learned=["lesson1"],
+        importance_score=0.8,
+        embedding=embedding,
+        occurred_at=occurred_at or _utcnow(),
+        created_at=_utcnow(),
+        updated_at=_utcnow(),
+    )
+
+
+class TestRetrievalQuery:
+    """Tests for RetrievalQuery."""
+
+    def test_default_values(self) -> None:
+        """Test default query values."""
+        query = RetrievalQuery()
+
+        assert query.query_text is None
+        assert query.limit == 10
+        assert query.min_relevance == 0.0
+        assert query.use_vector is True
+        assert query.use_temporal is True
+
+    def test_cache_key_generation(self) -> None:
+        """Test cache key generation."""
+        query1 = RetrievalQuery(query_text="test", limit=10)
+        query2 = RetrievalQuery(query_text="test", limit=10)
+        query3 = RetrievalQuery(query_text="different", limit=10)
+
+        # Same queries should have same key
+        assert query1.to_cache_key() == query2.to_cache_key()
+        # Different queries should have different keys
+        assert query1.to_cache_key() != query3.to_cache_key()
+
+
+class TestScoredResult:
+    """Tests for ScoredResult."""
+
+    def test_creation(self) -> None:
+        """Test creating a scored result."""
+        result = ScoredResult(
+            memory_id=uuid4(),
+            memory_type=MemoryType.EPISODIC,
+            relevance_score=0.85,
+            score_breakdown={"vector": 0.9, "recency": 0.8},
+        )
+
+        assert result.relevance_score == 0.85
+        assert result.score_breakdown["vector"] == 0.9
+
+
+class TestRelevanceScorer:
+    """Tests for RelevanceScorer."""
+
+    @pytest.fixture
+    def scorer(self) -> RelevanceScorer:
+        """Create a relevance scorer."""
+        return RelevanceScorer()
+
+    def test_score_with_vector(self, scorer: RelevanceScorer) -> None:
+        """Test scoring with vector similarity."""
+        result = scorer.score(
+            memory_id=uuid4(),
+            memory_type=MemoryType.EPISODIC,
+            vector_similarity=0.9,
+        )
+
+        assert result.relevance_score > 0
+        assert result.score_breakdown["vector"] == 0.9
+
+    def test_score_with_recency(self, scorer: RelevanceScorer) -> None:
+        """Test scoring with recency."""
+        recent_result = scorer.score(
+            memory_id=uuid4(),
+            memory_type=MemoryType.EPISODIC,
+            timestamp=_utcnow(),
+        )
+
+        old_result = scorer.score(
+            memory_id=uuid4(),
+            memory_type=MemoryType.EPISODIC,
+            timestamp=_utcnow() - timedelta(days=7),
+        )
+
+        # Recent should have higher recency score
+        assert (
+            recent_result.score_breakdown["recency"]
+            > old_result.score_breakdown["recency"]
+        )
+
+    def test_score_with_outcome_preference(self, scorer: RelevanceScorer) -> None:
+        """Test scoring with outcome preference."""
+        success_result = scorer.score(
+            memory_id=uuid4(),
+            memory_type=MemoryType.EPISODIC,
+            outcome=Outcome.SUCCESS,
+            preferred_outcomes=[Outcome.SUCCESS],
+        )
+
+        failure_result = scorer.score(
+            memory_id=uuid4(),
+            memory_type=MemoryType.EPISODIC,
+            outcome=Outcome.FAILURE,
+            preferred_outcomes=[Outcome.SUCCESS],
+        )
+
+        assert success_result.score_breakdown["outcome"] == 1.0
+        assert failure_result.score_breakdown["outcome"] == 0.0
+
+    def test_score_with_entity_match(self, scorer: RelevanceScorer) -> None:
+        """Test scoring with entity matches."""
+        full_match = scorer.score(
+            memory_id=uuid4(),
+            memory_type=MemoryType.EPISODIC,
+            entity_match_count=3,
+            entity_total=3,
+        )
+
+        partial_match = scorer.score(
+            memory_id=uuid4(),
+            memory_type=MemoryType.EPISODIC,
+            entity_match_count=1,
+            entity_total=3,
+        )
+
+        assert (
+            full_match.score_breakdown["entity"]
+            > partial_match.score_breakdown["entity"]
+        )
+
+
+class TestRetrievalCache:
+    """Tests for RetrievalCache."""
+
+    @pytest.fixture
+    def cache(self) -> RetrievalCache:
+        """Create a retrieval cache."""
+        return RetrievalCache(max_entries=10, default_ttl_seconds=60)
+
+    def test_put_and_get(self, cache: RetrievalCache) -> None:
+        """Test putting and getting from cache."""
+        results = [
+            ScoredResult(
+                memory_id=uuid4(),
+                memory_type=MemoryType.EPISODIC,
+                relevance_score=0.8,
+            )
+        ]
+
+        cache.put("test_key", results)
+        cached = cache.get("test_key")
+
+        assert cached is not None
+        assert len(cached) == 1
+
+    def test_get_nonexistent(self, cache: RetrievalCache) -> None:
+        """Test getting nonexistent entry."""
+        result = cache.get("nonexistent")
+        assert result is None
+
+    def test_lru_eviction(self) -> None:
+        """Test LRU eviction when at capacity."""
+        cache = RetrievalCache(max_entries=2, default_ttl_seconds=60)
+
+        results = [
+            ScoredResult(
+                memory_id=uuid4(),
+                memory_type=MemoryType.EPISODIC,
+                relevance_score=0.8,
+            )
+        ]
+
+        cache.put("key1", results)
+        cache.put("key2", results)
+        cache.put("key3", results)  # Should evict key1
+
+        assert cache.get("key1") is None
+        assert cache.get("key2") is not None
+        assert cache.get("key3") is not None
+
+    def test_invalidate(self, cache: RetrievalCache) -> None:
+        """Test invalidating a cache entry."""
+        results = [
+            ScoredResult(
+                memory_id=uuid4(),
+                memory_type=MemoryType.EPISODIC,
+                relevance_score=0.8,
+            )
+        ]
+
+        cache.put("test_key", results)
+        removed = cache.invalidate("test_key")
+
+        assert removed is True
+        assert cache.get("test_key") is None
+
+    def test_invalidate_by_memory(self, cache: RetrievalCache) -> None:
+        """Test invalidating by memory ID."""
+        memory_id = uuid4()
+        results = [
+            ScoredResult(
+                memory_id=memory_id,
+                memory_type=MemoryType.EPISODIC,
+                relevance_score=0.8,
+            )
+        ]
+
+        cache.put("key1", results)
+        cache.put("key2", results)
+
+        count = cache.invalidate_by_memory(memory_id)
+
+        assert count == 2
+        assert cache.get("key1") is None
+        assert cache.get("key2") is None
+
+    def test_clear(self, cache: RetrievalCache) -> None:
+        """Test clearing the cache."""
+        results = [
+            ScoredResult(
+                memory_id=uuid4(),
+                memory_type=MemoryType.EPISODIC,
+                relevance_score=0.8,
+            )
+        ]
+
+        cache.put("key1", results)
+        cache.put("key2", results)
+
+        count = cache.clear()
+
+        assert count == 2
+        assert cache.get("key1") is None
+
+    def test_get_stats(self, cache: RetrievalCache) -> None:
+        """Test getting cache statistics."""
+        stats = cache.get_stats()
+
+        assert "total_entries" in stats
+        assert "max_entries" in stats
+        assert stats["max_entries"] == 10
+
+
+class TestRetrievalEngine:
+    """Tests for RetrievalEngine."""
+
+    @pytest.fixture
+    def indexer(self) -> MemoryIndexer:
+        """Create a memory indexer."""
+        return MemoryIndexer()
+
+    @pytest.fixture
+    def engine(self, indexer: MemoryIndexer) -> RetrievalEngine:
+        """Create a retrieval engine."""
+        return RetrievalEngine(indexer=indexer, enable_cache=True)
+
+    @pytest.mark.asyncio
+    async def test_retrieve_by_vector(
+        self, engine: RetrievalEngine, indexer: MemoryIndexer
+    ) -> None:
+        """Test retrieval by vector similarity."""
+        e1 = make_episode(embedding=[1.0, 0.0, 0.0, 0.0])
+        e2 = make_episode(embedding=[0.9, 0.1, 0.0, 0.0])
+        e3 = make_episode(embedding=[0.0, 1.0, 0.0, 0.0])
+
+        await indexer.index(e1)
+        await indexer.index(e2)
+        await indexer.index(e3)
+
+        query = RetrievalQuery(
+            query_embedding=[1.0, 0.0, 0.0, 0.0],
+            limit=2,
+            use_temporal=False,
+            use_entity=False,
+            use_outcome=False,
+        )
+
+        result = await engine.retrieve(query)
+
+        assert len(result.items) > 0
+        assert result.retrieval_type == "hybrid"
+
+    @pytest.mark.asyncio
+    async def test_retrieve_recent(
+        self, engine: RetrievalEngine, indexer: MemoryIndexer
+    ) -> None:
+        """Test retrieval of recent items."""
+        now = _utcnow()
+        old = make_episode(occurred_at=now - timedelta(hours=2))
+        recent = make_episode(occurred_at=now - timedelta(minutes=30))
+
+        await indexer.index(old)
+        await indexer.index(recent)
+
+        result = await engine.retrieve_recent(hours=1)
+
+        assert len(result.items) == 1
+
+    @pytest.mark.asyncio
+    async def test_retrieve_by_entity(
+        self, engine: RetrievalEngine, indexer: MemoryIndexer
+    ) -> None:
+        """Test retrieval by entity."""
+        e1 = make_episode(task_type="deploy")
+        e2 = make_episode(task_type="test")
+
+        await indexer.index(e1)
+        await indexer.index(e2)
+
+        result = await engine.retrieve_by_entity("task_type", "deploy")
+
+        assert len(result.items) == 1
+
+    @pytest.mark.asyncio
+    async def test_retrieve_successful(
+        self, engine: RetrievalEngine, indexer: MemoryIndexer
+    ) -> None:
+        """Test retrieval of successful items."""
+        success = make_episode(outcome=Outcome.SUCCESS)
+        failure = make_episode(outcome=Outcome.FAILURE)
+
+        await indexer.index(success)
+        await indexer.index(failure)
+
+        result = await engine.retrieve_successful()
+
+        assert len(result.items) == 1
+        # Check outcome index was used
+        assert result.items[0].memory_id == success.id
+
+    @pytest.mark.asyncio
+    async def test_retrieve_with_cache(
+        self, engine: RetrievalEngine, indexer: MemoryIndexer
+    ) -> None:
+        """Test that retrieval uses cache."""
+        episode = make_episode(embedding=[1.0, 0.0, 0.0, 0.0])
+        await indexer.index(episode)
+
+        query = RetrievalQuery(
+            query_embedding=[1.0, 0.0, 0.0, 0.0],
+            limit=10,
+        )
+
+        # First retrieval
+        result1 = await engine.retrieve(query)
+        assert result1.metadata.get("cache_hit") is False
+
+        # Second retrieval should be cached
+        result2 = await engine.retrieve(query)
+        assert result2.metadata.get("cache_hit") is True
+
+    @pytest.mark.asyncio
+    async def test_invalidate_cache(
+        self, engine: RetrievalEngine, indexer: MemoryIndexer
+    ) -> None:
+        """Test cache invalidation."""
+        episode = make_episode(embedding=[1.0, 0.0, 0.0, 0.0])
+        await indexer.index(episode)
+
+        query = RetrievalQuery(query_embedding=[1.0, 0.0, 0.0, 0.0])
+        await engine.retrieve(query)
+
+        count = engine.invalidate_cache()
+
+        assert count > 0
+
+    @pytest.mark.asyncio
+    async def test_retrieve_similar(
+        self, engine: RetrievalEngine, indexer: MemoryIndexer
+    ) -> None:
+        """Test retrieve_similar convenience method."""
+        e1 = make_episode(embedding=[1.0, 0.0, 0.0, 0.0])
+        e2 = make_episode(embedding=[0.0, 1.0, 0.0, 0.0])
+
+        await indexer.index(e1)
+        await indexer.index(e2)
+
+        result = await engine.retrieve_similar(
+            embedding=[1.0, 0.0, 0.0, 0.0],
+            limit=1,
+        )
+
+        assert len(result.items) == 1
+
+    def test_get_cache_stats(self, engine: RetrievalEngine) -> None:
+        """Test getting cache statistics."""
+        stats = engine.get_cache_stats()
+
+        assert "total_entries" in stats
+
+
+class TestGetRetrievalEngine:
+    """Tests for singleton getter."""
+
+    def test_returns_instance(self) -> None:
+        """Test that getter returns instance."""
+        engine = get_retrieval_engine()
+        assert engine is not None
+        assert isinstance(engine, RetrievalEngine)
+
+    def test_returns_same_instance(self) -> None:
+        """Test that getter returns same instance."""
+        engine1 = get_retrieval_engine()
+        engine2 = get_retrieval_engine()
+        assert engine1 is engine2

backend/tests/unit/services/memory/integration/__init__.py

@@ -0,0 +1,2 @@
+# tests/unit/services/memory/integration/__init__.py
+"""Tests for memory integration module."""

backend/tests/unit/services/memory/integration/test_context_source.py

@@ -0,0 +1,322 @@
+# tests/unit/services/memory/integration/test_context_source.py
+"""Tests for MemoryContextSource service."""
+
+from datetime import UTC, datetime
+from unittest.mock import AsyncMock, MagicMock, patch
+from uuid import uuid4
+
+import pytest
+
+from app.services.context.types.memory import MemorySubtype
+from app.services.memory.integration.context_source import (
+    MemoryContextSource,
+    MemoryFetchConfig,
+    MemoryFetchResult,
+    get_memory_context_source,
+)
+
+pytestmark = pytest.mark.asyncio(loop_scope="function")
+
+
+@pytest.fixture
+def mock_session() -> MagicMock:
+    """Create mock database session."""
+    return MagicMock()
+
+
+@pytest.fixture
+def context_source(mock_session: MagicMock) -> MemoryContextSource:
+    """Create MemoryContextSource instance."""
+    return MemoryContextSource(session=mock_session)
+
+
+class TestMemoryFetchConfig:
+    """Tests for MemoryFetchConfig."""
+
+    def test_default_values(self) -> None:
+        """Default config values should be set correctly."""
+        config = MemoryFetchConfig()
+
+        assert config.working_limit == 10
+        assert config.episodic_limit == 10
+        assert config.semantic_limit == 15
+        assert config.procedural_limit == 5
+        assert config.episodic_days_back == 30
+        assert config.min_relevance == 0.3
+        assert config.include_working is True
+        assert config.include_episodic is True
+        assert config.include_semantic is True
+        assert config.include_procedural is True
+
+    def test_custom_values(self) -> None:
+        """Custom config values should be respected."""
+        config = MemoryFetchConfig(
+            working_limit=5,
+            include_working=False,
+        )
+
+        assert config.working_limit == 5
+        assert config.include_working is False
+
+
+class TestMemoryFetchResult:
+    """Tests for MemoryFetchResult."""
+
+    def test_stores_results(self) -> None:
+        """Result should store contexts and metadata."""
+        result = MemoryFetchResult(
+            contexts=[],
+            by_type={"working": 0, "episodic": 5, "semantic": 3, "procedural": 0},
+            fetch_time_ms=15.5,
+            query="test query",
+        )
+
+        assert result.contexts == []
+        assert result.by_type["episodic"] == 5
+        assert result.fetch_time_ms == 15.5
+        assert result.query == "test query"
+
+
+class TestMemoryContextSource:
+    """Tests for MemoryContextSource service."""
+
+    async def test_fetch_context_empty_when_no_sources(
+        self,
+        context_source: MemoryContextSource,
+    ) -> None:
+        """fetch_context should return empty when all sources fail."""
+        config = MemoryFetchConfig(
+            include_working=False,
+            include_episodic=False,
+            include_semantic=False,
+            include_procedural=False,
+        )
+
+        result = await context_source.fetch_context(
+            query="test",
+            project_id=uuid4(),
+            config=config,
+        )
+
+        assert len(result.contexts) == 0
+        assert result.by_type == {
+            "working": 0,
+            "episodic": 0,
+            "semantic": 0,
+            "procedural": 0,
+        }
+
+    @patch("app.services.memory.integration.context_source.WorkingMemory")
+    async def test_fetch_working_memory(
+        self,
+        mock_working_cls: MagicMock,
+        context_source: MemoryContextSource,
+    ) -> None:
+        """Should fetch working memory when session_id provided."""
+        # Setup mock - both keys should match the query "task"
+        mock_working = AsyncMock()
+        mock_working.list_keys = AsyncMock(return_value=["current_task", "task_state"])
+        mock_working.get = AsyncMock(side_effect=lambda k: {"key": k, "value": "test"})
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        config = MemoryFetchConfig(
+            include_episodic=False,
+            include_semantic=False,
+            include_procedural=False,
+        )
+
+        result = await context_source.fetch_context(
+            query="task",  # Both keys contain "task"
+            project_id=uuid4(),
+            session_id="sess-123",
+            config=config,
+        )
+
+        assert result.by_type["working"] == 2
+        assert all(
+            c.memory_subtype == MemorySubtype.WORKING for c in result.contexts
+        )
+
+    @patch("app.services.memory.integration.context_source.EpisodicMemory")
+    async def test_fetch_episodic_memory(
+        self,
+        mock_episodic_cls: MagicMock,
+        context_source: MemoryContextSource,
+    ) -> None:
+        """Should fetch episodic memory."""
+        # Setup mock episode
+        mock_episode = MagicMock()
+        mock_episode.id = uuid4()
+        mock_episode.task_description = "Completed login feature"
+        mock_episode.task_type = "feature"
+        mock_episode.outcome = MagicMock(value="success")
+        mock_episode.importance_score = 0.8
+        mock_episode.occurred_at = datetime.now(UTC)
+        mock_episode.lessons_learned = []
+
+        mock_episodic = AsyncMock()
+        mock_episodic.search_similar = AsyncMock(return_value=[mock_episode])
+        mock_episodic.get_recent = AsyncMock(return_value=[])
+        mock_episodic_cls.create = AsyncMock(return_value=mock_episodic)
+
+        config = MemoryFetchConfig(
+            include_working=False,
+            include_semantic=False,
+            include_procedural=False,
+        )
+
+        result = await context_source.fetch_context(
+            query="login",
+            project_id=uuid4(),
+            config=config,
+        )
+
+        assert result.by_type["episodic"] == 1
+        assert result.contexts[0].memory_subtype == MemorySubtype.EPISODIC
+        assert "Completed login feature" in result.contexts[0].content
+
+    @patch("app.services.memory.integration.context_source.SemanticMemory")
+    async def test_fetch_semantic_memory(
+        self,
+        mock_semantic_cls: MagicMock,
+        context_source: MemoryContextSource,
+    ) -> None:
+        """Should fetch semantic memory."""
+        # Setup mock fact
+        mock_fact = MagicMock()
+        mock_fact.id = uuid4()
+        mock_fact.subject = "User"
+        mock_fact.predicate = "prefers"
+        mock_fact.object = "dark mode"
+        mock_fact.confidence = 0.9
+
+        mock_semantic = AsyncMock()
+        mock_semantic.search_facts = AsyncMock(return_value=[mock_fact])
+        mock_semantic_cls.create = AsyncMock(return_value=mock_semantic)
+
+        config = MemoryFetchConfig(
+            include_working=False,
+            include_episodic=False,
+            include_procedural=False,
+        )
+
+        result = await context_source.fetch_context(
+            query="preferences",
+            project_id=uuid4(),
+            config=config,
+        )
+
+        assert result.by_type["semantic"] == 1
+        assert result.contexts[0].memory_subtype == MemorySubtype.SEMANTIC
+        assert "User prefers dark mode" in result.contexts[0].content
+
+    @patch("app.services.memory.integration.context_source.ProceduralMemory")
+    async def test_fetch_procedural_memory(
+        self,
+        mock_procedural_cls: MagicMock,
+        context_source: MemoryContextSource,
+    ) -> None:
+        """Should fetch procedural memory."""
+        # Setup mock procedure
+        mock_proc = MagicMock()
+        mock_proc.id = uuid4()
+        mock_proc.name = "Deploy"
+        mock_proc.trigger_pattern = "When deploying"
+        mock_proc.steps = [{"action": "build"}, {"action": "test"}]
+        mock_proc.success_rate = 0.9
+        mock_proc.success_count = 9
+        mock_proc.failure_count = 1
+
+        mock_procedural = AsyncMock()
+        mock_procedural.find_matching = AsyncMock(return_value=[mock_proc])
+        mock_procedural_cls.create = AsyncMock(return_value=mock_procedural)
+
+        config = MemoryFetchConfig(
+            include_working=False,
+            include_episodic=False,
+            include_semantic=False,
+        )
+
+        result = await context_source.fetch_context(
+            query="deploy",
+            project_id=uuid4(),
+            config=config,
+        )
+
+        assert result.by_type["procedural"] == 1
+        assert result.contexts[0].memory_subtype == MemorySubtype.PROCEDURAL
+        assert "Deploy" in result.contexts[0].content
+
+    async def test_results_sorted_by_relevance(
+        self,
+        context_source: MemoryContextSource,
+    ) -> None:
+        """Results should be sorted by relevance score."""
+        with patch.object(
+            context_source, "_fetch_episodic"
+        ) as mock_ep, patch.object(
+            context_source, "_fetch_semantic"
+        ) as mock_sem:
+            # Create contexts with different relevance scores
+            from app.services.context.types.memory import MemoryContext
+
+            ctx_low = MemoryContext(
+                content="low relevance",
+                source="test",
+                relevance_score=0.3,
+            )
+            ctx_high = MemoryContext(
+                content="high relevance",
+                source="test",
+                relevance_score=0.9,
+            )
+
+            mock_ep.return_value = [ctx_low]
+            mock_sem.return_value = [ctx_high]
+
+            config = MemoryFetchConfig(
+                include_working=False,
+                include_procedural=False,
+            )
+
+            result = await context_source.fetch_context(
+                query="test",
+                project_id=uuid4(),
+                config=config,
+            )
+
+            # Higher relevance should come first
+            assert result.contexts[0].relevance_score == 0.9
+            assert result.contexts[1].relevance_score == 0.3
+
+    @patch("app.services.memory.integration.context_source.WorkingMemory")
+    async def test_fetch_all_working(
+        self,
+        mock_working_cls: MagicMock,
+        context_source: MemoryContextSource,
+    ) -> None:
+        """fetch_all_working should return all working memory items."""
+        mock_working = AsyncMock()
+        mock_working.list_keys = AsyncMock(return_value=["key1", "key2", "key3"])
+        mock_working.get = AsyncMock(return_value="value")
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        contexts = await context_source.fetch_all_working(
+            session_id="sess-123",
+            project_id=uuid4(),
+        )
+
+        assert len(contexts) == 3
+        assert all(c.memory_subtype == MemorySubtype.WORKING for c in contexts)
+
+
+class TestGetMemoryContextSource:
+    """Tests for factory function."""
+
+    async def test_creates_instance(self) -> None:
+        """Factory should create MemoryContextSource instance."""
+        mock_session = MagicMock()
+
+        source = await get_memory_context_source(mock_session)
+
+        assert isinstance(source, MemoryContextSource)

backend/tests/unit/services/memory/integration/test_lifecycle.py

@@ -0,0 +1,471 @@
+# tests/unit/services/memory/integration/test_lifecycle.py
+"""Tests for Agent Lifecycle Hooks."""
+
+from datetime import UTC, datetime
+from unittest.mock import AsyncMock, MagicMock, patch
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.integration.lifecycle import (
+    AgentLifecycleManager,
+    LifecycleEvent,
+    LifecycleHooks,
+    LifecycleResult,
+    get_lifecycle_manager,
+)
+from app.services.memory.types import Outcome
+
+pytestmark = pytest.mark.asyncio(loop_scope="function")
+
+
+@pytest.fixture
+def mock_session() -> MagicMock:
+    """Create mock database session."""
+    return MagicMock()
+
+
+@pytest.fixture
+def lifecycle_hooks() -> LifecycleHooks:
+    """Create lifecycle hooks instance."""
+    return LifecycleHooks()
+
+
+@pytest.fixture
+def lifecycle_manager(mock_session: MagicMock) -> AgentLifecycleManager:
+    """Create lifecycle manager instance."""
+    return AgentLifecycleManager(session=mock_session)
+
+
+class TestLifecycleEvent:
+    """Tests for LifecycleEvent dataclass."""
+
+    def test_creates_event(self) -> None:
+        """Should create event with required fields."""
+        project_id = uuid4()
+        agent_id = uuid4()
+
+        event = LifecycleEvent(
+            event_type="spawn",
+            project_id=project_id,
+            agent_instance_id=agent_id,
+        )
+
+        assert event.event_type == "spawn"
+        assert event.project_id == project_id
+        assert event.agent_instance_id == agent_id
+        assert event.timestamp is not None
+        assert event.metadata == {}
+
+    def test_with_optional_fields(self) -> None:
+        """Should include optional fields."""
+        event = LifecycleEvent(
+            event_type="terminate",
+            project_id=uuid4(),
+            agent_instance_id=uuid4(),
+            session_id="sess-123",
+            metadata={"reason": "completed"},
+        )
+
+        assert event.session_id == "sess-123"
+        assert event.metadata["reason"] == "completed"
+
+
+class TestLifecycleResult:
+    """Tests for LifecycleResult dataclass."""
+
+    def test_success_result(self) -> None:
+        """Should create success result."""
+        result = LifecycleResult(
+            success=True,
+            event_type="spawn",
+            message="Agent spawned",
+            data={"session_id": "sess-123"},
+            duration_ms=10.5,
+        )
+
+        assert result.success is True
+        assert result.event_type == "spawn"
+        assert result.data["session_id"] == "sess-123"
+
+    def test_failure_result(self) -> None:
+        """Should create failure result."""
+        result = LifecycleResult(
+            success=False,
+            event_type="resume",
+            message="Checkpoint not found",
+        )
+
+        assert result.success is False
+        assert result.message == "Checkpoint not found"
+
+
+class TestLifecycleHooks:
+    """Tests for LifecycleHooks class."""
+
+    def test_register_spawn_hook(self, lifecycle_hooks: LifecycleHooks) -> None:
+        """Should register spawn hook."""
+        async def my_hook(event: LifecycleEvent) -> None:
+            pass
+
+        result = lifecycle_hooks.on_spawn(my_hook)
+
+        assert result is my_hook
+        assert my_hook in lifecycle_hooks._spawn_hooks
+
+    def test_register_all_hooks(self, lifecycle_hooks: LifecycleHooks) -> None:
+        """Should register hooks for all event types."""
+        hooks = [
+            lifecycle_hooks.on_spawn(AsyncMock()),
+            lifecycle_hooks.on_pause(AsyncMock()),
+            lifecycle_hooks.on_resume(AsyncMock()),
+            lifecycle_hooks.on_terminate(AsyncMock()),
+        ]
+
+        assert len(lifecycle_hooks._spawn_hooks) == 1
+        assert len(lifecycle_hooks._pause_hooks) == 1
+        assert len(lifecycle_hooks._resume_hooks) == 1
+        assert len(lifecycle_hooks._terminate_hooks) == 1
+
+    async def test_run_spawn_hooks(self, lifecycle_hooks: LifecycleHooks) -> None:
+        """Should run all spawn hooks."""
+        hook1 = AsyncMock()
+        hook2 = AsyncMock()
+        lifecycle_hooks.on_spawn(hook1)
+        lifecycle_hooks.on_spawn(hook2)
+
+        event = LifecycleEvent(
+            event_type="spawn",
+            project_id=uuid4(),
+            agent_instance_id=uuid4(),
+        )
+
+        await lifecycle_hooks.run_spawn_hooks(event)
+
+        hook1.assert_called_once_with(event)
+        hook2.assert_called_once_with(event)
+
+    async def test_hook_failure_doesnt_stop_others(
+        self, lifecycle_hooks: LifecycleHooks
+    ) -> None:
+        """Hook failure should not stop other hooks from running."""
+        hook1 = AsyncMock(side_effect=ValueError("Oops"))
+        hook2 = AsyncMock()
+        lifecycle_hooks.on_pause(hook1)
+        lifecycle_hooks.on_pause(hook2)
+
+        event = LifecycleEvent(
+            event_type="pause",
+            project_id=uuid4(),
+            agent_instance_id=uuid4(),
+        )
+
+        await lifecycle_hooks.run_pause_hooks(event)
+
+        # hook2 should still be called even though hook1 failed
+        hook2.assert_called_once()
+
+
+class TestAgentLifecycleManagerSpawn:
+    """Tests for AgentLifecycleManager.spawn."""
+
+    @patch("app.services.memory.integration.lifecycle.WorkingMemory")
+    async def test_spawn_creates_working_memory(
+        self,
+        mock_working_cls: MagicMock,
+        lifecycle_manager: AgentLifecycleManager,
+    ) -> None:
+        """Spawn should create working memory for session."""
+        mock_working = AsyncMock()
+        mock_working.set = AsyncMock()
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        result = await lifecycle_manager.spawn(
+            project_id=uuid4(),
+            agent_instance_id=uuid4(),
+            session_id="sess-123",
+        )
+
+        assert result.success is True
+        assert result.event_type == "spawn"
+        mock_working_cls.for_session.assert_called_once()
+
+    @patch("app.services.memory.integration.lifecycle.WorkingMemory")
+    async def test_spawn_with_initial_state(
+        self,
+        mock_working_cls: MagicMock,
+        lifecycle_manager: AgentLifecycleManager,
+    ) -> None:
+        """Spawn should populate initial state."""
+        mock_working = AsyncMock()
+        mock_working.set = AsyncMock()
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        result = await lifecycle_manager.spawn(
+            project_id=uuid4(),
+            agent_instance_id=uuid4(),
+            session_id="sess-123",
+            initial_state={"key1": "value1", "key2": "value2"},
+        )
+
+        assert result.success is True
+        assert result.data["initial_items"] == 2
+        assert mock_working.set.call_count == 2
+
+    @patch("app.services.memory.integration.lifecycle.WorkingMemory")
+    async def test_spawn_runs_hooks(
+        self,
+        mock_working_cls: MagicMock,
+        lifecycle_manager: AgentLifecycleManager,
+    ) -> None:
+        """Spawn should run registered hooks."""
+        mock_working = AsyncMock()
+        mock_working.set = AsyncMock()
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        hook = AsyncMock()
+        lifecycle_manager.hooks.on_spawn(hook)
+
+        await lifecycle_manager.spawn(
+            project_id=uuid4(),
+            agent_instance_id=uuid4(),
+            session_id="sess-123",
+        )
+
+        hook.assert_called_once()
+
+
+class TestAgentLifecycleManagerPause:
+    """Tests for AgentLifecycleManager.pause."""
+
+    @patch("app.services.memory.integration.lifecycle.WorkingMemory")
+    async def test_pause_creates_checkpoint(
+        self,
+        mock_working_cls: MagicMock,
+        lifecycle_manager: AgentLifecycleManager,
+    ) -> None:
+        """Pause should create checkpoint of working memory."""
+        mock_working = AsyncMock()
+        mock_working.list_keys = AsyncMock(return_value=["key1", "key2"])
+        mock_working.get = AsyncMock(return_value={"data": "test"})
+        mock_working.set = AsyncMock()
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        result = await lifecycle_manager.pause(
+            project_id=uuid4(),
+            agent_instance_id=uuid4(),
+            session_id="sess-123",
+            checkpoint_id="ckpt-001",
+        )
+
+        assert result.success is True
+        assert result.event_type == "pause"
+        assert result.data["checkpoint_id"] == "ckpt-001"
+        assert result.data["items_saved"] == 2
+
+        # Should save checkpoint with state
+        mock_working.set.assert_called_once()
+        call_args = mock_working.set.call_args
+        # Check positional arg (first arg is key)
+        assert "__checkpoint__ckpt-001" in call_args[0][0]
+
+    @patch("app.services.memory.integration.lifecycle.WorkingMemory")
+    async def test_pause_generates_checkpoint_id(
+        self,
+        mock_working_cls: MagicMock,
+        lifecycle_manager: AgentLifecycleManager,
+    ) -> None:
+        """Pause should generate checkpoint ID if not provided."""
+        mock_working = AsyncMock()
+        mock_working.list_keys = AsyncMock(return_value=[])
+        mock_working.set = AsyncMock()
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        result = await lifecycle_manager.pause(
+            project_id=uuid4(),
+            agent_instance_id=uuid4(),
+            session_id="sess-123",
+        )
+
+        assert result.success is True
+        assert "checkpoint_id" in result.data
+        assert result.data["checkpoint_id"].startswith("checkpoint_")
+
+
+class TestAgentLifecycleManagerResume:
+    """Tests for AgentLifecycleManager.resume."""
+
+    @patch("app.services.memory.integration.lifecycle.WorkingMemory")
+    async def test_resume_restores_checkpoint(
+        self,
+        mock_working_cls: MagicMock,
+        lifecycle_manager: AgentLifecycleManager,
+    ) -> None:
+        """Resume should restore working memory from checkpoint."""
+        checkpoint_data = {
+            "state": {"key1": "value1", "key2": "value2"},
+            "timestamp": datetime.now(UTC).isoformat(),
+            "keys_count": 2,
+        }
+
+        mock_working = AsyncMock()
+        mock_working.list_keys = AsyncMock(return_value=[])
+        mock_working.get = AsyncMock(return_value=checkpoint_data)
+        mock_working.set = AsyncMock()
+        mock_working.delete = AsyncMock()
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        result = await lifecycle_manager.resume(
+            project_id=uuid4(),
+            agent_instance_id=uuid4(),
+            session_id="sess-123",
+            checkpoint_id="ckpt-001",
+        )
+
+        assert result.success is True
+        assert result.event_type == "resume"
+        assert result.data["items_restored"] == 2
+
+    @patch("app.services.memory.integration.lifecycle.WorkingMemory")
+    async def test_resume_checkpoint_not_found(
+        self,
+        mock_working_cls: MagicMock,
+        lifecycle_manager: AgentLifecycleManager,
+    ) -> None:
+        """Resume should fail if checkpoint not found."""
+        mock_working = AsyncMock()
+        mock_working.get = AsyncMock(return_value=None)
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        result = await lifecycle_manager.resume(
+            project_id=uuid4(),
+            agent_instance_id=uuid4(),
+            session_id="sess-123",
+            checkpoint_id="nonexistent",
+        )
+
+        assert result.success is False
+        assert "not found" in result.message.lower()
+
+
+class TestAgentLifecycleManagerTerminate:
+    """Tests for AgentLifecycleManager.terminate."""
+
+    @patch("app.services.memory.integration.lifecycle.EpisodicMemory")
+    @patch("app.services.memory.integration.lifecycle.WorkingMemory")
+    async def test_terminate_consolidates_to_episodic(
+        self,
+        mock_working_cls: MagicMock,
+        mock_episodic_cls: MagicMock,
+        lifecycle_manager: AgentLifecycleManager,
+    ) -> None:
+        """Terminate should consolidate working memory to episodic."""
+        mock_working = AsyncMock()
+        mock_working.list_keys = AsyncMock(return_value=["key1", "key2"])
+        mock_working.get = AsyncMock(return_value="value")
+        mock_working.delete = AsyncMock()
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        mock_episode = MagicMock()
+        mock_episode.id = uuid4()
+
+        mock_episodic = AsyncMock()
+        mock_episodic.record_episode = AsyncMock(return_value=mock_episode)
+        mock_episodic_cls.create = AsyncMock(return_value=mock_episodic)
+
+        result = await lifecycle_manager.terminate(
+            project_id=uuid4(),
+            agent_instance_id=uuid4(),
+            session_id="sess-123",
+            task_description="Completed task",
+            outcome=Outcome.SUCCESS,
+        )
+
+        assert result.success is True
+        assert result.event_type == "terminate"
+        assert result.data["episode_id"] == str(mock_episode.id)
+        assert result.data["state_items_consolidated"] == 2
+        mock_episodic.record_episode.assert_called_once()
+
+    @patch("app.services.memory.integration.lifecycle.WorkingMemory")
+    async def test_terminate_cleans_up_working(
+        self,
+        mock_working_cls: MagicMock,
+        lifecycle_manager: AgentLifecycleManager,
+    ) -> None:
+        """Terminate should clean up working memory."""
+        mock_working = AsyncMock()
+        mock_working.list_keys = AsyncMock(return_value=["key1", "key2"])
+        mock_working.get = AsyncMock(return_value="value")
+        mock_working.delete = AsyncMock()
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        result = await lifecycle_manager.terminate(
+            project_id=uuid4(),
+            agent_instance_id=uuid4(),
+            session_id="sess-123",
+            consolidate_to_episodic=False,
+            cleanup_working=True,
+        )
+
+        assert result.success is True
+        assert result.data["items_cleared"] == 2
+        assert mock_working.delete.call_count == 2
+
+
+class TestAgentLifecycleManagerListCheckpoints:
+    """Tests for AgentLifecycleManager.list_checkpoints."""
+
+    @patch("app.services.memory.integration.lifecycle.WorkingMemory")
+    async def test_list_checkpoints(
+        self,
+        mock_working_cls: MagicMock,
+        lifecycle_manager: AgentLifecycleManager,
+    ) -> None:
+        """Should list available checkpoints."""
+        mock_working = AsyncMock()
+        mock_working.list_keys = AsyncMock(
+            return_value=[
+                "__checkpoint__ckpt-001",
+                "__checkpoint__ckpt-002",
+                "regular_key",
+            ]
+        )
+        mock_working.get = AsyncMock(
+            return_value={
+                "timestamp": "2024-01-01T00:00:00Z",
+                "keys_count": 5,
+            }
+        )
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        checkpoints = await lifecycle_manager.list_checkpoints(
+            project_id=uuid4(),
+            agent_instance_id=uuid4(),
+            session_id="sess-123",
+        )
+
+        assert len(checkpoints) == 2
+        assert checkpoints[0]["checkpoint_id"] == "ckpt-001"
+        assert checkpoints[0]["keys_count"] == 5
+
+
+class TestGetLifecycleManager:
+    """Tests for factory function."""
+
+    async def test_creates_instance(self) -> None:
+        """Factory should create AgentLifecycleManager instance."""
+        mock_session = MagicMock()
+
+        manager = await get_lifecycle_manager(mock_session)
+
+        assert isinstance(manager, AgentLifecycleManager)
+
+    async def test_with_custom_hooks(self) -> None:
+        """Factory should accept custom hooks."""
+        mock_session = MagicMock()
+        custom_hooks = LifecycleHooks()
+
+        manager = await get_lifecycle_manager(mock_session, hooks=custom_hooks)
+
+        assert manager.hooks is custom_hooks

backend/tests/unit/services/memory/mcp/__init__.py

@@ -0,0 +1,2 @@
+# tests/unit/services/memory/mcp/__init__.py
+"""Tests for memory MCP tools."""

backend/tests/unit/services/memory/mcp/test_service.py

@@ -0,0 +1,651 @@
+# tests/unit/services/memory/mcp/test_service.py
+"""Tests for MemoryToolService."""
+
+from datetime import UTC, datetime
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+from uuid import UUID, uuid4
+
+import pytest
+
+from app.services.memory.mcp.service import (
+    MemoryToolService,
+    ToolContext,
+    ToolResult,
+    get_memory_tool_service,
+)
+from app.services.memory.mcp.tools import (
+    AnalysisType,
+    MemoryType,
+    OutcomeType,
+)
+from app.services.memory.types import Outcome
+
+pytestmark = pytest.mark.asyncio(loop_scope="function")
+
+
+def make_context(
+    project_id: UUID | None = None,
+    agent_instance_id: UUID | None = None,
+    session_id: str | None = None,
+) -> ToolContext:
+    """Create a test context."""
+    return ToolContext(
+        project_id=project_id or uuid4(),
+        agent_instance_id=agent_instance_id or uuid4(),
+        session_id=session_id or "test-session",
+    )
+
+
+def make_mock_session() -> AsyncMock:
+    """Create a mock database session."""
+    session = AsyncMock()
+    session.execute = AsyncMock()
+    session.commit = AsyncMock()
+    session.flush = AsyncMock()
+    return session
+
+
+class TestToolContext:
+    """Tests for ToolContext dataclass."""
+
+    def test_context_creation(self) -> None:
+        """Context should be creatable with required fields."""
+        project_id = uuid4()
+        ctx = ToolContext(project_id=project_id)
+        assert ctx.project_id == project_id
+        assert ctx.agent_instance_id is None
+        assert ctx.session_id is None
+
+    def test_context_with_all_fields(self) -> None:
+        """Context should accept all optional fields."""
+        project_id = uuid4()
+        agent_id = uuid4()
+        ctx = ToolContext(
+            project_id=project_id,
+            agent_instance_id=agent_id,
+            agent_type_id=uuid4(),
+            session_id="session-123",
+            user_id=uuid4(),
+        )
+        assert ctx.project_id == project_id
+        assert ctx.agent_instance_id == agent_id
+        assert ctx.session_id == "session-123"
+
+
+class TestToolResult:
+    """Tests for ToolResult dataclass."""
+
+    def test_success_result(self) -> None:
+        """Success result should have correct fields."""
+        result = ToolResult(
+            success=True,
+            data={"key": "value"},
+            execution_time_ms=10.5,
+        )
+        assert result.success is True
+        assert result.data == {"key": "value"}
+        assert result.error is None
+
+    def test_error_result(self) -> None:
+        """Error result should have correct fields."""
+        result = ToolResult(
+            success=False,
+            error="Something went wrong",
+            error_code="VALIDATION_ERROR",
+        )
+        assert result.success is False
+        assert result.error == "Something went wrong"
+        assert result.error_code == "VALIDATION_ERROR"
+
+    def test_to_dict(self) -> None:
+        """Result should convert to dict correctly."""
+        result = ToolResult(
+            success=True,
+            data={"test": 1},
+            execution_time_ms=5.0,
+        )
+        result_dict = result.to_dict()
+        assert result_dict["success"] is True
+        assert result_dict["data"] == {"test": 1}
+        assert result_dict["execution_time_ms"] == 5.0
+
+
+class TestMemoryToolService:
+    """Tests for MemoryToolService."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock session."""
+        return make_mock_session()
+
+    @pytest.fixture
+    def service(self, mock_session: AsyncMock) -> MemoryToolService:
+        """Create a service with mock session."""
+        return MemoryToolService(session=mock_session)
+
+    @pytest.fixture
+    def context(self) -> ToolContext:
+        """Create a test context."""
+        return make_context()
+
+    async def test_execute_unknown_tool(
+        self,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Unknown tool should return error."""
+        result = await service.execute_tool(
+            tool_name="unknown_tool",
+            arguments={},
+            context=context,
+        )
+        assert result.success is False
+        assert result.error_code == "UNKNOWN_TOOL"
+
+    async def test_execute_with_invalid_args(
+        self,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Invalid arguments should return validation error."""
+        result = await service.execute_tool(
+            tool_name="remember",
+            arguments={"memory_type": "invalid_type"},
+            context=context,
+        )
+        assert result.success is False
+        assert result.error_code == "VALIDATION_ERROR"
+
+    @patch("app.services.memory.mcp.service.WorkingMemory")
+    async def test_remember_working_memory(
+        self,
+        mock_working_cls: MagicMock,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Remember should store in working memory."""
+        # Setup mock
+        mock_working = AsyncMock()
+        mock_working.set = AsyncMock()
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        result = await service.execute_tool(
+            tool_name="remember",
+            arguments={
+                "memory_type": "working",
+                "content": "Test content",
+                "key": "test_key",
+                "ttl_seconds": 3600,
+            },
+            context=context,
+        )
+
+        assert result.success is True
+        assert result.data["stored"] is True
+        assert result.data["memory_type"] == "working"
+        assert result.data["key"] == "test_key"
+
+    async def test_remember_episodic_memory(
+        self,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Remember should store in episodic memory."""
+        with patch("app.services.memory.mcp.service.EpisodicMemory") as mock_episodic_cls:
+            # Setup mock
+            mock_episode = MagicMock()
+            mock_episode.id = uuid4()
+
+            mock_episodic = AsyncMock()
+            mock_episodic.record_episode = AsyncMock(return_value=mock_episode)
+            mock_episodic_cls.create = AsyncMock(return_value=mock_episodic)
+
+            result = await service.execute_tool(
+                tool_name="remember",
+                arguments={
+                    "memory_type": "episodic",
+                    "content": "Important event happened",
+                    "importance": 0.8,
+                },
+                context=context,
+            )
+
+            assert result.success is True
+            assert result.data["stored"] is True
+            assert result.data["memory_type"] == "episodic"
+            assert "episode_id" in result.data
+
+    async def test_remember_working_without_key(
+        self,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Working memory without key should fail."""
+        result = await service.execute_tool(
+            tool_name="remember",
+            arguments={
+                "memory_type": "working",
+                "content": "Test content",
+            },
+            context=context,
+        )
+
+        assert result.success is False
+        assert "key is required" in result.error.lower()
+
+    async def test_remember_working_without_session(
+        self,
+        service: MemoryToolService,
+    ) -> None:
+        """Working memory without session should fail."""
+        context = ToolContext(project_id=uuid4(), session_id=None)
+
+        result = await service.execute_tool(
+            tool_name="remember",
+            arguments={
+                "memory_type": "working",
+                "content": "Test content",
+                "key": "test_key",
+            },
+            context=context,
+        )
+
+        assert result.success is False
+        assert "session id is required" in result.error.lower()
+
+    async def test_remember_semantic_memory(
+        self,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Remember should store facts in semantic memory."""
+        with patch("app.services.memory.mcp.service.SemanticMemory") as mock_semantic_cls:
+            mock_fact = MagicMock()
+            mock_fact.id = uuid4()
+
+            mock_semantic = AsyncMock()
+            mock_semantic.store_fact = AsyncMock(return_value=mock_fact)
+            mock_semantic_cls.create = AsyncMock(return_value=mock_semantic)
+
+            result = await service.execute_tool(
+                tool_name="remember",
+                arguments={
+                    "memory_type": "semantic",
+                    "content": "User prefers dark mode",
+                    "subject": "User",
+                    "predicate": "prefers",
+                    "object_value": "dark mode",
+                },
+                context=context,
+            )
+
+            assert result.success is True
+            assert result.data["memory_type"] == "semantic"
+            assert "fact_id" in result.data
+            assert "triple" in result.data
+
+    async def test_remember_semantic_without_fields(
+        self,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Semantic memory without subject/predicate/object should fail."""
+        result = await service.execute_tool(
+            tool_name="remember",
+            arguments={
+                "memory_type": "semantic",
+                "content": "Some content",
+                "subject": "User",
+                # Missing predicate and object_value
+            },
+            context=context,
+        )
+
+        assert result.success is False
+        assert "required" in result.error.lower()
+
+    async def test_remember_procedural_memory(
+        self,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Remember should store procedures in procedural memory."""
+        with patch("app.services.memory.mcp.service.ProceduralMemory") as mock_procedural_cls:
+            mock_procedure = MagicMock()
+            mock_procedure.id = uuid4()
+
+            mock_procedural = AsyncMock()
+            mock_procedural.record_procedure = AsyncMock(return_value=mock_procedure)
+            mock_procedural_cls.create = AsyncMock(return_value=mock_procedural)
+
+            result = await service.execute_tool(
+                tool_name="remember",
+                arguments={
+                    "memory_type": "procedural",
+                    "content": "File creation procedure",
+                    "trigger": "When creating a new file",
+                    "steps": [
+                        {"action": "check_exists"},
+                        {"action": "create"},
+                    ],
+                },
+                context=context,
+            )
+
+            assert result.success is True
+            assert result.data["memory_type"] == "procedural"
+            assert "procedure_id" in result.data
+            assert result.data["steps_count"] == 2
+
+    @patch("app.services.memory.mcp.service.EpisodicMemory")
+    @patch("app.services.memory.mcp.service.SemanticMemory")
+    async def test_recall_from_multiple_types(
+        self,
+        mock_semantic_cls: MagicMock,
+        mock_episodic_cls: MagicMock,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Recall should search across multiple memory types."""
+        # Mock episodic
+        mock_episode = MagicMock()
+        mock_episode.id = uuid4()
+        mock_episode.task_description = "Test episode"
+        mock_episode.outcome = Outcome.SUCCESS
+        mock_episode.occurred_at = datetime.now(UTC)
+        mock_episode.importance_score = 0.9
+
+        mock_episodic = AsyncMock()
+        mock_episodic.search_similar = AsyncMock(return_value=[mock_episode])
+        mock_episodic_cls.create = AsyncMock(return_value=mock_episodic)
+
+        # Mock semantic
+        mock_fact = MagicMock()
+        mock_fact.id = uuid4()
+        mock_fact.subject = "User"
+        mock_fact.predicate = "prefers"
+        mock_fact.object = "dark mode"
+        mock_fact.confidence = 0.8
+
+        mock_semantic = AsyncMock()
+        mock_semantic.search_facts = AsyncMock(return_value=[mock_fact])
+        mock_semantic_cls.create = AsyncMock(return_value=mock_semantic)
+
+        result = await service.execute_tool(
+            tool_name="recall",
+            arguments={
+                "query": "user preferences",
+                "memory_types": ["episodic", "semantic"],
+                "limit": 10,
+            },
+            context=context,
+        )
+
+        assert result.success is True
+        assert result.data["total_results"] == 2
+        assert len(result.data["results"]) == 2
+
+    @patch("app.services.memory.mcp.service.WorkingMemory")
+    async def test_forget_working_memory(
+        self,
+        mock_working_cls: MagicMock,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Forget should delete from working memory."""
+        mock_working = AsyncMock()
+        mock_working.delete = AsyncMock(return_value=True)
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        result = await service.execute_tool(
+            tool_name="forget",
+            arguments={
+                "memory_type": "working",
+                "key": "temp_key",
+            },
+            context=context,
+        )
+
+        assert result.success is True
+        assert result.data["deleted"] is True
+        assert result.data["deleted_count"] == 1
+
+    async def test_forget_pattern_requires_confirm(
+        self,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Pattern deletion should require confirmation."""
+        with patch("app.services.memory.mcp.service.WorkingMemory") as mock_working_cls:
+            mock_working = AsyncMock()
+            mock_working.list_keys = AsyncMock(return_value=["cache_1", "cache_2"])
+            mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+            result = await service.execute_tool(
+                tool_name="forget",
+                arguments={
+                    "memory_type": "working",
+                    "pattern": "cache_*",
+                    "confirm_bulk": False,
+                },
+                context=context,
+            )
+
+            assert result.success is False
+            assert "confirm_bulk" in result.error.lower()
+
+    @patch("app.services.memory.mcp.service.EpisodicMemory")
+    async def test_reflect_recent_patterns(
+        self,
+        mock_episodic_cls: MagicMock,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Reflect should analyze recent patterns."""
+        # Create mock episodes
+        mock_episodes = []
+        for i in range(5):
+            ep = MagicMock()
+            ep.id = uuid4()
+            ep.task_type = "code_review" if i % 2 == 0 else "deployment"
+            ep.outcome = Outcome.SUCCESS if i < 3 else Outcome.FAILURE
+            ep.task_description = f"Episode {i}"
+            ep.lessons_learned = None
+            ep.occurred_at = datetime.now(UTC)
+            mock_episodes.append(ep)
+
+        mock_episodic = AsyncMock()
+        mock_episodic.get_recent = AsyncMock(return_value=mock_episodes)
+        mock_episodic_cls.create = AsyncMock(return_value=mock_episodic)
+
+        result = await service.execute_tool(
+            tool_name="reflect",
+            arguments={
+                "analysis_type": "recent_patterns",
+                "depth": 3,
+            },
+            context=context,
+        )
+
+        assert result.success is True
+        assert result.data["analysis_type"] == "recent_patterns"
+        assert result.data["total_episodes"] == 5
+        assert "top_task_types" in result.data
+        assert "outcome_distribution" in result.data
+
+    @patch("app.services.memory.mcp.service.EpisodicMemory")
+    async def test_reflect_success_factors(
+        self,
+        mock_episodic_cls: MagicMock,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Reflect should analyze success factors."""
+        mock_episodes = []
+        for i in range(10):
+            ep = MagicMock()
+            ep.id = uuid4()
+            ep.task_type = "code_review"
+            ep.outcome = Outcome.SUCCESS if i < 8 else Outcome.FAILURE
+            ep.task_description = f"Episode {i}"
+            ep.lessons_learned = "Learned something" if i < 3 else None
+            ep.occurred_at = datetime.now(UTC)
+            mock_episodes.append(ep)
+
+        mock_episodic = AsyncMock()
+        mock_episodic.get_recent = AsyncMock(return_value=mock_episodes)
+        mock_episodic_cls.create = AsyncMock(return_value=mock_episodic)
+
+        result = await service.execute_tool(
+            tool_name="reflect",
+            arguments={
+                "analysis_type": "success_factors",
+                "include_examples": True,
+            },
+            context=context,
+        )
+
+        assert result.success is True
+        assert result.data["analysis_type"] == "success_factors"
+        assert result.data["overall_success_rate"] == 0.8
+
+    @patch("app.services.memory.mcp.service.EpisodicMemory")
+    @patch("app.services.memory.mcp.service.SemanticMemory")
+    @patch("app.services.memory.mcp.service.ProceduralMemory")
+    @patch("app.services.memory.mcp.service.WorkingMemory")
+    async def test_get_memory_stats(
+        self,
+        mock_working_cls: MagicMock,
+        mock_procedural_cls: MagicMock,
+        mock_semantic_cls: MagicMock,
+        mock_episodic_cls: MagicMock,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Get memory stats should return statistics."""
+        # Setup mocks
+        mock_working = AsyncMock()
+        mock_working.list_keys = AsyncMock(return_value=["key1", "key2"])
+        mock_working_cls.for_session = AsyncMock(return_value=mock_working)
+
+        mock_episodic = AsyncMock()
+        mock_episodic.get_recent = AsyncMock(return_value=[MagicMock() for _ in range(10)])
+        mock_episodic_cls.create = AsyncMock(return_value=mock_episodic)
+
+        mock_semantic = AsyncMock()
+        mock_semantic.search_facts = AsyncMock(return_value=[MagicMock() for _ in range(5)])
+        mock_semantic_cls.create = AsyncMock(return_value=mock_semantic)
+
+        mock_procedural = AsyncMock()
+        mock_procedural.find_matching = AsyncMock(return_value=[MagicMock() for _ in range(3)])
+        mock_procedural_cls.create = AsyncMock(return_value=mock_procedural)
+
+        result = await service.execute_tool(
+            tool_name="get_memory_stats",
+            arguments={
+                "include_breakdown": True,
+                "include_recent_activity": False,
+            },
+            context=context,
+        )
+
+        assert result.success is True
+        assert "breakdown" in result.data
+        breakdown = result.data["breakdown"]
+        assert breakdown["working"] == 2
+        assert breakdown["episodic"] == 10
+        assert breakdown["semantic"] == 5
+        assert breakdown["procedural"] == 3
+        assert breakdown["total"] == 20
+
+    @patch("app.services.memory.mcp.service.ProceduralMemory")
+    async def test_search_procedures(
+        self,
+        mock_procedural_cls: MagicMock,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Search procedures should return matching procedures."""
+        mock_proc = MagicMock()
+        mock_proc.id = uuid4()
+        mock_proc.name = "Deployment procedure"
+        mock_proc.description = "How to deploy"
+        mock_proc.trigger = "When deploying"
+        mock_proc.success_rate = 0.9
+        mock_proc.execution_count = 10
+        mock_proc.steps = [{"action": "deploy"}]
+
+        mock_procedural = AsyncMock()
+        mock_procedural.find_matching = AsyncMock(return_value=[mock_proc])
+        mock_procedural_cls.create = AsyncMock(return_value=mock_procedural)
+
+        result = await service.execute_tool(
+            tool_name="search_procedures",
+            arguments={
+                "trigger": "Deploying to production",
+                "min_success_rate": 0.8,
+                "include_steps": True,
+            },
+            context=context,
+        )
+
+        assert result.success is True
+        assert result.data["procedures_found"] == 1
+        proc = result.data["procedures"][0]
+        assert proc["name"] == "Deployment procedure"
+        assert "steps" in proc
+
+    async def test_record_outcome(
+        self,
+        service: MemoryToolService,
+        context: ToolContext,
+    ) -> None:
+        """Record outcome should store outcome and update procedure."""
+        with (
+            patch("app.services.memory.mcp.service.EpisodicMemory") as mock_episodic_cls,
+            patch("app.services.memory.mcp.service.ProceduralMemory") as mock_procedural_cls,
+        ):
+            mock_episode = MagicMock()
+            mock_episode.id = uuid4()
+
+            mock_episodic = AsyncMock()
+            mock_episodic.record_episode = AsyncMock(return_value=mock_episode)
+            mock_episodic_cls.create = AsyncMock(return_value=mock_episodic)
+
+            mock_procedural = AsyncMock()
+            mock_procedural.record_outcome = AsyncMock()
+            mock_procedural_cls.create = AsyncMock(return_value=mock_procedural)
+
+            result = await service.execute_tool(
+                tool_name="record_outcome",
+                arguments={
+                    "task_type": "code_review",
+                    "outcome": "success",
+                    "lessons_learned": "Breaking changes caught early",
+                    "duration_seconds": 120.5,
+                },
+                context=context,
+            )
+
+            assert result.success is True
+            assert result.data["recorded"] is True
+            assert result.data["outcome"] == "success"
+            assert "episode_id" in result.data
+
+
+class TestGetMemoryToolService:
+    """Tests for get_memory_tool_service factory."""
+
+    async def test_creates_service(self) -> None:
+        """Factory should create a service."""
+        mock_session = make_mock_session()
+        service = await get_memory_tool_service(mock_session)
+        assert isinstance(service, MemoryToolService)
+
+    async def test_accepts_embedding_generator(self) -> None:
+        """Factory should accept embedding generator."""
+        mock_session = make_mock_session()
+        mock_generator = MagicMock()
+        service = await get_memory_tool_service(mock_session, mock_generator)
+        assert service._embedding_generator is mock_generator

backend/tests/unit/services/memory/mcp/test_tools.py

@@ -0,0 +1,420 @@
+# tests/unit/services/memory/mcp/test_tools.py
+"""Tests for MCP tool definitions."""
+
+import pytest
+from pydantic import ValidationError
+
+from app.services.memory.mcp.tools import (
+    MEMORY_TOOL_DEFINITIONS,
+    AnalysisType,
+    ForgetArgs,
+    GetMemoryStatsArgs,
+    MemoryToolDefinition,
+    MemoryType,
+    OutcomeType,
+    RecallArgs,
+    RecordOutcomeArgs,
+    ReflectArgs,
+    RememberArgs,
+    SearchProceduresArgs,
+    get_all_tool_schemas,
+    get_tool_definition,
+)
+
+
+class TestMemoryType:
+    """Tests for MemoryType enum."""
+
+    def test_all_types_defined(self) -> None:
+        """All memory types should be defined."""
+        assert MemoryType.WORKING == "working"
+        assert MemoryType.EPISODIC == "episodic"
+        assert MemoryType.SEMANTIC == "semantic"
+        assert MemoryType.PROCEDURAL == "procedural"
+
+    def test_enum_values(self) -> None:
+        """Enum values should match strings."""
+        assert MemoryType.WORKING.value == "working"
+        assert MemoryType("episodic") == MemoryType.EPISODIC
+
+
+class TestAnalysisType:
+    """Tests for AnalysisType enum."""
+
+    def test_all_types_defined(self) -> None:
+        """All analysis types should be defined."""
+        assert AnalysisType.RECENT_PATTERNS == "recent_patterns"
+        assert AnalysisType.SUCCESS_FACTORS == "success_factors"
+        assert AnalysisType.FAILURE_PATTERNS == "failure_patterns"
+        assert AnalysisType.COMMON_PROCEDURES == "common_procedures"
+        assert AnalysisType.LEARNING_PROGRESS == "learning_progress"
+
+
+class TestOutcomeType:
+    """Tests for OutcomeType enum."""
+
+    def test_all_outcomes_defined(self) -> None:
+        """All outcome types should be defined."""
+        assert OutcomeType.SUCCESS == "success"
+        assert OutcomeType.PARTIAL == "partial"
+        assert OutcomeType.FAILURE == "failure"
+        assert OutcomeType.ABANDONED == "abandoned"
+
+
+class TestRememberArgs:
+    """Tests for RememberArgs validation."""
+
+    def test_valid_working_memory_args(self) -> None:
+        """Valid working memory args should parse."""
+        args = RememberArgs(
+            memory_type=MemoryType.WORKING,
+            content="Test content",
+            key="test_key",
+            ttl_seconds=3600,
+        )
+        assert args.memory_type == MemoryType.WORKING
+        assert args.key == "test_key"
+        assert args.ttl_seconds == 3600
+
+    def test_valid_semantic_args(self) -> None:
+        """Valid semantic memory args should parse."""
+        args = RememberArgs(
+            memory_type=MemoryType.SEMANTIC,
+            content="User prefers dark mode",
+            subject="User",
+            predicate="prefers",
+            object_value="dark mode",
+        )
+        assert args.subject == "User"
+        assert args.predicate == "prefers"
+        assert args.object_value == "dark mode"
+
+    def test_valid_procedural_args(self) -> None:
+        """Valid procedural memory args should parse."""
+        args = RememberArgs(
+            memory_type=MemoryType.PROCEDURAL,
+            content="File creation procedure",
+            trigger="When creating a new file",
+            steps=[{"action": "check_exists"}, {"action": "create"}],
+        )
+        assert args.trigger == "When creating a new file"
+        assert len(args.steps) == 2
+
+    def test_importance_validation(self) -> None:
+        """Importance must be between 0 and 1."""
+        args = RememberArgs(
+            memory_type=MemoryType.WORKING,
+            content="Test",
+            importance=0.8,
+        )
+        assert args.importance == 0.8
+
+        with pytest.raises(ValidationError):
+            RememberArgs(
+                memory_type=MemoryType.WORKING,
+                content="Test",
+                importance=1.5,  # Invalid
+            )
+
+        with pytest.raises(ValidationError):
+            RememberArgs(
+                memory_type=MemoryType.WORKING,
+                content="Test",
+                importance=-0.1,  # Invalid
+            )
+
+    def test_content_required(self) -> None:
+        """Content is required."""
+        with pytest.raises(ValidationError):
+            RememberArgs(
+                memory_type=MemoryType.WORKING,
+                content="",  # Empty not allowed
+            )
+
+    def test_ttl_validation(self) -> None:
+        """TTL must be within bounds."""
+        with pytest.raises(ValidationError):
+            RememberArgs(
+                memory_type=MemoryType.WORKING,
+                content="Test",
+                ttl_seconds=0,  # Too low
+            )
+
+        with pytest.raises(ValidationError):
+            RememberArgs(
+                memory_type=MemoryType.WORKING,
+                content="Test",
+                ttl_seconds=86400 * 31,  # Over 30 days
+            )
+
+    def test_default_values(self) -> None:
+        """Default values should be set correctly."""
+        args = RememberArgs(
+            memory_type=MemoryType.WORKING,
+            content="Test",
+        )
+        assert args.importance == 0.5
+        assert args.ttl_seconds is None
+        assert args.metadata == {}
+        assert args.key is None
+
+
+class TestRecallArgs:
+    """Tests for RecallArgs validation."""
+
+    def test_valid_args(self) -> None:
+        """Valid recall args should parse."""
+        args = RecallArgs(
+            query="authentication errors",
+            memory_types=[MemoryType.EPISODIC, MemoryType.SEMANTIC],
+            limit=10,
+        )
+        assert args.query == "authentication errors"
+        assert len(args.memory_types) == 2
+        assert args.limit == 10
+
+    def test_default_memory_types(self) -> None:
+        """Default memory types should be episodic and semantic."""
+        args = RecallArgs(query="test query")
+        assert MemoryType.EPISODIC in args.memory_types
+        assert MemoryType.SEMANTIC in args.memory_types
+
+    def test_limit_validation(self) -> None:
+        """Limit must be between 1 and 100."""
+        with pytest.raises(ValidationError):
+            RecallArgs(query="test", limit=0)
+
+        with pytest.raises(ValidationError):
+            RecallArgs(query="test", limit=101)
+
+    def test_min_relevance_validation(self) -> None:
+        """Min relevance must be between 0 and 1."""
+        args = RecallArgs(query="test", min_relevance=0.5)
+        assert args.min_relevance == 0.5
+
+        with pytest.raises(ValidationError):
+            RecallArgs(query="test", min_relevance=1.5)
+
+
+class TestForgetArgs:
+    """Tests for ForgetArgs validation."""
+
+    def test_valid_key_deletion(self) -> None:
+        """Valid key deletion args should parse."""
+        args = ForgetArgs(
+            memory_type=MemoryType.WORKING,
+            key="temp_key",
+        )
+        assert args.memory_type == MemoryType.WORKING
+        assert args.key == "temp_key"
+
+    def test_valid_id_deletion(self) -> None:
+        """Valid ID deletion args should parse."""
+        args = ForgetArgs(
+            memory_type=MemoryType.EPISODIC,
+            memory_id="12345678-1234-1234-1234-123456789012",
+        )
+        assert args.memory_id is not None
+
+    def test_pattern_deletion_requires_confirm(self) -> None:
+        """Pattern deletion should parse but service should validate confirm."""
+        args = ForgetArgs(
+            memory_type=MemoryType.WORKING,
+            pattern="cache_*",
+            confirm_bulk=False,
+        )
+        assert args.pattern == "cache_*"
+        assert args.confirm_bulk is False
+
+
+class TestReflectArgs:
+    """Tests for ReflectArgs validation."""
+
+    def test_valid_args(self) -> None:
+        """Valid reflect args should parse."""
+        args = ReflectArgs(
+            analysis_type=AnalysisType.SUCCESS_FACTORS,
+            depth=3,
+        )
+        assert args.analysis_type == AnalysisType.SUCCESS_FACTORS
+        assert args.depth == 3
+
+    def test_depth_validation(self) -> None:
+        """Depth must be between 1 and 5."""
+        with pytest.raises(ValidationError):
+            ReflectArgs(analysis_type=AnalysisType.SUCCESS_FACTORS, depth=0)
+
+        with pytest.raises(ValidationError):
+            ReflectArgs(analysis_type=AnalysisType.SUCCESS_FACTORS, depth=6)
+
+    def test_default_values(self) -> None:
+        """Default values should be set correctly."""
+        args = ReflectArgs(analysis_type=AnalysisType.RECENT_PATTERNS)
+        assert args.depth == 3
+        assert args.include_examples is True
+        assert args.max_items == 10
+
+
+class TestGetMemoryStatsArgs:
+    """Tests for GetMemoryStatsArgs validation."""
+
+    def test_valid_args(self) -> None:
+        """Valid args should parse."""
+        args = GetMemoryStatsArgs(
+            include_breakdown=True,
+            include_recent_activity=True,
+            time_range_days=30,
+        )
+        assert args.include_breakdown is True
+        assert args.time_range_days == 30
+
+    def test_time_range_validation(self) -> None:
+        """Time range must be between 1 and 90."""
+        with pytest.raises(ValidationError):
+            GetMemoryStatsArgs(time_range_days=0)
+
+        with pytest.raises(ValidationError):
+            GetMemoryStatsArgs(time_range_days=91)
+
+
+class TestSearchProceduresArgs:
+    """Tests for SearchProceduresArgs validation."""
+
+    def test_valid_args(self) -> None:
+        """Valid args should parse."""
+        args = SearchProceduresArgs(
+            trigger="Deploying to production",
+            min_success_rate=0.8,
+            limit=5,
+        )
+        assert args.trigger == "Deploying to production"
+        assert args.min_success_rate == 0.8
+
+    def test_trigger_required(self) -> None:
+        """Trigger is required."""
+        with pytest.raises(ValidationError):
+            SearchProceduresArgs(trigger="")
+
+    def test_success_rate_validation(self) -> None:
+        """Success rate must be between 0 and 1."""
+        with pytest.raises(ValidationError):
+            SearchProceduresArgs(trigger="test", min_success_rate=1.5)
+
+
+class TestRecordOutcomeArgs:
+    """Tests for RecordOutcomeArgs validation."""
+
+    def test_valid_success_args(self) -> None:
+        """Valid success args should parse."""
+        args = RecordOutcomeArgs(
+            task_type="code_review",
+            outcome=OutcomeType.SUCCESS,
+            lessons_learned="Breaking changes caught early",
+        )
+        assert args.task_type == "code_review"
+        assert args.outcome == OutcomeType.SUCCESS
+
+    def test_valid_failure_args(self) -> None:
+        """Valid failure args should parse."""
+        args = RecordOutcomeArgs(
+            task_type="deployment",
+            outcome=OutcomeType.FAILURE,
+            error_details="Database migration timeout",
+            duration_seconds=120.5,
+        )
+        assert args.outcome == OutcomeType.FAILURE
+        assert args.error_details is not None
+
+    def test_task_type_required(self) -> None:
+        """Task type is required."""
+        with pytest.raises(ValidationError):
+            RecordOutcomeArgs(task_type="", outcome=OutcomeType.SUCCESS)
+
+
+class TestMemoryToolDefinition:
+    """Tests for MemoryToolDefinition class."""
+
+    def test_to_mcp_format(self) -> None:
+        """Tool should convert to MCP format."""
+        tool = MemoryToolDefinition(
+            name="test_tool",
+            description="A test tool",
+            args_schema=RememberArgs,
+        )
+
+        mcp_format = tool.to_mcp_format()
+
+        assert mcp_format["name"] == "test_tool"
+        assert mcp_format["description"] == "A test tool"
+        assert "inputSchema" in mcp_format
+        assert "properties" in mcp_format["inputSchema"]
+
+    def test_validate_args(self) -> None:
+        """Tool should validate args using schema."""
+        tool = MemoryToolDefinition(
+            name="remember",
+            description="Store in memory",
+            args_schema=RememberArgs,
+        )
+
+        # Valid args
+        validated = tool.validate_args({
+            "memory_type": "working",
+            "content": "Test content",
+        })
+        assert isinstance(validated, RememberArgs)
+
+        # Invalid args
+        with pytest.raises(ValidationError):
+            tool.validate_args({"memory_type": "invalid"})
+
+
+class TestToolDefinitions:
+    """Tests for the tool definitions dictionary."""
+
+    def test_all_tools_defined(self) -> None:
+        """All expected tools should be defined."""
+        expected_tools = [
+            "remember",
+            "recall",
+            "forget",
+            "reflect",
+            "get_memory_stats",
+            "search_procedures",
+            "record_outcome",
+        ]
+
+        for tool_name in expected_tools:
+            assert tool_name in MEMORY_TOOL_DEFINITIONS
+            assert isinstance(MEMORY_TOOL_DEFINITIONS[tool_name], MemoryToolDefinition)
+
+    def test_get_tool_definition(self) -> None:
+        """get_tool_definition should return correct tool."""
+        tool = get_tool_definition("remember")
+        assert tool is not None
+        assert tool.name == "remember"
+
+        unknown = get_tool_definition("unknown_tool")
+        assert unknown is None
+
+    def test_get_all_tool_schemas(self) -> None:
+        """get_all_tool_schemas should return MCP-formatted schemas."""
+        schemas = get_all_tool_schemas()
+
+        assert len(schemas) == 7
+        for schema in schemas:
+            assert "name" in schema
+            assert "description" in schema
+            assert "inputSchema" in schema
+
+    def test_tool_descriptions_not_empty(self) -> None:
+        """All tools should have descriptions."""
+        for name, tool in MEMORY_TOOL_DEFINITIONS.items():
+            assert tool.description, f"Tool {name} has empty description"
+            assert len(tool.description) > 50, f"Tool {name} description too short"
+
+    def test_input_schemas_have_properties(self) -> None:
+        """All tool schemas should have properties defined."""
+        for name, tool in MEMORY_TOOL_DEFINITIONS.items():
+            schema = tool.to_mcp_format()
+            assert "properties" in schema["inputSchema"], f"Tool {name} missing properties"

backend/tests/unit/services/memory/procedural/__init__.py

@@ -0,0 +1,2 @@
+# tests/unit/services/memory/procedural/__init__.py
+"""Unit tests for procedural memory."""

backend/tests/unit/services/memory/procedural/test_matching.py

@@ -0,0 +1,427 @@
+# tests/unit/services/memory/procedural/test_matching.py
+"""Unit tests for procedure matching."""
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.procedural.matching import (
+    MatchContext,
+    MatchResult,
+    ProcedureMatcher,
+    get_procedure_matcher,
+)
+from app.services.memory.types import Procedure
+
+
+def create_test_procedure(
+    name: str = "deploy_api",
+    trigger_pattern: str = "deploy.*api",
+    success_count: int = 8,
+    failure_count: int = 2,
+) -> Procedure:
+    """Create a test procedure for testing."""
+    now = datetime.now(UTC)
+    return Procedure(
+        id=uuid4(),
+        project_id=None,
+        agent_type_id=None,
+        name=name,
+        trigger_pattern=trigger_pattern,
+        steps=[
+            {"order": 1, "action": "build"},
+            {"order": 2, "action": "test"},
+            {"order": 3, "action": "deploy"},
+        ],
+        success_count=success_count,
+        failure_count=failure_count,
+        last_used=now,
+        embedding=None,
+        created_at=now,
+        updated_at=now,
+    )
+
+
+class TestMatchResult:
+    """Tests for MatchResult dataclass."""
+
+    def test_to_dict(self) -> None:
+        """Test converting match result to dictionary."""
+        procedure = create_test_procedure()
+        result = MatchResult(
+            procedure=procedure,
+            score=0.85,
+            matched_terms=["deploy", "api"],
+            match_type="keyword",
+        )
+
+        data = result.to_dict()
+
+        assert "procedure_id" in data
+        assert "procedure_name" in data
+        assert data["score"] == 0.85
+        assert data["matched_terms"] == ["deploy", "api"]
+        assert data["match_type"] == "keyword"
+        assert data["success_rate"] == 0.8
+
+
+class TestMatchContext:
+    """Tests for MatchContext dataclass."""
+
+    def test_default_values(self) -> None:
+        """Test default values."""
+        context = MatchContext(query="deploy api")
+
+        assert context.query == "deploy api"
+        assert context.task_type is None
+        assert context.project_id is None
+        assert context.max_results == 5
+        assert context.min_score == 0.3
+        assert context.require_success_rate is None
+
+    def test_with_all_values(self) -> None:
+        """Test with all values set."""
+        project_id = uuid4()
+        context = MatchContext(
+            query="deploy api",
+            task_type="deployment",
+            project_id=project_id,
+            max_results=10,
+            min_score=0.5,
+            require_success_rate=0.7,
+        )
+
+        assert context.query == "deploy api"
+        assert context.task_type == "deployment"
+        assert context.project_id == project_id
+        assert context.max_results == 10
+        assert context.min_score == 0.5
+        assert context.require_success_rate == 0.7
+
+
+class TestProcedureMatcher:
+    """Tests for ProcedureMatcher class."""
+
+    @pytest.fixture
+    def matcher(self) -> ProcedureMatcher:
+        """Create a procedure matcher."""
+        return ProcedureMatcher()
+
+    @pytest.fixture
+    def procedures(self) -> list[Procedure]:
+        """Create test procedures."""
+        return [
+            create_test_procedure(
+                name="deploy_api",
+                trigger_pattern="deploy.*api",
+                success_count=9,
+                failure_count=1,
+            ),
+            create_test_procedure(
+                name="deploy_frontend",
+                trigger_pattern="deploy.*frontend",
+                success_count=7,
+                failure_count=3,
+            ),
+            create_test_procedure(
+                name="build_project",
+                trigger_pattern="build.*project",
+                success_count=8,
+                failure_count=2,
+            ),
+            create_test_procedure(
+                name="run_tests",
+                trigger_pattern="test.*run",
+                success_count=5,
+                failure_count=5,
+            ),
+        ]
+
+    def test_match_exact_name(
+        self,
+        matcher: ProcedureMatcher,
+        procedures: list[Procedure],
+    ) -> None:
+        """Test matching with exact name."""
+        context = MatchContext(query="deploy_api")
+
+        results = matcher.match(procedures, context)
+
+        assert len(results) > 0
+        # First result should be deploy_api
+        assert results[0].procedure.name == "deploy_api"
+
+    def test_match_partial_terms(
+        self,
+        matcher: ProcedureMatcher,
+        procedures: list[Procedure],
+    ) -> None:
+        """Test matching with partial terms."""
+        context = MatchContext(query="deploy")
+
+        results = matcher.match(procedures, context)
+
+        assert len(results) >= 2
+        # Both deploy procedures should match
+        names = [r.procedure.name for r in results]
+        assert "deploy_api" in names
+        assert "deploy_frontend" in names
+
+    def test_match_with_task_type(
+        self,
+        matcher: ProcedureMatcher,
+        procedures: list[Procedure],
+    ) -> None:
+        """Test matching with task type."""
+        context = MatchContext(
+            query="build something",
+            task_type="build",
+        )
+
+        results = matcher.match(procedures, context)
+
+        assert len(results) > 0
+        assert results[0].procedure.name == "build_project"
+
+    def test_match_respects_min_score(
+        self,
+        matcher: ProcedureMatcher,
+        procedures: list[Procedure],
+    ) -> None:
+        """Test that matching respects minimum score."""
+        context = MatchContext(
+            query="completely unrelated query xyz",
+            min_score=0.5,
+        )
+
+        results = matcher.match(procedures, context)
+
+        # Should not match anything with high min_score
+        for result in results:
+            assert result.score >= 0.5
+
+    def test_match_respects_success_rate_requirement(
+        self,
+        matcher: ProcedureMatcher,
+        procedures: list[Procedure],
+    ) -> None:
+        """Test that matching respects success rate requirement."""
+        context = MatchContext(
+            query="deploy",
+            require_success_rate=0.7,
+        )
+
+        results = matcher.match(procedures, context)
+
+        for result in results:
+            assert result.procedure.success_rate >= 0.7
+
+    def test_match_respects_max_results(
+        self,
+        matcher: ProcedureMatcher,
+        procedures: list[Procedure],
+    ) -> None:
+        """Test that matching respects max results."""
+        context = MatchContext(
+            query="deploy",
+            max_results=1,
+            min_score=0.0,
+        )
+
+        results = matcher.match(procedures, context)
+
+        assert len(results) <= 1
+
+    def test_match_sorts_by_score(
+        self,
+        matcher: ProcedureMatcher,
+        procedures: list[Procedure],
+    ) -> None:
+        """Test that results are sorted by score."""
+        context = MatchContext(query="deploy", min_score=0.0)
+
+        results = matcher.match(procedures, context)
+
+        if len(results) > 1:
+            scores = [r.score for r in results]
+            assert scores == sorted(scores, reverse=True)
+
+    def test_match_empty_procedures(
+        self,
+        matcher: ProcedureMatcher,
+    ) -> None:
+        """Test matching with empty procedures list."""
+        context = MatchContext(query="deploy")
+
+        results = matcher.match([], context)
+
+        assert results == []
+
+
+class TestProcedureMatcherRankByRelevance:
+    """Tests for rank_by_relevance method."""
+
+    @pytest.fixture
+    def matcher(self) -> ProcedureMatcher:
+        """Create a procedure matcher."""
+        return ProcedureMatcher()
+
+    def test_rank_by_relevance(
+        self,
+        matcher: ProcedureMatcher,
+    ) -> None:
+        """Test ranking by relevance."""
+        procedures = [
+            create_test_procedure(name="unrelated", trigger_pattern="something else"),
+            create_test_procedure(name="deploy_api", trigger_pattern="deploy.*api"),
+            create_test_procedure(
+                name="deploy_frontend", trigger_pattern="deploy.*frontend"
+            ),
+        ]
+
+        ranked = matcher.rank_by_relevance(procedures, "deploy")
+
+        # Deploy procedures should be ranked first
+        assert ranked[0].name in ["deploy_api", "deploy_frontend"]
+
+    def test_rank_by_relevance_empty(
+        self,
+        matcher: ProcedureMatcher,
+    ) -> None:
+        """Test ranking empty list."""
+        ranked = matcher.rank_by_relevance([], "deploy")
+
+        assert ranked == []
+
+
+class TestProcedureMatcherSuggestProcedures:
+    """Tests for suggest_procedures method."""
+
+    @pytest.fixture
+    def matcher(self) -> ProcedureMatcher:
+        """Create a procedure matcher."""
+        return ProcedureMatcher()
+
+    @pytest.fixture
+    def procedures(self) -> list[Procedure]:
+        """Create test procedures."""
+        return [
+            create_test_procedure(
+                name="deploy_api",
+                trigger_pattern="deploy api",
+                success_count=9,
+                failure_count=1,
+            ),
+            create_test_procedure(
+                name="bad_deploy",
+                trigger_pattern="deploy bad",
+                success_count=2,
+                failure_count=8,
+            ),
+        ]
+
+    def test_suggest_procedures(
+        self,
+        matcher: ProcedureMatcher,
+        procedures: list[Procedure],
+    ) -> None:
+        """Test suggesting procedures."""
+        suggestions = matcher.suggest_procedures(
+            procedures,
+            "deploy",
+            min_success_rate=0.5,
+        )
+
+        assert len(suggestions) > 0
+        # Only high success rate should be suggested
+        for s in suggestions:
+            assert s.procedure.success_rate >= 0.5
+
+    def test_suggest_procedures_limits_results(
+        self,
+        matcher: ProcedureMatcher,
+        procedures: list[Procedure],
+    ) -> None:
+        """Test that suggestions are limited."""
+        suggestions = matcher.suggest_procedures(
+            procedures,
+            "deploy",
+            max_suggestions=1,
+        )
+
+        assert len(suggestions) <= 1
+
+
+class TestGetProcedureMatcher:
+    """Tests for singleton getter."""
+
+    def test_get_procedure_matcher_returns_instance(self) -> None:
+        """Test that getter returns instance."""
+        matcher = get_procedure_matcher()
+
+        assert matcher is not None
+        assert isinstance(matcher, ProcedureMatcher)
+
+    def test_get_procedure_matcher_returns_same_instance(self) -> None:
+        """Test that getter returns same instance (singleton)."""
+        matcher1 = get_procedure_matcher()
+        matcher2 = get_procedure_matcher()
+
+        assert matcher1 is matcher2
+
+
+class TestProcedureMatcherExtractTerms:
+    """Tests for term extraction."""
+
+    @pytest.fixture
+    def matcher(self) -> ProcedureMatcher:
+        """Create a procedure matcher."""
+        return ProcedureMatcher()
+
+    def test_extract_terms_basic(
+        self,
+        matcher: ProcedureMatcher,
+    ) -> None:
+        """Test basic term extraction."""
+        terms = matcher._extract_terms("deploy the api")
+
+        assert "deploy" in terms
+        assert "the" in terms
+        assert "api" in terms
+
+    def test_extract_terms_removes_special_chars(
+        self,
+        matcher: ProcedureMatcher,
+    ) -> None:
+        """Test that special characters are removed."""
+        terms = matcher._extract_terms("deploy.api!now")
+
+        assert "deploy" in terms
+        assert "api" in terms
+        assert "now" in terms
+        assert "." not in terms
+        assert "!" not in terms
+
+    def test_extract_terms_filters_short(
+        self,
+        matcher: ProcedureMatcher,
+    ) -> None:
+        """Test that short terms are filtered."""
+        terms = matcher._extract_terms("a big api")
+
+        assert "a" not in terms
+        assert "big" in terms
+        assert "api" in terms
+
+    def test_extract_terms_lowercases(
+        self,
+        matcher: ProcedureMatcher,
+    ) -> None:
+        """Test that terms are lowercased."""
+        terms = matcher._extract_terms("Deploy API")
+
+        assert "deploy" in terms
+        assert "api" in terms
+        assert "Deploy" not in terms
+        assert "API" not in terms

backend/tests/unit/services/memory/procedural/test_memory.py

@@ -0,0 +1,569 @@
+# tests/unit/services/memory/procedural/test_memory.py
+"""Unit tests for ProceduralMemory class."""
+
+from datetime import UTC, datetime
+from unittest.mock import AsyncMock, MagicMock
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.procedural.memory import ProceduralMemory
+from app.services.memory.types import ProcedureCreate, Step
+
+
+def create_mock_procedure_model(
+    name="deploy_api",
+    trigger_pattern="deploy.*api",
+    project_id=None,
+    agent_type_id=None,
+    success_count=5,
+    failure_count=1,
+):
+    """Create a mock procedure model for testing."""
+    mock = MagicMock()
+    mock.id = uuid4()
+    mock.project_id = project_id
+    mock.agent_type_id = agent_type_id
+    mock.name = name
+    mock.trigger_pattern = trigger_pattern
+    mock.steps = [
+        {"order": 1, "action": "build", "parameters": {}},
+        {"order": 2, "action": "test", "parameters": {}},
+        {"order": 3, "action": "deploy", "parameters": {}},
+    ]
+    mock.success_count = success_count
+    mock.failure_count = failure_count
+    mock.last_used = datetime.now(UTC)
+    mock.embedding = None
+    mock.created_at = datetime.now(UTC)
+    mock.updated_at = datetime.now(UTC)
+    mock.success_rate = (
+        success_count / (success_count + failure_count)
+        if (success_count + failure_count) > 0
+        else 0.0
+    )
+    mock.total_uses = success_count + failure_count
+    return mock
+
+
+class TestProceduralMemoryInit:
+    """Tests for ProceduralMemory initialization."""
+
+    def test_init_creates_memory(self) -> None:
+        """Test that init creates memory instance."""
+        mock_session = AsyncMock()
+        memory = ProceduralMemory(session=mock_session)
+
+        assert memory._session is mock_session
+
+    def test_init_with_embedding_generator(self) -> None:
+        """Test init with embedding generator."""
+        mock_session = AsyncMock()
+        mock_embedding_gen = AsyncMock()
+        memory = ProceduralMemory(
+            session=mock_session, embedding_generator=mock_embedding_gen
+        )
+
+        assert memory._embedding_generator is mock_embedding_gen
+
+    @pytest.mark.asyncio
+    async def test_create_factory_method(self) -> None:
+        """Test create factory method."""
+        mock_session = AsyncMock()
+        memory = await ProceduralMemory.create(session=mock_session)
+
+        assert memory is not None
+        assert memory._session is mock_session
+
+
+class TestProceduralMemoryRecordProcedure:
+    """Tests for procedure recording methods."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        session.add = MagicMock()
+        session.flush = AsyncMock()
+        session.refresh = AsyncMock()
+        # Mock no existing procedure found
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        session.execute.return_value = mock_result
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> ProceduralMemory:
+        """Create a ProceduralMemory instance."""
+        return ProceduralMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_record_new_procedure(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test recording a new procedure."""
+        procedure_data = ProcedureCreate(
+            name="build_project",
+            trigger_pattern="build.*project",
+            steps=[
+                {"order": 1, "action": "npm install"},
+                {"order": 2, "action": "npm run build"},
+            ],
+            project_id=uuid4(),
+        )
+
+        result = await memory.record_procedure(procedure_data)
+
+        assert result.name == "build_project"
+        assert result.trigger_pattern == "build.*project"
+        mock_session.add.assert_called_once()
+        mock_session.flush.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_record_updates_existing(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test that recording duplicate procedure updates existing."""
+        # Mock existing procedure found
+        existing_mock = create_mock_procedure_model()
+        find_result = MagicMock()
+        find_result.scalar_one_or_none.return_value = existing_mock
+
+        # Mock update result
+        updated_mock = create_mock_procedure_model(success_count=6)
+        update_result = MagicMock()
+        update_result.scalar_one.return_value = updated_mock
+
+        mock_session.execute.side_effect = [find_result, update_result]
+
+        procedure_data = ProcedureCreate(
+            name="deploy_api",
+            trigger_pattern="deploy.*api",
+            steps=[{"order": 1, "action": "deploy"}],
+        )
+
+        _ = await memory.record_procedure(procedure_data)
+
+        # Should have called execute twice (find + update)
+        assert mock_session.execute.call_count == 2
+
+
+class TestProceduralMemoryFindMatching:
+    """Tests for procedure matching methods."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        session.execute.return_value = mock_result
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> ProceduralMemory:
+        """Create a ProceduralMemory instance."""
+        return ProceduralMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_find_matching(
+        self,
+        memory: ProceduralMemory,
+    ) -> None:
+        """Test finding matching procedures."""
+        results = await memory.find_matching("deploy api")
+
+        assert isinstance(results, list)
+
+    @pytest.mark.asyncio
+    async def test_find_matching_with_project_filter(
+        self,
+        memory: ProceduralMemory,
+    ) -> None:
+        """Test finding matching procedures with project filter."""
+        project_id = uuid4()
+        results = await memory.find_matching(
+            "deploy api",
+            project_id=project_id,
+        )
+
+        assert isinstance(results, list)
+
+    @pytest.mark.asyncio
+    async def test_find_matching_returns_results(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test that find_matching returns results."""
+        procedures = [
+            create_mock_procedure_model(name="deploy_api"),
+            create_mock_procedure_model(name="deploy_frontend"),
+        ]
+
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = procedures
+        mock_session.execute.return_value = mock_result
+
+        results = await memory.find_matching("deploy")
+
+        assert len(results) == 2
+
+
+class TestProceduralMemoryGetBestProcedure:
+    """Tests for get_best_procedure method."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> ProceduralMemory:
+        """Create a ProceduralMemory instance."""
+        return ProceduralMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_get_best_procedure_none(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test get_best_procedure returns None when no match."""
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        mock_session.execute.return_value = mock_result
+
+        result = await memory.get_best_procedure("unknown_task")
+
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_get_best_procedure_returns_highest_success_rate(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test get_best_procedure returns highest success rate."""
+        low_success = create_mock_procedure_model(
+            name="deploy_v1", success_count=3, failure_count=7
+        )
+        high_success = create_mock_procedure_model(
+            name="deploy_v2", success_count=9, failure_count=1
+        )
+
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = [high_success, low_success]
+        mock_session.execute.return_value = mock_result
+
+        result = await memory.get_best_procedure("deploy")
+
+        assert result is not None
+        assert result.name == "deploy_v2"
+
+
+class TestProceduralMemoryRecordOutcome:
+    """Tests for outcome recording."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> ProceduralMemory:
+        """Create a ProceduralMemory instance."""
+        return ProceduralMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_record_outcome_success(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test recording a successful outcome."""
+        existing_mock = create_mock_procedure_model()
+
+        # First query: find procedure
+        find_result = MagicMock()
+        find_result.scalar_one_or_none.return_value = existing_mock
+
+        # Second query: update
+        updated_mock = create_mock_procedure_model(success_count=6)
+        update_result = MagicMock()
+        update_result.scalar_one.return_value = updated_mock
+
+        mock_session.execute.side_effect = [find_result, update_result]
+
+        result = await memory.record_outcome(existing_mock.id, success=True)
+
+        assert result.success_count == 6
+
+    @pytest.mark.asyncio
+    async def test_record_outcome_failure(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test recording a failure outcome."""
+        existing_mock = create_mock_procedure_model()
+
+        # First query: find procedure
+        find_result = MagicMock()
+        find_result.scalar_one_or_none.return_value = existing_mock
+
+        # Second query: update
+        updated_mock = create_mock_procedure_model(failure_count=2)
+        update_result = MagicMock()
+        update_result.scalar_one.return_value = updated_mock
+
+        mock_session.execute.side_effect = [find_result, update_result]
+
+        result = await memory.record_outcome(existing_mock.id, success=False)
+
+        assert result.failure_count == 2
+
+    @pytest.mark.asyncio
+    async def test_record_outcome_not_found(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test recording outcome for non-existent procedure raises error."""
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        with pytest.raises(ValueError, match="Procedure not found"):
+            await memory.record_outcome(uuid4(), success=True)
+
+
+class TestProceduralMemoryUpdateSteps:
+    """Tests for step updates."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> ProceduralMemory:
+        """Create a ProceduralMemory instance."""
+        return ProceduralMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_update_steps(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test updating steps."""
+        existing_mock = create_mock_procedure_model()
+
+        # First query: find procedure
+        find_result = MagicMock()
+        find_result.scalar_one_or_none.return_value = existing_mock
+
+        # Second query: update
+        updated_mock = create_mock_procedure_model()
+        updated_mock.steps = [
+            {"order": 1, "action": "new_step_1", "parameters": {}},
+            {"order": 2, "action": "new_step_2", "parameters": {}},
+        ]
+        update_result = MagicMock()
+        update_result.scalar_one.return_value = updated_mock
+
+        mock_session.execute.side_effect = [find_result, update_result]
+
+        new_steps = [
+            Step(order=1, action="new_step_1"),
+            Step(order=2, action="new_step_2"),
+        ]
+
+        result = await memory.update_steps(existing_mock.id, new_steps)
+
+        assert len(result.steps) == 2
+
+    @pytest.mark.asyncio
+    async def test_update_steps_not_found(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test updating steps for non-existent procedure raises error."""
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        with pytest.raises(ValueError, match="Procedure not found"):
+            await memory.update_steps(uuid4(), [Step(order=1, action="test")])
+
+
+class TestProceduralMemoryStats:
+    """Tests for statistics methods."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> ProceduralMemory:
+        """Create a ProceduralMemory instance."""
+        return ProceduralMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_get_stats_empty(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test getting stats for empty project."""
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        mock_session.execute.return_value = mock_result
+
+        stats = await memory.get_stats(uuid4())
+
+        assert stats["total_procedures"] == 0
+        assert stats["avg_success_rate"] == 0.0
+
+    @pytest.mark.asyncio
+    async def test_get_stats_with_data(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test getting stats with data."""
+        procedures = [
+            create_mock_procedure_model(success_count=8, failure_count=2),
+            create_mock_procedure_model(success_count=6, failure_count=4),
+        ]
+
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = procedures
+        mock_session.execute.return_value = mock_result
+
+        stats = await memory.get_stats(uuid4())
+
+        assert stats["total_procedures"] == 2
+        assert stats["total_uses"] == 20  # (8+2) + (6+4)
+
+    @pytest.mark.asyncio
+    async def test_count(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test counting procedures."""
+        procedures = [create_mock_procedure_model() for _ in range(5)]
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = procedures
+        mock_session.execute.return_value = mock_result
+
+        count = await memory.count(uuid4())
+
+        assert count == 5
+
+
+class TestProceduralMemoryDelete:
+    """Tests for delete operations."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> ProceduralMemory:
+        """Create a ProceduralMemory instance."""
+        return ProceduralMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_delete(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test deleting a procedure."""
+        existing_mock = create_mock_procedure_model()
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = existing_mock
+        mock_session.execute.return_value = mock_result
+        mock_session.delete = AsyncMock()
+
+        result = await memory.delete(existing_mock.id)
+
+        assert result is True
+        mock_session.delete.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_delete_not_found(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test deleting non-existent procedure."""
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        result = await memory.delete(uuid4())
+
+        assert result is False
+
+
+class TestProceduralMemoryGetById:
+    """Tests for get_by_id method."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> ProceduralMemory:
+        """Create a ProceduralMemory instance."""
+        return ProceduralMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_get_by_id(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test getting procedure by ID."""
+        existing_mock = create_mock_procedure_model()
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = existing_mock
+        mock_session.execute.return_value = mock_result
+
+        result = await memory.get_by_id(existing_mock.id)
+
+        assert result is not None
+        assert result.name == "deploy_api"
+
+    @pytest.mark.asyncio
+    async def test_get_by_id_not_found(
+        self,
+        memory: ProceduralMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test get_by_id returns None when not found."""
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        result = await memory.get_by_id(uuid4())
+
+        assert result is None

backend/tests/unit/services/memory/scoping/__init__.py

@@ -0,0 +1,2 @@
+# tests/unit/services/memory/scoping/__init__.py
+"""Unit tests for memory scoping."""

backend/tests/unit/services/memory/scoping/test_resolver.py

@@ -0,0 +1,653 @@
+# tests/unit/services/memory/scoping/test_resolver.py
+"""Unit tests for scope resolution."""
+
+from dataclasses import dataclass
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.scoping.resolver import (
+    ResolutionOptions,
+    ResolutionResult,
+    ScopeFilter,
+    ScopeResolver,
+    get_scope_resolver,
+)
+from app.services.memory.scoping.scope import ScopeManager, ScopePolicy
+from app.services.memory.types import ScopeContext, ScopeLevel
+
+
+@dataclass
+class MockItem:
+    """Mock item for testing resolution."""
+
+    id: str
+    name: str
+    scope_id: str
+
+
+class TestResolutionResult:
+    """Tests for ResolutionResult dataclass."""
+
+    def test_total_count(self) -> None:
+        """Test total_count property."""
+        result = ResolutionResult[MockItem](
+            items=[
+                MockItem(id="1", name="a", scope_id="s1"),
+                MockItem(id="2", name="b", scope_id="s2"),
+            ],
+            sources=[],
+        )
+
+        assert result.total_count == 2
+
+    def test_empty_result(self) -> None:
+        """Test empty result."""
+        result = ResolutionResult[MockItem](
+            items=[],
+            sources=[],
+        )
+
+        assert result.total_count == 0
+        assert result.inherited_count == 0
+        assert result.own_count == 0
+
+
+class TestResolutionOptions:
+    """Tests for ResolutionOptions dataclass."""
+
+    def test_default_values(self) -> None:
+        """Test default option values."""
+        options = ResolutionOptions()
+
+        assert options.include_inherited is True
+        assert options.max_inheritance_depth == 5
+        assert options.limit_per_scope == 100
+        assert options.total_limit == 500
+        assert options.deduplicate is True
+        assert options.deduplicate_key is None
+
+    def test_custom_values(self) -> None:
+        """Test custom option values."""
+        options = ResolutionOptions(
+            include_inherited=False,
+            max_inheritance_depth=3,
+            limit_per_scope=50,
+            total_limit=200,
+            deduplicate=False,
+            deduplicate_key="id",
+        )
+
+        assert options.include_inherited is False
+        assert options.max_inheritance_depth == 3
+        assert options.limit_per_scope == 50
+        assert options.total_limit == 200
+        assert options.deduplicate is False
+        assert options.deduplicate_key == "id"
+
+
+class TestScopeResolver:
+    """Tests for ScopeResolver class."""
+
+    @pytest.fixture
+    def manager(self) -> ScopeManager:
+        """Create a scope manager."""
+        return ScopeManager()
+
+    @pytest.fixture
+    def resolver(self, manager: ScopeManager) -> ScopeResolver:
+        """Create a scope resolver."""
+        return ScopeResolver(manager=manager)
+
+    def test_resolve_single_scope(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test resolving from a single scope."""
+        scope = manager.create_scope(ScopeLevel.PROJECT, "project-1")
+
+        def fetcher(s: ScopeContext, limit: int) -> list[MockItem]:
+            if s.scope_id == "project-1":
+                return [MockItem(id="1", name="item1", scope_id="project-1")]
+            return []
+
+        result = resolver.resolve(
+            scope=scope,
+            fetcher=fetcher,
+            options=ResolutionOptions(include_inherited=False),
+        )
+
+        assert result.total_count == 1
+        assert result.own_count == 1
+        assert result.inherited_count == 0
+
+    def test_resolve_with_inheritance(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test resolving with scope inheritance."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project-1", parent=global_scope
+        )
+
+        def fetcher(s: ScopeContext, limit: int) -> list[MockItem]:
+            if s.scope_id == "project-1":
+                return [MockItem(id="1", name="project-item", scope_id="project-1")]
+            elif s.scope_id == "global":
+                return [MockItem(id="2", name="global-item", scope_id="global")]
+            return []
+
+        result = resolver.resolve(
+            scope=project_scope,
+            fetcher=fetcher,
+            options=ResolutionOptions(include_inherited=True),
+        )
+
+        assert result.total_count == 2
+        assert result.own_count == 1
+        assert result.inherited_count == 1
+
+    def test_resolve_respects_depth_limit(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test that resolution respects max inheritance depth."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project", parent=global_scope
+        )
+        agent_scope = manager.create_scope(
+            ScopeLevel.AGENT_TYPE, "agent", parent=project_scope
+        )
+        instance_scope = manager.create_scope(
+            ScopeLevel.AGENT_INSTANCE, "instance", parent=agent_scope
+        )
+        session_scope = manager.create_scope(
+            ScopeLevel.SESSION, "session", parent=instance_scope
+        )
+
+        items_per_scope = {
+            "session": [MockItem(id="1", name="s", scope_id="session")],
+            "instance": [MockItem(id="2", name="i", scope_id="instance")],
+            "agent": [MockItem(id="3", name="a", scope_id="agent")],
+            "project": [MockItem(id="4", name="p", scope_id="project")],
+            "global": [MockItem(id="5", name="g", scope_id="global")],
+        }
+
+        def fetcher(s: ScopeContext, limit: int) -> list[MockItem]:
+            return items_per_scope.get(s.scope_id, [])
+
+        # Depth 1 should get session + instance
+        result = resolver.resolve(
+            scope=session_scope,
+            fetcher=fetcher,
+            options=ResolutionOptions(max_inheritance_depth=1),
+        )
+
+        assert result.total_count == 2
+
+    def test_resolve_respects_total_limit(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test that resolution respects total limit."""
+        scope = manager.create_scope(ScopeLevel.PROJECT, "project")
+
+        def fetcher(s: ScopeContext, limit: int) -> list[MockItem]:
+            return [
+                MockItem(id=str(i), name=f"item-{i}", scope_id="project")
+                for i in range(10)
+            ]
+
+        result = resolver.resolve(
+            scope=scope,
+            fetcher=fetcher,
+            options=ResolutionOptions(total_limit=5),
+        )
+
+        assert result.total_count == 5
+
+    def test_resolve_deduplicates_by_key(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test deduplication by key field."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project", parent=global_scope
+        )
+
+        def fetcher(s: ScopeContext, limit: int) -> list[MockItem]:
+            if s.scope_id == "project":
+                return [MockItem(id="1", name="project-ver", scope_id="project")]
+            elif s.scope_id == "global":
+                # Same ID, should be deduplicated
+                return [MockItem(id="1", name="global-ver", scope_id="global")]
+            return []
+
+        result = resolver.resolve(
+            scope=project_scope,
+            fetcher=fetcher,
+            options=ResolutionOptions(deduplicate=True, deduplicate_key="id"),
+        )
+
+        # Should only have the project version (encountered first)
+        assert result.total_count == 1
+        assert result.items[0].name == "project-ver"
+
+    def test_resolve_skips_non_readable_scopes(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test that non-readable scopes are skipped."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project", parent=global_scope
+        )
+
+        # Set global as non-readable
+        manager.set_policy(
+            global_scope,
+            ScopePolicy(
+                scope_type=ScopeLevel.GLOBAL,
+                scope_id="global",
+                can_read=False,
+            ),
+        )
+
+        def fetcher(s: ScopeContext, limit: int) -> list[MockItem]:
+            if s.scope_id == "project":
+                return [MockItem(id="1", name="project-item", scope_id="project")]
+            elif s.scope_id == "global":
+                return [MockItem(id="2", name="global-item", scope_id="global")]
+            return []
+
+        result = resolver.resolve(
+            scope=project_scope,
+            fetcher=fetcher,
+        )
+
+        # Should only have project item
+        assert result.total_count == 1
+        assert result.items[0].scope_id == "project"
+
+    def test_resolve_skips_non_inheritable_scopes(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test that non-inheritable parent scopes stop inheritance."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project", parent=global_scope
+        )
+
+        # Set global as non-inheritable
+        manager.set_policy(
+            global_scope,
+            ScopePolicy(
+                scope_type=ScopeLevel.GLOBAL,
+                scope_id="global",
+                can_inherit=False,
+            ),
+        )
+
+        def fetcher(s: ScopeContext, limit: int) -> list[MockItem]:
+            if s.scope_id == "project":
+                return [MockItem(id="1", name="project-item", scope_id="project")]
+            elif s.scope_id == "global":
+                return [MockItem(id="2", name="global-item", scope_id="global")]
+            return []
+
+        result = resolver.resolve(
+            scope=project_scope,
+            fetcher=fetcher,
+        )
+
+        # Should only have project item
+        assert result.total_count == 1
+
+    def test_get_visible_scopes(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test getting visible scopes."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project", parent=global_scope
+        )
+        agent_scope = manager.create_scope(
+            ScopeLevel.AGENT_TYPE, "agent", parent=project_scope
+        )
+
+        visible = resolver.get_visible_scopes(agent_scope)
+
+        assert len(visible) == 3
+        assert visible[0].scope_id == "agent"
+        assert visible[1].scope_id == "project"
+        assert visible[2].scope_id == "global"
+
+    def test_get_visible_scopes_stops_at_non_inheritable(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test that visible scopes stop at non-inheritable parent."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project", parent=global_scope
+        )
+        agent_scope = manager.create_scope(
+            ScopeLevel.AGENT_TYPE, "agent", parent=project_scope
+        )
+
+        # Make project non-inheritable
+        manager.set_policy(
+            project_scope,
+            ScopePolicy(
+                scope_type=ScopeLevel.PROJECT,
+                scope_id="project",
+                can_inherit=False,
+            ),
+        )
+
+        visible = resolver.get_visible_scopes(agent_scope)
+
+        # Should stop at project (exclusive)
+        assert len(visible) == 1
+        assert visible[0].scope_id == "agent"
+
+    def test_find_write_scope_same_level(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test finding write scope at same level."""
+        scope = manager.create_scope(ScopeLevel.PROJECT, "project")
+
+        result = resolver.find_write_scope(ScopeLevel.PROJECT, scope)
+
+        assert result is not None
+        assert result.scope_id == "project"
+
+    def test_find_write_scope_ancestor(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test finding write scope in ancestors."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project", parent=global_scope
+        )
+        agent_scope = manager.create_scope(
+            ScopeLevel.AGENT_TYPE, "agent", parent=project_scope
+        )
+
+        result = resolver.find_write_scope(ScopeLevel.PROJECT, agent_scope)
+
+        assert result is not None
+        assert result.scope_id == "project"
+
+    def test_find_write_scope_not_found(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test finding write scope when not in hierarchy."""
+        scope = manager.create_scope(ScopeLevel.PROJECT, "project")
+
+        # Looking for session level, but we're at project
+        result = resolver.find_write_scope(ScopeLevel.SESSION, scope)
+
+        assert result is None
+
+    def test_find_write_scope_respects_write_policy(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test that find_write_scope respects write policy."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project", parent=global_scope
+        )
+
+        # Make project read-only
+        manager.set_policy(
+            project_scope,
+            ScopePolicy(
+                scope_type=ScopeLevel.PROJECT,
+                scope_id="project",
+                can_write=False,
+            ),
+        )
+
+        result = resolver.find_write_scope(ScopeLevel.PROJECT, project_scope)
+
+        assert result is None
+
+    def test_resolve_scope_from_memory_working(
+        self,
+        resolver: ScopeResolver,
+    ) -> None:
+        """Test resolving scope for working memory."""
+        project_id = str(uuid4())
+        session_id = "session-123"
+
+        scope, level = resolver.resolve_scope_from_memory(
+            memory_type="working",
+            project_id=project_id,
+            session_id=session_id,
+        )
+
+        assert scope.scope_type == ScopeLevel.SESSION
+        assert level == ScopeLevel.SESSION
+
+    def test_resolve_scope_from_memory_episodic(
+        self,
+        resolver: ScopeResolver,
+    ) -> None:
+        """Test resolving scope for episodic memory."""
+        project_id = str(uuid4())
+        agent_instance_id = str(uuid4())
+
+        scope, level = resolver.resolve_scope_from_memory(
+            memory_type="episodic",
+            project_id=project_id,
+            agent_instance_id=agent_instance_id,
+        )
+
+        assert scope.scope_type == ScopeLevel.AGENT_INSTANCE
+        assert level == ScopeLevel.AGENT_INSTANCE
+
+    def test_resolve_scope_from_memory_semantic(
+        self,
+        resolver: ScopeResolver,
+    ) -> None:
+        """Test resolving scope for semantic memory."""
+        project_id = str(uuid4())
+
+        scope, level = resolver.resolve_scope_from_memory(
+            memory_type="semantic",
+            project_id=project_id,
+        )
+
+        assert scope.scope_type == ScopeLevel.PROJECT
+        assert level == ScopeLevel.PROJECT
+
+    def test_resolve_scope_from_memory_procedural(
+        self,
+        resolver: ScopeResolver,
+    ) -> None:
+        """Test resolving scope for procedural memory."""
+        project_id = str(uuid4())
+        agent_type_id = str(uuid4())
+
+        scope, level = resolver.resolve_scope_from_memory(
+            memory_type="procedural",
+            project_id=project_id,
+            agent_type_id=agent_type_id,
+        )
+
+        assert scope.scope_type == ScopeLevel.AGENT_TYPE
+        assert level == ScopeLevel.AGENT_TYPE
+
+    def test_validate_write_access_allowed(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test write access validation when allowed."""
+        scope = manager.create_scope(ScopeLevel.PROJECT, "project")
+
+        assert resolver.validate_write_access(scope, "semantic") is True
+
+    def test_validate_write_access_denied_by_policy(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test write access denied by policy."""
+        scope = manager.create_scope(ScopeLevel.PROJECT, "project")
+
+        manager.set_policy(
+            scope,
+            ScopePolicy(
+                scope_type=ScopeLevel.PROJECT,
+                scope_id="project",
+                can_write=False,
+            ),
+        )
+
+        assert resolver.validate_write_access(scope, "semantic") is False
+
+    def test_validate_write_access_denied_by_memory_type(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test write access denied by memory type restriction."""
+        scope = manager.create_scope(ScopeLevel.PROJECT, "project")
+
+        manager.set_policy(
+            scope,
+            ScopePolicy(
+                scope_type=ScopeLevel.PROJECT,
+                scope_id="project",
+                allowed_memory_types=["episodic"],  # Only episodic allowed
+            ),
+        )
+
+        assert resolver.validate_write_access(scope, "semantic") is False
+        assert resolver.validate_write_access(scope, "episodic") is True
+
+    def test_get_scope_chain(
+        self,
+        resolver: ScopeResolver,
+        manager: ScopeManager,
+    ) -> None:
+        """Test getting scope chain."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project", parent=global_scope
+        )
+        agent_scope = manager.create_scope(
+            ScopeLevel.AGENT_TYPE, "agent", parent=project_scope
+        )
+
+        chain = resolver.get_scope_chain(agent_scope)
+
+        assert len(chain) == 3
+        assert chain[0] == (ScopeLevel.GLOBAL, "global")
+        assert chain[1] == (ScopeLevel.PROJECT, "project")
+        assert chain[2] == (ScopeLevel.AGENT_TYPE, "agent")
+
+
+class TestScopeFilter:
+    """Tests for ScopeFilter dataclass."""
+
+    def test_default_values(self) -> None:
+        """Test default filter values."""
+        filter_ = ScopeFilter()
+
+        assert filter_.scope_types is None
+        assert filter_.project_ids is None
+        assert filter_.agent_type_ids is None
+        assert filter_.include_global is True
+
+    def test_matches_global_scope(self) -> None:
+        """Test matching global scope."""
+        scope = ScopeContext(
+            scope_type=ScopeLevel.GLOBAL,
+            scope_id="global",
+        )
+
+        filter_ = ScopeFilter(include_global=True)
+        assert filter_.matches(scope) is True
+
+        filter_ = ScopeFilter(include_global=False)
+        assert filter_.matches(scope) is False
+
+    def test_matches_scope_type(self) -> None:
+        """Test matching by scope type."""
+        scope = ScopeContext(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="project-1",
+        )
+
+        filter_ = ScopeFilter(scope_types=[ScopeLevel.PROJECT])
+        assert filter_.matches(scope) is True
+
+        filter_ = ScopeFilter(scope_types=[ScopeLevel.AGENT_TYPE])
+        assert filter_.matches(scope) is False
+
+    def test_matches_project_id(self) -> None:
+        """Test matching by project ID."""
+        scope = ScopeContext(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="project-1",
+        )
+
+        filter_ = ScopeFilter(project_ids=["project-1", "project-2"])
+        assert filter_.matches(scope) is True
+
+        filter_ = ScopeFilter(project_ids=["project-3"])
+        assert filter_.matches(scope) is False
+
+    def test_matches_agent_type_id(self) -> None:
+        """Test matching by agent type ID."""
+        scope = ScopeContext(
+            scope_type=ScopeLevel.AGENT_TYPE,
+            scope_id="agent-1",
+        )
+
+        filter_ = ScopeFilter(agent_type_ids=["agent-1"])
+        assert filter_.matches(scope) is True
+
+        filter_ = ScopeFilter(agent_type_ids=["agent-2"])
+        assert filter_.matches(scope) is False
+
+
+class TestGetScopeResolver:
+    """Tests for singleton getter."""
+
+    def test_returns_instance(self) -> None:
+        """Test that getter returns instance."""
+        resolver = get_scope_resolver()
+        assert resolver is not None
+        assert isinstance(resolver, ScopeResolver)
+
+    def test_returns_same_instance(self) -> None:
+        """Test that getter returns same instance."""
+        resolver1 = get_scope_resolver()
+        resolver2 = get_scope_resolver()
+        assert resolver1 is resolver2

backend/tests/unit/services/memory/scoping/test_scope.py

@@ -0,0 +1,361 @@
+# tests/unit/services/memory/scoping/test_scope.py
+"""Unit tests for scope management."""
+
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.scoping.scope import (
+    ScopeManager,
+    ScopePolicy,
+    get_scope_manager,
+)
+from app.services.memory.types import ScopeLevel
+
+
+class TestScopePolicy:
+    """Tests for ScopePolicy dataclass."""
+
+    def test_default_values(self) -> None:
+        """Test default policy values."""
+        policy = ScopePolicy(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="test-project",
+        )
+
+        assert policy.can_read is True
+        assert policy.can_write is True
+        assert policy.can_inherit is True
+        assert policy.allowed_memory_types == ["all"]
+
+    def test_allows_read(self) -> None:
+        """Test allows_read method."""
+        policy = ScopePolicy(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="test",
+            can_read=True,
+        )
+        assert policy.allows_read() is True
+
+        policy.can_read = False
+        assert policy.allows_read() is False
+
+    def test_allows_write(self) -> None:
+        """Test allows_write method."""
+        policy = ScopePolicy(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="test",
+            can_write=True,
+        )
+        assert policy.allows_write() is True
+
+        policy.can_write = False
+        assert policy.allows_write() is False
+
+    def test_allows_inherit(self) -> None:
+        """Test allows_inherit method."""
+        policy = ScopePolicy(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="test",
+            can_inherit=True,
+        )
+        assert policy.allows_inherit() is True
+
+        policy.can_inherit = False
+        assert policy.allows_inherit() is False
+
+    def test_allows_memory_type(self) -> None:
+        """Test allows_memory_type method."""
+        policy = ScopePolicy(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="test",
+            allowed_memory_types=["all"],
+        )
+        assert policy.allows_memory_type("working") is True
+        assert policy.allows_memory_type("episodic") is True
+
+        policy.allowed_memory_types = ["working", "episodic"]
+        assert policy.allows_memory_type("working") is True
+        assert policy.allows_memory_type("episodic") is True
+        assert policy.allows_memory_type("semantic") is False
+
+
+class TestScopeManager:
+    """Tests for ScopeManager class."""
+
+    @pytest.fixture
+    def manager(self) -> ScopeManager:
+        """Create a scope manager."""
+        return ScopeManager()
+
+    def test_create_global_scope(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test creating a global scope."""
+        scope = manager.create_scope(
+            scope_type=ScopeLevel.GLOBAL,
+            scope_id="global",
+        )
+
+        assert scope.scope_type == ScopeLevel.GLOBAL
+        assert scope.scope_id == "global"
+        assert scope.parent is None
+
+    def test_create_project_scope(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test creating a project scope."""
+        global_scope = manager.create_scope(
+            scope_type=ScopeLevel.GLOBAL,
+            scope_id="global",
+        )
+
+        project_scope = manager.create_scope(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="project-1",
+            parent=global_scope,
+        )
+
+        assert project_scope.scope_type == ScopeLevel.PROJECT
+        assert project_scope.scope_id == "project-1"
+        assert project_scope.parent is global_scope
+
+    def test_create_scope_auto_parent(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test that non-global scopes auto-create parent chain."""
+        scope = manager.create_scope(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="test-project",
+        )
+
+        assert scope.scope_type == ScopeLevel.PROJECT
+        assert scope.parent is not None
+        assert scope.parent.scope_type == ScopeLevel.GLOBAL
+
+    def test_create_scope_invalid_hierarchy(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test that invalid hierarchy raises error."""
+        project_scope = manager.create_scope(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="project-1",
+        )
+
+        with pytest.raises(ValueError, match="Invalid scope hierarchy"):
+            manager.create_scope(
+                scope_type=ScopeLevel.GLOBAL,
+                scope_id="global",
+                parent=project_scope,
+            )
+
+    def test_create_scope_from_ids(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test creating scope from individual IDs."""
+        project_id = uuid4()
+        agent_type_id = uuid4()
+
+        scope = manager.create_scope_from_ids(
+            project_id=project_id,
+            agent_type_id=agent_type_id,
+        )
+
+        assert scope.scope_type == ScopeLevel.AGENT_TYPE
+        assert scope.scope_id == str(agent_type_id)
+        assert scope.parent is not None
+        assert scope.parent.scope_type == ScopeLevel.PROJECT
+
+    def test_create_scope_from_ids_with_session(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test creating scope with session ID."""
+        project_id = uuid4()
+        session_id = "session-123"
+
+        scope = manager.create_scope_from_ids(
+            project_id=project_id,
+            session_id=session_id,
+        )
+
+        assert scope.scope_type == ScopeLevel.SESSION
+        assert scope.scope_id == session_id
+
+    def test_get_default_policy(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test getting default policy."""
+        scope = manager.create_scope(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="test-project",
+        )
+
+        policy = manager.get_policy(scope)
+
+        assert policy.can_read is True
+        assert policy.can_write is True
+
+    def test_set_and_get_policy(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test setting and retrieving a policy."""
+        scope = manager.create_scope(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="test-project",
+        )
+
+        custom_policy = ScopePolicy(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="test-project",
+            can_write=False,
+        )
+
+        manager.set_policy(scope, custom_policy)
+        retrieved = manager.get_policy(scope)
+
+        assert retrieved.can_write is False
+
+    def test_get_scope_depth(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test getting scope depth."""
+        assert manager.get_scope_depth(ScopeLevel.GLOBAL) == 0
+        assert manager.get_scope_depth(ScopeLevel.PROJECT) == 1
+        assert manager.get_scope_depth(ScopeLevel.AGENT_TYPE) == 2
+        assert manager.get_scope_depth(ScopeLevel.AGENT_INSTANCE) == 3
+        assert manager.get_scope_depth(ScopeLevel.SESSION) == 4
+
+    def test_get_parent_level(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test getting parent level."""
+        assert manager.get_parent_level(ScopeLevel.GLOBAL) is None
+        assert manager.get_parent_level(ScopeLevel.PROJECT) == ScopeLevel.GLOBAL
+        assert manager.get_parent_level(ScopeLevel.AGENT_TYPE) == ScopeLevel.PROJECT
+        assert manager.get_parent_level(ScopeLevel.SESSION) == ScopeLevel.AGENT_INSTANCE
+
+    def test_get_child_level(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test getting child level."""
+        assert manager.get_child_level(ScopeLevel.GLOBAL) == ScopeLevel.PROJECT
+        assert manager.get_child_level(ScopeLevel.PROJECT) == ScopeLevel.AGENT_TYPE
+        assert manager.get_child_level(ScopeLevel.SESSION) is None
+
+    def test_is_ancestor(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test ancestor checking."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project", parent=global_scope
+        )
+        agent_scope = manager.create_scope(
+            ScopeLevel.AGENT_TYPE, "agent", parent=project_scope
+        )
+
+        assert manager.is_ancestor(global_scope, agent_scope) is True
+        assert manager.is_ancestor(project_scope, agent_scope) is True
+        assert manager.is_ancestor(agent_scope, global_scope) is False
+        assert manager.is_ancestor(agent_scope, project_scope) is False
+
+    def test_get_common_ancestor(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test finding common ancestor."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project", parent=global_scope
+        )
+        agent1 = manager.create_scope(
+            ScopeLevel.AGENT_TYPE, "agent1", parent=project_scope
+        )
+        agent2 = manager.create_scope(
+            ScopeLevel.AGENT_TYPE, "agent2", parent=project_scope
+        )
+
+        common = manager.get_common_ancestor(agent1, agent2)
+
+        assert common is not None
+        assert common.scope_type == ScopeLevel.PROJECT
+
+    def test_can_access_same_scope(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test access to same scope."""
+        scope = manager.create_scope(ScopeLevel.PROJECT, "project")
+
+        assert manager.can_access(scope, scope) is True
+        assert manager.can_access(scope, scope, "write") is True
+
+    def test_can_access_ancestor(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test access to ancestor scope."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project", parent=global_scope
+        )
+
+        # Child can read from parent
+        assert manager.can_access(project_scope, global_scope, "read") is True
+
+    def test_cannot_access_descendant(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test that parent cannot access child scope."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project_scope = manager.create_scope(
+            ScopeLevel.PROJECT, "project", parent=global_scope
+        )
+
+        # Parent cannot access child
+        assert manager.can_access(global_scope, project_scope) is False
+
+    def test_cannot_access_sibling(
+        self,
+        manager: ScopeManager,
+    ) -> None:
+        """Test that sibling scopes cannot access each other."""
+        global_scope = manager.create_scope(ScopeLevel.GLOBAL, "global")
+        project1 = manager.create_scope(
+            ScopeLevel.PROJECT, "project1", parent=global_scope
+        )
+        project2 = manager.create_scope(
+            ScopeLevel.PROJECT, "project2", parent=global_scope
+        )
+
+        assert manager.can_access(project1, project2) is False
+        assert manager.can_access(project2, project1) is False
+
+
+class TestGetScopeManager:
+    """Tests for singleton getter."""
+
+    def test_returns_instance(self) -> None:
+        """Test that getter returns instance."""
+        manager = get_scope_manager()
+        assert manager is not None
+        assert isinstance(manager, ScopeManager)
+
+    def test_returns_same_instance(self) -> None:
+        """Test that getter returns same instance."""
+        manager1 = get_scope_manager()
+        manager2 = get_scope_manager()
+        assert manager1 is manager2

backend/tests/unit/services/memory/semantic/__init__.py

@@ -0,0 +1,2 @@
+# tests/unit/services/memory/semantic/__init__.py
+"""Unit tests for semantic memory service."""

backend/tests/unit/services/memory/semantic/test_extraction.py

@@ -0,0 +1,263 @@
+# tests/unit/services/memory/semantic/test_extraction.py
+"""Unit tests for fact extraction."""
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.semantic.extraction import (
+    ExtractedFact,
+    ExtractionContext,
+    FactExtractor,
+    get_fact_extractor,
+)
+from app.services.memory.types import Episode, Outcome
+
+
+def create_test_episode(
+    lessons_learned: list[str] | None = None,
+    outcome: Outcome = Outcome.SUCCESS,
+    task_type: str = "code_review",
+    task_description: str = "Review the authentication module",
+    outcome_details: str = "",
+) -> Episode:
+    """Create a test episode for extraction tests."""
+    return Episode(
+        id=uuid4(),
+        project_id=uuid4(),
+        agent_instance_id=None,
+        agent_type_id=None,
+        session_id="test-session",
+        task_type=task_type,
+        task_description=task_description,
+        actions=[],
+        context_summary="Test context",
+        outcome=outcome,
+        outcome_details=outcome_details,
+        duration_seconds=60.0,
+        tokens_used=500,
+        lessons_learned=lessons_learned or [],
+        importance_score=0.7,
+        embedding=None,
+        occurred_at=datetime.now(UTC),
+        created_at=datetime.now(UTC),
+        updated_at=datetime.now(UTC),
+    )
+
+
+class TestExtractedFact:
+    """Tests for ExtractedFact dataclass."""
+
+    def test_to_fact_create(self) -> None:
+        """Test converting ExtractedFact to FactCreate."""
+        extracted = ExtractedFact(
+            subject="Python",
+            predicate="uses",
+            object="dynamic typing",
+            confidence=0.8,
+        )
+
+        fact_create = extracted.to_fact_create(
+            project_id=uuid4(),
+            source_episode_ids=[uuid4()],
+        )
+
+        assert fact_create.subject == "Python"
+        assert fact_create.predicate == "uses"
+        assert fact_create.object == "dynamic typing"
+        assert fact_create.confidence == 0.8
+
+    def test_to_fact_create_defaults(self) -> None:
+        """Test to_fact_create with default values."""
+        extracted = ExtractedFact(
+            subject="A",
+            predicate="B",
+            object="C",
+            confidence=0.5,
+        )
+
+        fact_create = extracted.to_fact_create()
+
+        assert fact_create.project_id is None
+        assert fact_create.source_episode_ids == []
+
+
+class TestFactExtractor:
+    """Tests for FactExtractor class."""
+
+    @pytest.fixture
+    def extractor(self) -> FactExtractor:
+        """Create a fact extractor."""
+        return FactExtractor()
+
+    def test_extract_from_episode_with_lessons(
+        self,
+        extractor: FactExtractor,
+    ) -> None:
+        """Test extracting facts from episode with lessons."""
+        episode = create_test_episode(
+            lessons_learned=[
+                "Always validate user input before processing",
+                "Use parameterized queries to prevent SQL injection",
+            ]
+        )
+
+        facts = extractor.extract_from_episode(episode)
+
+        assert len(facts) > 0
+        # Should have lesson_learned predicates
+        lesson_facts = [f for f in facts if f.predicate == "lesson_learned"]
+        assert len(lesson_facts) >= 2
+
+    def test_extract_from_episode_with_always_pattern(
+        self,
+        extractor: FactExtractor,
+    ) -> None:
+        """Test extracting 'always' pattern lessons."""
+        episode = create_test_episode(
+            lessons_learned=["Always close file handles properly"]
+        )
+
+        facts = extractor.extract_from_episode(episode)
+
+        best_practices = [f for f in facts if f.predicate == "best_practice"]
+        assert len(best_practices) >= 1
+        assert any("close file handles" in f.object for f in best_practices)
+
+    def test_extract_from_episode_with_never_pattern(
+        self,
+        extractor: FactExtractor,
+    ) -> None:
+        """Test extracting 'never' pattern lessons."""
+        episode = create_test_episode(
+            lessons_learned=["Never store passwords in plain text"]
+        )
+
+        facts = extractor.extract_from_episode(episode)
+
+        anti_patterns = [f for f in facts if f.predicate == "anti_pattern"]
+        assert len(anti_patterns) >= 1
+
+    def test_extract_from_episode_with_conditional_pattern(
+        self,
+        extractor: FactExtractor,
+    ) -> None:
+        """Test extracting conditional lessons."""
+        episode = create_test_episode(
+            lessons_learned=["When handling errors, log the stack trace"]
+        )
+
+        facts = extractor.extract_from_episode(episode)
+
+        conditional = [f for f in facts if f.predicate == "requires_action"]
+        assert len(conditional) >= 1
+
+    def test_extract_outcome_facts_success(
+        self,
+        extractor: FactExtractor,
+    ) -> None:
+        """Test extracting facts from successful episode."""
+        episode = create_test_episode(
+            outcome=Outcome.SUCCESS,
+            outcome_details="Deployed to production without issues",
+        )
+
+        facts = extractor.extract_from_episode(episode)
+
+        success_facts = [f for f in facts if f.predicate == "successful_approach"]
+        assert len(success_facts) >= 1
+
+    def test_extract_outcome_facts_failure(
+        self,
+        extractor: FactExtractor,
+    ) -> None:
+        """Test extracting facts from failed episode."""
+        episode = create_test_episode(
+            outcome=Outcome.FAILURE,
+            outcome_details="Connection timeout during deployment",
+        )
+
+        facts = extractor.extract_from_episode(episode)
+
+        failure_facts = [f for f in facts if f.predicate == "known_failure_mode"]
+        assert len(failure_facts) >= 1
+
+    def test_extract_from_text_uses_pattern(
+        self,
+        extractor: FactExtractor,
+    ) -> None:
+        """Test extracting 'uses' pattern from text."""
+        text = "FastAPI uses Starlette for ASGI support."
+
+        facts = extractor.extract_from_text(text)
+
+        assert len(facts) >= 1
+        uses_facts = [f for f in facts if f.predicate == "uses"]
+        assert len(uses_facts) >= 1
+
+    def test_extract_from_text_requires_pattern(
+        self,
+        extractor: FactExtractor,
+    ) -> None:
+        """Test extracting 'requires' pattern from text."""
+        text = "This feature requires Python 3.10 or higher."
+
+        facts = extractor.extract_from_text(text)
+
+        requires_facts = [f for f in facts if f.predicate == "requires"]
+        assert len(requires_facts) >= 1
+
+    def test_extract_from_text_empty(
+        self,
+        extractor: FactExtractor,
+    ) -> None:
+        """Test extracting from empty text."""
+        facts = extractor.extract_from_text("")
+
+        assert facts == []
+
+    def test_extract_from_text_short(
+        self,
+        extractor: FactExtractor,
+    ) -> None:
+        """Test extracting from too-short text."""
+        facts = extractor.extract_from_text("Hi.")
+
+        assert facts == []
+
+    def test_extract_with_context(
+        self,
+        extractor: FactExtractor,
+    ) -> None:
+        """Test extraction with custom context."""
+        episode = create_test_episode(lessons_learned=["Low confidence lesson"])
+
+        context = ExtractionContext(
+            min_confidence=0.9,  # High threshold
+            max_facts_per_source=2,
+        )
+
+        facts = extractor.extract_from_episode(episode, context)
+
+        # Should filter out low confidence facts
+        for fact in facts:
+            assert fact.confidence >= 0.9 or len(facts) <= 2
+
+
+class TestGetFactExtractor:
+    """Tests for singleton getter."""
+
+    def test_get_fact_extractor_returns_instance(self) -> None:
+        """Test that get_fact_extractor returns an instance."""
+        extractor = get_fact_extractor()
+
+        assert extractor is not None
+        assert isinstance(extractor, FactExtractor)
+
+    def test_get_fact_extractor_returns_same_instance(self) -> None:
+        """Test that get_fact_extractor returns singleton."""
+        extractor1 = get_fact_extractor()
+        extractor2 = get_fact_extractor()
+
+        assert extractor1 is extractor2

backend/tests/unit/services/memory/semantic/test_memory.py

@@ -0,0 +1,446 @@
+# tests/unit/services/memory/semantic/test_memory.py
+"""Unit tests for SemanticMemory class."""
+
+from datetime import UTC, datetime
+from unittest.mock import AsyncMock, MagicMock
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.semantic.memory import SemanticMemory
+from app.services.memory.types import FactCreate
+
+
+def create_mock_fact_model(
+    project_id=None,
+    subject="FastAPI",
+    predicate="uses",
+    obj="Starlette",
+    confidence=0.8,
+):
+    """Create a mock fact model for testing."""
+    mock = MagicMock()
+    mock.id = uuid4()
+    mock.project_id = project_id
+    mock.subject = subject
+    mock.predicate = predicate
+    mock.object = obj
+    mock.confidence = confidence
+    mock.source_episode_ids = []
+    mock.first_learned = datetime.now(UTC)
+    mock.last_reinforced = datetime.now(UTC)
+    mock.reinforcement_count = 1
+    mock.embedding = None
+    mock.created_at = datetime.now(UTC)
+    mock.updated_at = datetime.now(UTC)
+    return mock
+
+
+class TestSemanticMemoryInit:
+    """Tests for SemanticMemory initialization."""
+
+    def test_init_creates_memory(self) -> None:
+        """Test that init creates memory instance."""
+        mock_session = AsyncMock()
+        memory = SemanticMemory(session=mock_session)
+
+        assert memory._session is mock_session
+
+    def test_init_with_embedding_generator(self) -> None:
+        """Test init with embedding generator."""
+        mock_session = AsyncMock()
+        mock_embedding_gen = AsyncMock()
+        memory = SemanticMemory(
+            session=mock_session, embedding_generator=mock_embedding_gen
+        )
+
+        assert memory._embedding_generator is mock_embedding_gen
+
+    @pytest.mark.asyncio
+    async def test_create_factory_method(self) -> None:
+        """Test create factory method."""
+        mock_session = AsyncMock()
+        memory = await SemanticMemory.create(session=mock_session)
+
+        assert memory is not None
+        assert memory._session is mock_session
+
+
+class TestSemanticMemoryStoreFact:
+    """Tests for fact storage methods."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        session.add = MagicMock()
+        session.flush = AsyncMock()
+        session.refresh = AsyncMock()
+        # Mock no existing fact found
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        session.execute.return_value = mock_result
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> SemanticMemory:
+        """Create a SemanticMemory instance."""
+        return SemanticMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_store_new_fact(
+        self,
+        memory: SemanticMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test storing a new fact."""
+        fact_data = FactCreate(
+            subject="Python",
+            predicate="is_a",
+            object="programming language",
+            confidence=0.9,
+            project_id=uuid4(),
+        )
+
+        result = await memory.store_fact(fact_data)
+
+        assert result.subject == "Python"
+        assert result.predicate == "is_a"
+        assert result.object == "programming language"
+        mock_session.add.assert_called_once()
+        mock_session.flush.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_store_fact_reinforces_existing(
+        self,
+        memory: SemanticMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test that storing duplicate fact reinforces existing."""
+        # Mock existing fact found - needs to be found first
+        existing_mock = create_mock_fact_model(confidence=0.7)
+        find_result = MagicMock()
+        find_result.scalar_one_or_none.return_value = existing_mock
+
+        # Second find for reinforce_fact
+        find_for_reinforce = MagicMock()
+        find_for_reinforce.scalar_one_or_none.return_value = existing_mock
+
+        # Mock update result - returns the updated mock
+        updated_mock = create_mock_fact_model(confidence=0.8)
+        update_result = MagicMock()
+        update_result.scalar_one.return_value = updated_mock
+
+        mock_session.execute.side_effect = [
+            find_result,  # _find_existing_fact
+            find_for_reinforce,  # reinforce_fact query
+            update_result,  # reinforce_fact update
+        ]
+
+        fact_data = FactCreate(
+            subject="FastAPI",
+            predicate="uses",
+            object="Starlette",
+        )
+
+        _ = await memory.store_fact(fact_data)
+
+        # Should have called execute three times (find + find + update)
+        assert mock_session.execute.call_count == 3
+
+
+class TestSemanticMemorySearch:
+    """Tests for fact search methods."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        session.execute.return_value = mock_result
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> SemanticMemory:
+        """Create a SemanticMemory instance."""
+        return SemanticMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_search_facts(
+        self,
+        memory: SemanticMemory,
+    ) -> None:
+        """Test searching for facts."""
+        results = await memory.search_facts("Python programming")
+
+        assert isinstance(results, list)
+
+    @pytest.mark.asyncio
+    async def test_search_facts_with_project_filter(
+        self,
+        memory: SemanticMemory,
+    ) -> None:
+        """Test searching for facts with project filter."""
+        project_id = uuid4()
+        results = await memory.search_facts("Python", project_id=project_id)
+
+        assert isinstance(results, list)
+
+    @pytest.mark.asyncio
+    async def test_get_by_entity(
+        self,
+        memory: SemanticMemory,
+    ) -> None:
+        """Test getting facts by entity."""
+        results = await memory.get_by_entity("FastAPI")
+
+        assert isinstance(results, list)
+
+    @pytest.mark.asyncio
+    async def test_get_by_subject(
+        self,
+        memory: SemanticMemory,
+    ) -> None:
+        """Test getting facts by subject."""
+        results = await memory.get_by_subject("Python")
+
+        assert isinstance(results, list)
+
+    @pytest.mark.asyncio
+    async def test_get_by_id_not_found(
+        self,
+        memory: SemanticMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test get_by_id returns None when not found."""
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        result = await memory.get_by_id(uuid4())
+
+        assert result is None
+
+
+class TestSemanticMemoryReinforcement:
+    """Tests for fact reinforcement."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> SemanticMemory:
+        """Create a SemanticMemory instance."""
+        return SemanticMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_reinforce_fact(
+        self,
+        memory: SemanticMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test reinforcing a fact."""
+        existing_mock = create_mock_fact_model(confidence=0.7)
+
+        # First query: find fact
+        find_result = MagicMock()
+        find_result.scalar_one_or_none.return_value = existing_mock
+
+        # Second query: update fact
+        updated_mock = create_mock_fact_model(confidence=0.8)
+        update_result = MagicMock()
+        update_result.scalar_one.return_value = updated_mock
+
+        mock_session.execute.side_effect = [find_result, update_result]
+
+        result = await memory.reinforce_fact(existing_mock.id, confidence_boost=0.1)
+
+        assert result.confidence == 0.8
+
+    @pytest.mark.asyncio
+    async def test_reinforce_fact_not_found(
+        self,
+        memory: SemanticMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test reinforcing a non-existent fact raises error."""
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        with pytest.raises(ValueError, match="Fact not found"):
+            await memory.reinforce_fact(uuid4())
+
+    @pytest.mark.asyncio
+    async def test_deprecate_fact(
+        self,
+        memory: SemanticMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test deprecating a fact."""
+        existing_mock = create_mock_fact_model(confidence=0.8)
+
+        find_result = MagicMock()
+        find_result.scalar_one_or_none.return_value = existing_mock
+
+        deprecated_mock = create_mock_fact_model(confidence=0.0)
+        update_result = MagicMock()
+        update_result.scalar_one_or_none.return_value = deprecated_mock
+
+        mock_session.execute.side_effect = [find_result, update_result]
+
+        result = await memory.deprecate_fact(existing_mock.id, reason="Outdated")
+
+        assert result is not None
+        assert result.confidence == 0.0
+
+    @pytest.mark.asyncio
+    async def test_deprecate_fact_not_found(
+        self,
+        memory: SemanticMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test deprecating non-existent fact returns None."""
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        result = await memory.deprecate_fact(uuid4(), reason="Test")
+
+        assert result is None
+
+
+class TestSemanticMemoryConflictResolution:
+    """Tests for conflict resolution."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> SemanticMemory:
+        """Create a SemanticMemory instance."""
+        return SemanticMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_resolve_conflict_empty_list(
+        self,
+        memory: SemanticMemory,
+    ) -> None:
+        """Test resolving conflict with empty list."""
+        result = await memory.resolve_conflict([])
+
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_resolve_conflict_keeps_highest_confidence(
+        self,
+        memory: SemanticMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test that conflict resolution keeps highest confidence fact."""
+        fact_low = create_mock_fact_model(confidence=0.5)
+        fact_high = create_mock_fact_model(confidence=0.9)
+
+        # Mock finding the facts
+        find_result = MagicMock()
+        find_result.scalars.return_value.all.return_value = [fact_low, fact_high]
+
+        # Mock deprecation (find + update)
+        find_one_result = MagicMock()
+        find_one_result.scalar_one_or_none.return_value = fact_low
+        update_result = MagicMock()
+        update_result.scalar_one_or_none.return_value = fact_low
+
+        mock_session.execute.side_effect = [find_result, find_one_result, update_result]
+
+        result = await memory.resolve_conflict([fact_low.id, fact_high.id])
+
+        assert result is not None
+        assert result.confidence == 0.9
+
+
+class TestSemanticMemoryStats:
+    """Tests for statistics methods."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        return session
+
+    @pytest.fixture
+    def memory(self, mock_session: AsyncMock) -> SemanticMemory:
+        """Create a SemanticMemory instance."""
+        return SemanticMemory(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_get_stats_empty(
+        self,
+        memory: SemanticMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test getting stats for empty project."""
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        mock_session.execute.return_value = mock_result
+
+        stats = await memory.get_stats(uuid4())
+
+        assert stats["total_facts"] == 0
+        assert stats["avg_confidence"] == 0.0
+
+    @pytest.mark.asyncio
+    async def test_count(
+        self,
+        memory: SemanticMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test counting facts."""
+        facts = [create_mock_fact_model() for _ in range(5)]
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = facts
+        mock_session.execute.return_value = mock_result
+
+        count = await memory.count(uuid4())
+
+        assert count == 5
+
+    @pytest.mark.asyncio
+    async def test_delete(
+        self,
+        memory: SemanticMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test deleting a fact."""
+        existing_mock = create_mock_fact_model()
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = existing_mock
+        mock_session.execute.return_value = mock_result
+        mock_session.delete = AsyncMock()
+
+        result = await memory.delete(existing_mock.id)
+
+        assert result is True
+        mock_session.delete.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_delete_not_found(
+        self,
+        memory: SemanticMemory,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test deleting non-existent fact."""
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        result = await memory.delete(uuid4())
+
+        assert result is False

backend/tests/unit/services/memory/semantic/test_verification.py

@@ -0,0 +1,298 @@
+# tests/unit/services/memory/semantic/test_verification.py
+"""Unit tests for fact verification."""
+
+from datetime import UTC, datetime
+from unittest.mock import AsyncMock, MagicMock
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.semantic.verification import (
+    FactConflict,
+    FactVerifier,
+    VerificationResult,
+)
+
+
+def create_mock_fact_model(
+    subject="FastAPI",
+    predicate="uses",
+    obj="Starlette",
+    confidence=0.8,
+    project_id=None,
+):
+    """Create a mock fact model for testing."""
+    mock = MagicMock()
+    mock.id = uuid4()
+    mock.project_id = project_id
+    mock.subject = subject
+    mock.predicate = predicate
+    mock.object = obj
+    mock.confidence = confidence
+    mock.source_episode_ids = []
+    mock.first_learned = datetime.now(UTC)
+    mock.last_reinforced = datetime.now(UTC)
+    mock.reinforcement_count = 1
+    mock.embedding = None
+    mock.created_at = datetime.now(UTC)
+    mock.updated_at = datetime.now(UTC)
+    return mock
+
+
+class TestFactConflict:
+    """Tests for FactConflict dataclass."""
+
+    def test_to_dict(self) -> None:
+        """Test converting conflict to dictionary."""
+        conflict = FactConflict(
+            fact_a_id=uuid4(),
+            fact_b_id=uuid4(),
+            conflict_type="contradiction",
+            description="Test conflict",
+            suggested_resolution="Keep higher confidence",
+        )
+
+        result = conflict.to_dict()
+
+        assert "fact_a_id" in result
+        assert "fact_b_id" in result
+        assert result["conflict_type"] == "contradiction"
+        assert result["description"] == "Test conflict"
+
+
+class TestVerificationResult:
+    """Tests for VerificationResult dataclass."""
+
+    def test_default_values(self) -> None:
+        """Test default values."""
+        result = VerificationResult(is_valid=True)
+
+        assert result.is_valid is True
+        assert result.confidence_adjustment == 0.0
+        assert result.conflicts == []
+        assert result.supporting_facts == []
+        assert result.messages == []
+
+
+class TestFactVerifier:
+    """Tests for FactVerifier class."""
+
+    @pytest.fixture
+    def mock_session(self) -> AsyncMock:
+        """Create a mock database session."""
+        session = AsyncMock()
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        session.execute.return_value = mock_result
+        return session
+
+    @pytest.fixture
+    def verifier(self, mock_session: AsyncMock) -> FactVerifier:
+        """Create a fact verifier."""
+        return FactVerifier(session=mock_session)
+
+    @pytest.mark.asyncio
+    async def test_verify_fact_valid(
+        self,
+        verifier: FactVerifier,
+    ) -> None:
+        """Test verifying a valid fact with no conflicts."""
+        result = await verifier.verify_fact(
+            subject="Python",
+            predicate="is_a",
+            obj="programming language",
+        )
+
+        assert result.is_valid is True
+        assert len(result.conflicts) == 0
+
+    @pytest.mark.asyncio
+    async def test_verify_fact_with_support(
+        self,
+        verifier: FactVerifier,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test verifying a fact with supporting facts."""
+        # Mock finding supporting facts
+        supporting = [create_mock_fact_model()]
+
+        # First query: contradictions (empty)
+        contradiction_result = MagicMock()
+        contradiction_result.scalars.return_value.all.return_value = []
+
+        # Second query: supporting facts
+        support_result = MagicMock()
+        support_result.scalars.return_value.all.return_value = supporting
+
+        mock_session.execute.side_effect = [contradiction_result, support_result]
+
+        result = await verifier.verify_fact(
+            subject="Python",
+            predicate="uses",
+            obj="dynamic typing",
+        )
+
+        assert result.is_valid is True
+        assert len(result.supporting_facts) >= 1
+        assert result.confidence_adjustment > 0
+
+    @pytest.mark.asyncio
+    async def test_verify_fact_with_contradiction(
+        self,
+        verifier: FactVerifier,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test verifying a fact with contradictions."""
+        # Mock finding contradicting fact
+        contradicting = create_mock_fact_model(
+            subject="Python",
+            predicate="does_not_use",
+            obj="static typing",
+        )
+
+        contradiction_result = MagicMock()
+        contradiction_result.scalars.return_value.all.return_value = [contradicting]
+
+        support_result = MagicMock()
+        support_result.scalars.return_value.all.return_value = []
+
+        mock_session.execute.side_effect = [contradiction_result, support_result]
+
+        result = await verifier.verify_fact(
+            subject="Python",
+            predicate="uses",
+            obj="static typing",
+        )
+
+        assert result.is_valid is False
+        assert len(result.conflicts) >= 1
+        assert result.confidence_adjustment < 0
+
+    def test_get_opposite_predicates(
+        self,
+        verifier: FactVerifier,
+    ) -> None:
+        """Test getting opposite predicates."""
+        opposites = verifier._get_opposite_predicates("uses")
+
+        assert "does_not_use" in opposites
+
+    def test_get_opposite_predicates_unknown(
+        self,
+        verifier: FactVerifier,
+    ) -> None:
+        """Test getting opposites for unknown predicate."""
+        opposites = verifier._get_opposite_predicates("unknown_predicate")
+
+        assert opposites == []
+
+    @pytest.mark.asyncio
+    async def test_find_all_conflicts_empty(
+        self,
+        verifier: FactVerifier,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test finding all conflicts in empty fact base."""
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = []
+        mock_session.execute.return_value = mock_result
+
+        conflicts = await verifier.find_all_conflicts()
+
+        assert conflicts == []
+
+    @pytest.mark.asyncio
+    async def test_find_all_conflicts_no_conflicts(
+        self,
+        verifier: FactVerifier,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test finding conflicts when there are none."""
+        # Two facts with different subjects
+        fact1 = create_mock_fact_model(subject="Python", predicate="uses")
+        fact2 = create_mock_fact_model(subject="JavaScript", predicate="uses")
+
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = [fact1, fact2]
+        mock_session.execute.return_value = mock_result
+
+        conflicts = await verifier.find_all_conflicts()
+
+        assert conflicts == []
+
+    @pytest.mark.asyncio
+    async def test_find_all_conflicts_with_contradiction(
+        self,
+        verifier: FactVerifier,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test finding contradicting facts."""
+        # Two contradicting facts
+        fact1 = create_mock_fact_model(
+            subject="Python",
+            predicate="best_practice",
+            obj="Use type hints",
+        )
+        fact2 = create_mock_fact_model(
+            subject="Python",
+            predicate="anti_pattern",
+            obj="Use type hints",
+        )
+
+        mock_result = MagicMock()
+        mock_result.scalars.return_value.all.return_value = [fact1, fact2]
+        mock_session.execute.return_value = mock_result
+
+        conflicts = await verifier.find_all_conflicts()
+
+        assert len(conflicts) == 1
+        assert conflicts[0].conflict_type == "contradiction"
+
+    @pytest.mark.asyncio
+    async def test_get_fact_reliability_score_not_found(
+        self,
+        verifier: FactVerifier,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test reliability score for non-existent fact."""
+        mock_result = MagicMock()
+        mock_result.scalar_one_or_none.return_value = None
+        mock_session.execute.return_value = mock_result
+
+        score = await verifier.get_fact_reliability_score(uuid4())
+
+        assert score == 0.0
+
+    @pytest.mark.asyncio
+    async def test_get_fact_reliability_score(
+        self,
+        verifier: FactVerifier,
+        mock_session: AsyncMock,
+    ) -> None:
+        """Test calculating reliability score."""
+        fact = create_mock_fact_model(confidence=0.8)
+        fact.reinforcement_count = 5
+
+        # Query 1: Get fact
+        fact_result = MagicMock()
+        fact_result.scalar_one_or_none.return_value = fact
+
+        # Query 2: Supporting facts
+        support_result = MagicMock()
+        support_result.scalars.return_value.all.return_value = []
+
+        # Query 3: Contradictions
+        conflict_result = MagicMock()
+        conflict_result.scalars.return_value.all.return_value = []
+
+        mock_session.execute.side_effect = [
+            fact_result,
+            support_result,
+            conflict_result,
+        ]
+
+        score = await verifier.get_fact_reliability_score(fact.id)
+
+        # Score should be >= confidence (0.8) due to reinforcement bonus
+        assert score >= 0.8
+        assert score <= 1.0

backend/tests/unit/services/memory/test_config.py

@@ -0,0 +1,243 @@
+"""
+Tests for Memory System Configuration.
+"""
+
+import pytest
+from pydantic import ValidationError
+
+from app.services.memory.config import (
+    MemorySettings,
+    get_default_settings,
+    get_memory_settings,
+    reset_memory_settings,
+)
+
+
+class TestMemorySettings:
+    """Tests for MemorySettings class."""
+
+    def test_default_settings(self) -> None:
+        """Test that default settings are valid."""
+        settings = MemorySettings()
+
+        # Working memory defaults
+        assert settings.working_memory_backend == "redis"
+        assert settings.working_memory_default_ttl_seconds == 3600
+        assert settings.working_memory_max_items_per_session == 1000
+
+        # Redis defaults
+        assert settings.redis_url == "redis://localhost:6379/0"
+        assert settings.redis_prefix == "mem"
+
+        # Episodic defaults
+        assert settings.episodic_max_episodes_per_project == 10000
+        assert settings.episodic_default_importance == 0.5
+
+        # Semantic defaults
+        assert settings.semantic_max_facts_per_project == 50000
+        assert settings.semantic_min_confidence == 0.1
+
+        # Procedural defaults
+        assert settings.procedural_max_procedures_per_project == 1000
+        assert settings.procedural_min_success_rate == 0.3
+
+        # Embedding defaults
+        assert settings.embedding_model == "text-embedding-3-small"
+        assert settings.embedding_dimensions == 1536
+
+        # Retrieval defaults
+        assert settings.retrieval_default_limit == 10
+        assert settings.retrieval_max_limit == 100
+
+    def test_invalid_backend(self) -> None:
+        """Test that invalid backend raises error."""
+        with pytest.raises(ValidationError) as exc_info:
+            MemorySettings(working_memory_backend="invalid")
+
+        assert "backend must be one of" in str(exc_info.value)
+
+    def test_valid_backends(self) -> None:
+        """Test valid backend values."""
+        redis_settings = MemorySettings(working_memory_backend="redis")
+        assert redis_settings.working_memory_backend == "redis"
+
+        memory_settings = MemorySettings(working_memory_backend="memory")
+        assert memory_settings.working_memory_backend == "memory"
+
+    def test_invalid_embedding_model(self) -> None:
+        """Test that invalid embedding model raises error."""
+        with pytest.raises(ValidationError) as exc_info:
+            MemorySettings(embedding_model="invalid-model")
+
+        assert "embedding_model must be one of" in str(exc_info.value)
+
+    def test_valid_embedding_models(self) -> None:
+        """Test valid embedding model values."""
+        for model in [
+            "text-embedding-3-small",
+            "text-embedding-3-large",
+            "text-embedding-ada-002",
+        ]:
+            settings = MemorySettings(embedding_model=model)
+            assert settings.embedding_model == model
+
+    def test_retrieval_limit_validation(self) -> None:
+        """Test that default limit cannot exceed max limit."""
+        with pytest.raises(ValidationError) as exc_info:
+            MemorySettings(
+                retrieval_default_limit=50,
+                retrieval_max_limit=25,
+            )
+
+        assert "cannot exceed retrieval_max_limit" in str(exc_info.value)
+
+    def test_valid_retrieval_limits(self) -> None:
+        """Test valid retrieval limit combinations."""
+        settings = MemorySettings(
+            retrieval_default_limit=10,
+            retrieval_max_limit=50,
+        )
+        assert settings.retrieval_default_limit == 10
+        assert settings.retrieval_max_limit == 50
+
+        # Equal limits should be valid
+        settings = MemorySettings(
+            retrieval_default_limit=25,
+            retrieval_max_limit=25,
+        )
+        assert settings.retrieval_default_limit == 25
+        assert settings.retrieval_max_limit == 25
+
+    def test_ttl_bounds(self) -> None:
+        """Test TTL setting bounds."""
+        # Valid TTL
+        settings = MemorySettings(working_memory_default_ttl_seconds=1800)
+        assert settings.working_memory_default_ttl_seconds == 1800
+
+        # Too low
+        with pytest.raises(ValidationError):
+            MemorySettings(working_memory_default_ttl_seconds=30)
+
+        # Too high
+        with pytest.raises(ValidationError):
+            MemorySettings(working_memory_default_ttl_seconds=100000)
+
+    def test_confidence_bounds(self) -> None:
+        """Test confidence score bounds."""
+        # Valid confidence
+        settings = MemorySettings(semantic_min_confidence=0.5)
+        assert settings.semantic_min_confidence == 0.5
+
+        # Bounds
+        settings = MemorySettings(semantic_min_confidence=0.0)
+        assert settings.semantic_min_confidence == 0.0
+
+        settings = MemorySettings(semantic_min_confidence=1.0)
+        assert settings.semantic_min_confidence == 1.0
+
+        # Out of bounds
+        with pytest.raises(ValidationError):
+            MemorySettings(semantic_min_confidence=-0.1)
+
+        with pytest.raises(ValidationError):
+            MemorySettings(semantic_min_confidence=1.1)
+
+    def test_get_working_memory_config(self) -> None:
+        """Test working memory config dictionary."""
+        settings = MemorySettings()
+        config = settings.get_working_memory_config()
+
+        assert config["backend"] == "redis"
+        assert config["default_ttl_seconds"] == 3600
+        assert config["max_items_per_session"] == 1000
+        assert config["max_value_size_bytes"] == 1048576
+        assert config["checkpoint_enabled"] is True
+
+    def test_get_redis_config(self) -> None:
+        """Test Redis config dictionary."""
+        settings = MemorySettings()
+        config = settings.get_redis_config()
+
+        assert config["url"] == "redis://localhost:6379/0"
+        assert config["prefix"] == "mem"
+        assert config["connection_timeout_seconds"] == 5
+
+    def test_get_embedding_config(self) -> None:
+        """Test embedding config dictionary."""
+        settings = MemorySettings()
+        config = settings.get_embedding_config()
+
+        assert config["model"] == "text-embedding-3-small"
+        assert config["dimensions"] == 1536
+        assert config["batch_size"] == 100
+        assert config["cache_enabled"] is True
+
+    def test_get_consolidation_config(self) -> None:
+        """Test consolidation config dictionary."""
+        settings = MemorySettings()
+        config = settings.get_consolidation_config()
+
+        assert config["enabled"] is True
+        assert config["batch_size"] == 100
+        assert config["schedule_cron"] == "0 3 * * *"
+        assert config["working_to_episodic_delay_minutes"] == 30
+
+    def test_to_dict(self) -> None:
+        """Test full settings to dictionary."""
+        settings = MemorySettings()
+        config = settings.to_dict()
+
+        assert "working_memory" in config
+        assert "redis" in config
+        assert "episodic" in config
+        assert "semantic" in config
+        assert "procedural" in config
+        assert "embedding" in config
+        assert "retrieval" in config
+        assert "consolidation" in config
+        assert "pruning" in config
+        assert "cache" in config
+        assert "performance" in config
+
+
+class TestMemorySettingsSingleton:
+    """Tests for MemorySettings singleton functions."""
+
+    def setup_method(self) -> None:
+        """Reset singleton before each test."""
+        reset_memory_settings()
+
+    def teardown_method(self) -> None:
+        """Reset singleton after each test."""
+        reset_memory_settings()
+
+    def test_get_memory_settings_singleton(self) -> None:
+        """Test that get_memory_settings returns same instance."""
+        settings1 = get_memory_settings()
+        settings2 = get_memory_settings()
+
+        assert settings1 is settings2
+
+    def test_reset_memory_settings(self) -> None:
+        """Test that reset creates new instance."""
+        settings1 = get_memory_settings()
+        reset_memory_settings()
+        settings2 = get_memory_settings()
+
+        assert settings1 is not settings2
+
+    def test_get_default_settings_cached(self) -> None:
+        """Test that get_default_settings is cached."""
+        # Clear the lru_cache first
+        get_default_settings.cache_clear()
+
+        settings1 = get_default_settings()
+        settings2 = get_default_settings()
+
+        assert settings1 is settings2
+
+    def test_default_settings_immutable_pattern(self) -> None:
+        """Test that default settings provide consistent values."""
+        defaults = get_default_settings()
+        assert defaults.working_memory_backend == "redis"
+        assert defaults.embedding_model == "text-embedding-3-small"

backend/tests/unit/services/memory/test_exceptions.py

@@ -0,0 +1,325 @@
+"""
+Tests for Memory System Exceptions.
+"""
+
+from uuid import uuid4
+
+import pytest
+
+from app.services.memory.exceptions import (
+    CheckpointError,
+    EmbeddingError,
+    MemoryCapacityError,
+    MemoryConflictError,
+    MemoryConsolidationError,
+    MemoryError,
+    MemoryExpiredError,
+    MemoryNotFoundError,
+    MemoryRetrievalError,
+    MemoryScopeError,
+    MemorySerializationError,
+    MemoryStorageError,
+)
+
+
+class TestMemoryError:
+    """Tests for base MemoryError class."""
+
+    def test_basic_error(self) -> None:
+        """Test creating a basic memory error."""
+        error = MemoryError("Something went wrong")
+
+        assert str(error) == "Something went wrong"
+        assert error.message == "Something went wrong"
+        assert error.memory_type is None
+        assert error.scope_type is None
+        assert error.scope_id is None
+        assert error.details == {}
+
+    def test_error_with_context(self) -> None:
+        """Test creating an error with context."""
+        error = MemoryError(
+            "Operation failed",
+            memory_type="episodic",
+            scope_type="project",
+            scope_id="proj-123",
+            details={"operation": "search"},
+        )
+
+        assert error.memory_type == "episodic"
+        assert error.scope_type == "project"
+        assert error.scope_id == "proj-123"
+        assert error.details == {"operation": "search"}
+
+    def test_error_inheritance(self) -> None:
+        """Test that MemoryError inherits from Exception."""
+        error = MemoryError("test")
+        assert isinstance(error, Exception)
+
+
+class TestMemoryNotFoundError:
+    """Tests for MemoryNotFoundError class."""
+
+    def test_default_message(self) -> None:
+        """Test default error message."""
+        error = MemoryNotFoundError()
+        assert error.message == "Memory not found"
+
+    def test_with_memory_id(self) -> None:
+        """Test error with memory ID."""
+        memory_id = uuid4()
+        error = MemoryNotFoundError(
+            f"Memory {memory_id} not found",
+            memory_id=memory_id,
+        )
+
+        assert error.memory_id == memory_id
+
+    def test_with_key(self) -> None:
+        """Test error with key."""
+        error = MemoryNotFoundError(
+            "Key not found",
+            key="my_key",
+        )
+
+        assert error.key == "my_key"
+
+
+class TestMemoryCapacityError:
+    """Tests for MemoryCapacityError class."""
+
+    def test_default_message(self) -> None:
+        """Test default error message."""
+        error = MemoryCapacityError()
+        assert error.message == "Memory capacity exceeded"
+
+    def test_with_sizes(self) -> None:
+        """Test error with size information."""
+        error = MemoryCapacityError(
+            "Working memory full",
+            current_size=1048576,
+            max_size=1000000,
+            item_count=500,
+        )
+
+        assert error.current_size == 1048576
+        assert error.max_size == 1000000
+        assert error.item_count == 500
+
+
+class TestMemoryExpiredError:
+    """Tests for MemoryExpiredError class."""
+
+    def test_default_message(self) -> None:
+        """Test default error message."""
+        error = MemoryExpiredError()
+        assert error.message == "Memory has expired"
+
+    def test_with_expiry_info(self) -> None:
+        """Test error with expiry information."""
+        error = MemoryExpiredError(
+            "Key expired",
+            key="session_data",
+            expired_at="2025-01-05T00:00:00Z",
+        )
+
+        assert error.key == "session_data"
+        assert error.expired_at == "2025-01-05T00:00:00Z"
+
+
+class TestMemoryStorageError:
+    """Tests for MemoryStorageError class."""
+
+    def test_default_message(self) -> None:
+        """Test default error message."""
+        error = MemoryStorageError()
+        assert error.message == "Memory storage operation failed"
+
+    def test_with_operation_info(self) -> None:
+        """Test error with operation information."""
+        error = MemoryStorageError(
+            "Redis write failed",
+            operation="set",
+            backend="redis",
+        )
+
+        assert error.operation == "set"
+        assert error.backend == "redis"
+
+
+class TestMemorySerializationError:
+    """Tests for MemorySerializationError class."""
+
+    def test_default_message(self) -> None:
+        """Test default error message."""
+        error = MemorySerializationError()
+        assert error.message == "Memory serialization failed"
+
+    def test_with_content_type(self) -> None:
+        """Test error with content type."""
+        error = MemorySerializationError(
+            "Cannot serialize function",
+            content_type="function",
+        )
+
+        assert error.content_type == "function"
+
+
+class TestMemoryScopeError:
+    """Tests for MemoryScopeError class."""
+
+    def test_default_message(self) -> None:
+        """Test default error message."""
+        error = MemoryScopeError()
+        assert error.message == "Memory scope error"
+
+    def test_with_scope_info(self) -> None:
+        """Test error with scope information."""
+        error = MemoryScopeError(
+            "Scope access denied",
+            requested_scope="global",
+            allowed_scopes=["project", "session"],
+        )
+
+        assert error.requested_scope == "global"
+        assert error.allowed_scopes == ["project", "session"]
+
+
+class TestMemoryConsolidationError:
+    """Tests for MemoryConsolidationError class."""
+
+    def test_default_message(self) -> None:
+        """Test default error message."""
+        error = MemoryConsolidationError()
+        assert error.message == "Memory consolidation failed"
+
+    def test_with_consolidation_info(self) -> None:
+        """Test error with consolidation information."""
+        error = MemoryConsolidationError(
+            "Transfer failed",
+            source_type="working",
+            target_type="episodic",
+            items_processed=50,
+        )
+
+        assert error.source_type == "working"
+        assert error.target_type == "episodic"
+        assert error.items_processed == 50
+
+
+class TestMemoryRetrievalError:
+    """Tests for MemoryRetrievalError class."""
+
+    def test_default_message(self) -> None:
+        """Test default error message."""
+        error = MemoryRetrievalError()
+        assert error.message == "Memory retrieval failed"
+
+    def test_with_query_info(self) -> None:
+        """Test error with query information."""
+        error = MemoryRetrievalError(
+            "Search timeout",
+            query="complex search query",
+            retrieval_type="semantic",
+        )
+
+        assert error.query == "complex search query"
+        assert error.retrieval_type == "semantic"
+
+
+class TestEmbeddingError:
+    """Tests for EmbeddingError class."""
+
+    def test_default_message(self) -> None:
+        """Test default error message."""
+        error = EmbeddingError()
+        assert error.message == "Embedding generation failed"
+
+    def test_with_embedding_info(self) -> None:
+        """Test error with embedding information."""
+        error = EmbeddingError(
+            "Content too long",
+            content_length=100000,
+            model="text-embedding-3-small",
+        )
+
+        assert error.content_length == 100000
+        assert error.model == "text-embedding-3-small"
+
+
+class TestCheckpointError:
+    """Tests for CheckpointError class."""
+
+    def test_default_message(self) -> None:
+        """Test default error message."""
+        error = CheckpointError()
+        assert error.message == "Checkpoint operation failed"
+
+    def test_with_checkpoint_info(self) -> None:
+        """Test error with checkpoint information."""
+        error = CheckpointError(
+            "Restore failed",
+            checkpoint_id="chk-123",
+            operation="restore",
+        )
+
+        assert error.checkpoint_id == "chk-123"
+        assert error.operation == "restore"
+
+
+class TestMemoryConflictError:
+    """Tests for MemoryConflictError class."""
+
+    def test_default_message(self) -> None:
+        """Test default error message."""
+        error = MemoryConflictError()
+        assert error.message == "Memory conflict detected"
+
+    def test_with_conflict_info(self) -> None:
+        """Test error with conflict information."""
+        id1 = uuid4()
+        id2 = uuid4()
+        error = MemoryConflictError(
+            "Contradictory facts detected",
+            conflicting_ids=[id1, id2],
+            conflict_type="semantic",
+        )
+
+        assert len(error.conflicting_ids) == 2
+        assert error.conflict_type == "semantic"
+
+
+class TestExceptionHierarchy:
+    """Tests for exception inheritance hierarchy."""
+
+    def test_all_exceptions_inherit_from_memory_error(self) -> None:
+        """Test that all exceptions inherit from MemoryError."""
+        exceptions = [
+            MemoryNotFoundError(),
+            MemoryCapacityError(),
+            MemoryExpiredError(),
+            MemoryStorageError(),
+            MemorySerializationError(),
+            MemoryScopeError(),
+            MemoryConsolidationError(),
+            MemoryRetrievalError(),
+            EmbeddingError(),
+            CheckpointError(),
+            MemoryConflictError(),
+        ]
+
+        for exc in exceptions:
+            assert isinstance(exc, MemoryError)
+            assert isinstance(exc, Exception)
+
+    def test_can_catch_base_error(self) -> None:
+        """Test that catching MemoryError catches all subclasses."""
+        exceptions = [
+            MemoryNotFoundError("not found"),
+            MemoryCapacityError("capacity"),
+            MemoryStorageError("storage"),
+        ]
+
+        for exc in exceptions:
+            with pytest.raises(MemoryError):
+                raise exc

backend/tests/unit/services/memory/test_types.py

@@ -0,0 +1,411 @@
+"""
+Tests for Memory System Types.
+"""
+
+from datetime import datetime, timedelta
+from uuid import uuid4
+
+from app.services.memory.types import (
+    ConsolidationStatus,
+    ConsolidationType,
+    EpisodeCreate,
+    Fact,
+    FactCreate,
+    MemoryItem,
+    MemoryStats,
+    MemoryType,
+    Outcome,
+    Procedure,
+    ProcedureCreate,
+    RetrievalResult,
+    ScopeContext,
+    ScopeLevel,
+    Step,
+    TaskState,
+    WorkingMemoryItem,
+)
+
+
+class TestEnums:
+    """Tests for memory enums."""
+
+    def test_memory_type_values(self) -> None:
+        """Test MemoryType enum values."""
+        assert MemoryType.WORKING == "working"
+        assert MemoryType.EPISODIC == "episodic"
+        assert MemoryType.SEMANTIC == "semantic"
+        assert MemoryType.PROCEDURAL == "procedural"
+
+    def test_scope_level_values(self) -> None:
+        """Test ScopeLevel enum values."""
+        assert ScopeLevel.GLOBAL == "global"
+        assert ScopeLevel.PROJECT == "project"
+        assert ScopeLevel.AGENT_TYPE == "agent_type"
+        assert ScopeLevel.AGENT_INSTANCE == "agent_instance"
+        assert ScopeLevel.SESSION == "session"
+
+    def test_outcome_values(self) -> None:
+        """Test Outcome enum values."""
+        assert Outcome.SUCCESS == "success"
+        assert Outcome.FAILURE == "failure"
+        assert Outcome.PARTIAL == "partial"
+
+    def test_consolidation_status_values(self) -> None:
+        """Test ConsolidationStatus enum values."""
+        assert ConsolidationStatus.PENDING == "pending"
+        assert ConsolidationStatus.RUNNING == "running"
+        assert ConsolidationStatus.COMPLETED == "completed"
+        assert ConsolidationStatus.FAILED == "failed"
+
+    def test_consolidation_type_values(self) -> None:
+        """Test ConsolidationType enum values."""
+        assert ConsolidationType.WORKING_TO_EPISODIC == "working_to_episodic"
+        assert ConsolidationType.EPISODIC_TO_SEMANTIC == "episodic_to_semantic"
+        assert ConsolidationType.EPISODIC_TO_PROCEDURAL == "episodic_to_procedural"
+        assert ConsolidationType.PRUNING == "pruning"
+
+
+class TestScopeContext:
+    """Tests for ScopeContext dataclass."""
+
+    def test_create_scope_context(self) -> None:
+        """Test creating a scope context."""
+        scope = ScopeContext(
+            scope_type=ScopeLevel.SESSION,
+            scope_id="sess-123",
+        )
+
+        assert scope.scope_type == ScopeLevel.SESSION
+        assert scope.scope_id == "sess-123"
+        assert scope.parent is None
+
+    def test_scope_with_parent(self) -> None:
+        """Test creating a scope with parent."""
+        parent = ScopeContext(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="proj-123",
+        )
+        child = ScopeContext(
+            scope_type=ScopeLevel.SESSION,
+            scope_id="sess-456",
+            parent=parent,
+        )
+
+        assert child.parent is parent
+        assert child.parent.scope_type == ScopeLevel.PROJECT
+
+    def test_get_hierarchy(self) -> None:
+        """Test getting scope hierarchy."""
+        global_scope = ScopeContext(
+            scope_type=ScopeLevel.GLOBAL,
+            scope_id="global",
+        )
+        project_scope = ScopeContext(
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="proj-123",
+            parent=global_scope,
+        )
+        session_scope = ScopeContext(
+            scope_type=ScopeLevel.SESSION,
+            scope_id="sess-456",
+            parent=project_scope,
+        )
+
+        hierarchy = session_scope.get_hierarchy()
+
+        assert len(hierarchy) == 3
+        assert hierarchy[0].scope_type == ScopeLevel.GLOBAL
+        assert hierarchy[1].scope_type == ScopeLevel.PROJECT
+        assert hierarchy[2].scope_type == ScopeLevel.SESSION
+
+    def test_to_key_prefix(self) -> None:
+        """Test converting scope to key prefix."""
+        scope = ScopeContext(
+            scope_type=ScopeLevel.SESSION,
+            scope_id="sess-123",
+        )
+
+        prefix = scope.to_key_prefix()
+        assert prefix == "session:sess-123"
+
+
+class TestMemoryItem:
+    """Tests for MemoryItem dataclass."""
+
+    def test_create_memory_item(self) -> None:
+        """Test creating a memory item."""
+        now = datetime.now()
+        item = MemoryItem(
+            id=uuid4(),
+            memory_type=MemoryType.EPISODIC,
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="proj-123",
+            created_at=now,
+            updated_at=now,
+        )
+
+        assert item.memory_type == MemoryType.EPISODIC
+        assert item.scope_type == ScopeLevel.PROJECT
+        assert item.metadata == {}
+
+    def test_get_age_seconds(self) -> None:
+        """Test getting item age."""
+        past = datetime.now() - timedelta(seconds=100)
+        item = MemoryItem(
+            id=uuid4(),
+            memory_type=MemoryType.SEMANTIC,
+            scope_type=ScopeLevel.GLOBAL,
+            scope_id="global",
+            created_at=past,
+            updated_at=past,
+        )
+
+        age = item.get_age_seconds()
+        assert age >= 100
+        assert age < 105  # Allow small margin
+
+
+class TestWorkingMemoryItem:
+    """Tests for WorkingMemoryItem dataclass."""
+
+    def test_create_working_memory_item(self) -> None:
+        """Test creating a working memory item."""
+        item = WorkingMemoryItem(
+            id=uuid4(),
+            scope_type=ScopeLevel.SESSION,
+            scope_id="sess-123",
+            key="my_key",
+            value={"data": "value"},
+        )
+
+        assert item.key == "my_key"
+        assert item.value == {"data": "value"}
+        assert item.expires_at is None
+
+    def test_is_expired_no_expiry(self) -> None:
+        """Test is_expired with no expiry set."""
+        item = WorkingMemoryItem(
+            id=uuid4(),
+            scope_type=ScopeLevel.SESSION,
+            scope_id="sess-123",
+            key="my_key",
+            value="value",
+        )
+
+        assert item.is_expired() is False
+
+    def test_is_expired_future(self) -> None:
+        """Test is_expired with future expiry."""
+        item = WorkingMemoryItem(
+            id=uuid4(),
+            scope_type=ScopeLevel.SESSION,
+            scope_id="sess-123",
+            key="my_key",
+            value="value",
+            expires_at=datetime.now() + timedelta(hours=1),
+        )
+
+        assert item.is_expired() is False
+
+    def test_is_expired_past(self) -> None:
+        """Test is_expired with past expiry."""
+        item = WorkingMemoryItem(
+            id=uuid4(),
+            scope_type=ScopeLevel.SESSION,
+            scope_id="sess-123",
+            key="my_key",
+            value="value",
+            expires_at=datetime.now() - timedelta(hours=1),
+        )
+
+        assert item.is_expired() is True
+
+
+class TestTaskState:
+    """Tests for TaskState dataclass."""
+
+    def test_create_task_state(self) -> None:
+        """Test creating a task state."""
+        state = TaskState(
+            task_id="task-123",
+            task_type="code_review",
+            description="Review PR #42",
+        )
+
+        assert state.task_id == "task-123"
+        assert state.task_type == "code_review"
+        assert state.status == "in_progress"
+        assert state.current_step == 0
+        assert state.progress_percent == 0.0
+
+    def test_task_state_with_progress(self) -> None:
+        """Test task state with progress."""
+        state = TaskState(
+            task_id="task-123",
+            task_type="implementation",
+            description="Implement feature X",
+            current_step=3,
+            total_steps=5,
+            progress_percent=60.0,
+        )
+
+        assert state.current_step == 3
+        assert state.total_steps == 5
+        assert state.progress_percent == 60.0
+
+
+class TestEpisode:
+    """Tests for Episode and EpisodeCreate dataclasses."""
+
+    def test_create_episode_data(self) -> None:
+        """Test creating episode create data."""
+        data = EpisodeCreate(
+            project_id=uuid4(),
+            session_id="sess-123",
+            task_type="bug_fix",
+            task_description="Fix login bug",
+            actions=[{"action": "read_file", "file": "auth.py"}],
+            context_summary="User reported login issues",
+            outcome=Outcome.SUCCESS,
+            outcome_details="Fixed by updating validation",
+            duration_seconds=120.5,
+            tokens_used=5000,
+        )
+
+        assert data.task_type == "bug_fix"
+        assert data.outcome == Outcome.SUCCESS
+        assert len(data.actions) == 1
+        assert data.importance_score == 0.5  # Default
+
+
+class TestFact:
+    """Tests for Fact and FactCreate dataclasses."""
+
+    def test_create_fact_data(self) -> None:
+        """Test creating fact create data."""
+        data = FactCreate(
+            subject="FastAPI",
+            predicate="uses",
+            object="Starlette framework",
+        )
+
+        assert data.subject == "FastAPI"
+        assert data.predicate == "uses"
+        assert data.object == "Starlette framework"
+        assert data.confidence == 0.8  # Default
+        assert data.project_id is None  # Global fact
+
+
+class TestProcedure:
+    """Tests for Procedure and ProcedureCreate dataclasses."""
+
+    def test_create_procedure_data(self) -> None:
+        """Test creating procedure create data."""
+        data = ProcedureCreate(
+            name="review_pr",
+            trigger_pattern="review pull request",
+            steps=[
+                {"action": "checkout_branch"},
+                {"action": "run_tests"},
+                {"action": "review_changes"},
+            ],
+        )
+
+        assert data.name == "review_pr"
+        assert len(data.steps) == 3
+
+    def test_procedure_success_rate(self) -> None:
+        """Test procedure success rate calculation."""
+        now = datetime.now()
+        procedure = Procedure(
+            id=uuid4(),
+            project_id=None,
+            agent_type_id=None,
+            name="test_proc",
+            trigger_pattern="test",
+            steps=[],
+            success_count=8,
+            failure_count=2,
+            last_used=now,
+            embedding=None,
+            created_at=now,
+            updated_at=now,
+        )
+
+        assert procedure.success_rate == 0.8
+
+    def test_procedure_success_rate_zero_uses(self) -> None:
+        """Test procedure success rate with zero uses."""
+        now = datetime.now()
+        procedure = Procedure(
+            id=uuid4(),
+            project_id=None,
+            agent_type_id=None,
+            name="test_proc",
+            trigger_pattern="test",
+            steps=[],
+            success_count=0,
+            failure_count=0,
+            last_used=None,
+            embedding=None,
+            created_at=now,
+            updated_at=now,
+        )
+
+        assert procedure.success_rate == 0.0
+
+
+class TestStep:
+    """Tests for Step dataclass."""
+
+    def test_create_step(self) -> None:
+        """Test creating a step."""
+        step = Step(
+            order=1,
+            action="run_tests",
+            parameters={"verbose": True},
+            expected_outcome="All tests pass",
+        )
+
+        assert step.order == 1
+        assert step.action == "run_tests"
+        assert step.parameters == {"verbose": True}
+
+
+class TestRetrievalResult:
+    """Tests for RetrievalResult dataclass."""
+
+    def test_create_retrieval_result(self) -> None:
+        """Test creating a retrieval result."""
+        result: RetrievalResult[Fact] = RetrievalResult(
+            items=[],
+            total_count=0,
+            query="test query",
+            retrieval_type="semantic",
+            latency_ms=15.5,
+        )
+
+        assert result.query == "test query"
+        assert result.latency_ms == 15.5
+        assert result.metadata == {}
+
+
+class TestMemoryStats:
+    """Tests for MemoryStats dataclass."""
+
+    def test_create_memory_stats(self) -> None:
+        """Test creating memory stats."""
+        stats = MemoryStats(
+            memory_type=MemoryType.EPISODIC,
+            scope_type=ScopeLevel.PROJECT,
+            scope_id="proj-123",
+            item_count=150,
+            total_size_bytes=1048576,
+            oldest_item_age_seconds=86400,
+            newest_item_age_seconds=60,
+            avg_item_size_bytes=6990.5,
+        )
+
+        assert stats.memory_type == MemoryType.EPISODIC
+        assert stats.item_count == 150
+        assert stats.total_size_bytes == 1048576

backend/tests/unit/services/memory/working/__init__.py

@@ -0,0 +1,2 @@
+# tests/unit/services/memory/working/__init__.py
+"""Unit tests for working memory implementation."""

backend/tests/unit/services/memory/working/test_memory.py

@@ -0,0 +1,391 @@
+# tests/unit/services/memory/working/test_memory.py
+"""Unit tests for WorkingMemory class."""
+
+import pytest
+import pytest_asyncio
+
+from app.services.memory.exceptions import MemoryNotFoundError
+from app.services.memory.types import ScopeContext, ScopeLevel, TaskState
+from app.services.memory.working.memory import WorkingMemory
+from app.services.memory.working.storage import InMemoryStorage
+
+
+@pytest.fixture
+def scope() -> ScopeContext:
+    """Create a test scope."""
+    return ScopeContext(
+        scope_type=ScopeLevel.SESSION,
+        scope_id="test-session-123",
+    )
+
+
+@pytest.fixture
+def storage() -> InMemoryStorage:
+    """Create a test storage backend."""
+    return InMemoryStorage(max_keys=1000)
+
+
+@pytest_asyncio.fixture
+async def memory(scope: ScopeContext, storage: InMemoryStorage) -> WorkingMemory:
+    """Create a WorkingMemory instance for testing."""
+    wm = WorkingMemory(scope=scope, storage=storage)
+    await wm._initialize()
+    return wm
+
+
+class TestWorkingMemoryBasicOperations:
+    """Tests for basic key-value operations."""
+
+    @pytest.mark.asyncio
+    async def test_set_and_get(self, memory: WorkingMemory) -> None:
+        """Test basic set and get."""
+        await memory.set("key1", "value1")
+        result = await memory.get("key1")
+        assert result == "value1"
+
+    @pytest.mark.asyncio
+    async def test_get_with_default(self, memory: WorkingMemory) -> None:
+        """Test get with default value."""
+        result = await memory.get("nonexistent", default="fallback")
+        assert result == "fallback"
+
+    @pytest.mark.asyncio
+    async def test_delete(self, memory: WorkingMemory) -> None:
+        """Test delete operation."""
+        await memory.set("key1", "value1")
+        result = await memory.delete("key1")
+        assert result is True
+        assert await memory.exists("key1") is False
+
+    @pytest.mark.asyncio
+    async def test_exists(self, memory: WorkingMemory) -> None:
+        """Test exists check."""
+        await memory.set("key1", "value1")
+        assert await memory.exists("key1") is True
+        assert await memory.exists("nonexistent") is False
+
+    @pytest.mark.asyncio
+    async def test_reserved_key_prefix(self, memory: WorkingMemory) -> None:
+        """Test that keys starting with _ are rejected."""
+        with pytest.raises(ValueError, match="reserved"):
+            await memory.set("_internal", "value")
+
+    @pytest.mark.asyncio
+    async def test_cannot_delete_internal_keys(self, memory: WorkingMemory) -> None:
+        """Test that internal keys cannot be deleted directly."""
+        with pytest.raises(ValueError, match="internal"):
+            await memory.delete("_task_state")
+
+
+class TestWorkingMemoryListAndClear:
+    """Tests for list and clear operations."""
+
+    @pytest.mark.asyncio
+    async def test_list_keys(self, memory: WorkingMemory) -> None:
+        """Test listing keys."""
+        await memory.set("key1", "value1")
+        await memory.set("key2", "value2")
+
+        keys = await memory.list_keys()
+        assert set(keys) == {"key1", "key2"}
+
+    @pytest.mark.asyncio
+    async def test_list_keys_excludes_internal(self, memory: WorkingMemory) -> None:
+        """Test that list_keys excludes internal keys."""
+        await memory.set("user_key", "value")
+        # Internal keys exist from initialization
+        keys = await memory.list_keys()
+        assert all(not k.startswith("_") for k in keys)
+
+    @pytest.mark.asyncio
+    async def test_list_keys_with_pattern(self, memory: WorkingMemory) -> None:
+        """Test listing keys with pattern."""
+        await memory.set("prefix_a", "value1")
+        await memory.set("prefix_b", "value2")
+        await memory.set("other", "value3")
+
+        keys = await memory.list_keys("prefix_*")
+        assert set(keys) == {"prefix_a", "prefix_b"}
+
+    @pytest.mark.asyncio
+    async def test_get_all(self, memory: WorkingMemory) -> None:
+        """Test getting all key-value pairs."""
+        await memory.set("key1", "value1")
+        await memory.set("key2", "value2")
+
+        result = await memory.get_all()
+        assert result == {"key1": "value1", "key2": "value2"}
+
+    @pytest.mark.asyncio
+    async def test_clear_preserves_internal_state(self, memory: WorkingMemory) -> None:
+        """Test that clear preserves internal state."""
+        # Set some user data
+        await memory.set("user_key", "value")
+
+        # Set task state
+        state = TaskState(
+            task_id="task-1",
+            task_type="test",
+            description="Test task",
+        )
+        await memory.set_task_state(state)
+
+        # Clear
+        await memory.clear()
+
+        # User data should be gone
+        assert await memory.exists("user_key") is False
+
+        # Task state should be preserved
+        restored_state = await memory.get_task_state()
+        assert restored_state is not None
+        assert restored_state.task_id == "task-1"
+
+
+class TestWorkingMemoryTaskState:
+    """Tests for task state operations."""
+
+    @pytest.mark.asyncio
+    async def test_set_and_get_task_state(self, memory: WorkingMemory) -> None:
+        """Test setting and getting task state."""
+        state = TaskState(
+            task_id="task-123",
+            task_type="code_review",
+            description="Review pull request",
+            status="in_progress",
+            current_step=2,
+            total_steps=5,
+            progress_percent=40.0,
+            context={"pr_id": 456},
+        )
+
+        await memory.set_task_state(state)
+        result = await memory.get_task_state()
+
+        assert result is not None
+        assert result.task_id == "task-123"
+        assert result.task_type == "code_review"
+        assert result.status == "in_progress"
+        assert result.current_step == 2
+        assert result.progress_percent == 40.0
+        assert result.context == {"pr_id": 456}
+
+    @pytest.mark.asyncio
+    async def test_get_task_state_none_when_not_set(
+        self, memory: WorkingMemory
+    ) -> None:
+        """Test that get_task_state returns None when not set."""
+        result = await memory.get_task_state()
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_update_task_progress(self, memory: WorkingMemory) -> None:
+        """Test updating task progress."""
+        state = TaskState(
+            task_id="task-123",
+            task_type="test",
+            description="Test",
+            current_step=1,
+            progress_percent=10.0,
+            status="running",
+        )
+        await memory.set_task_state(state)
+
+        updated = await memory.update_task_progress(
+            current_step=3,
+            progress_percent=60.0,
+            status="processing",
+        )
+
+        assert updated is not None
+        assert updated.current_step == 3
+        assert updated.progress_percent == 60.0
+        assert updated.status == "processing"
+
+    @pytest.mark.asyncio
+    async def test_update_task_progress_clamps_percent(
+        self, memory: WorkingMemory
+    ) -> None:
+        """Test that progress percent is clamped to 0-100."""
+        state = TaskState(
+            task_id="task-123",
+            task_type="test",
+            description="Test",
+        )
+        await memory.set_task_state(state)
+
+        updated = await memory.update_task_progress(progress_percent=150.0)
+        assert updated is not None
+        assert updated.progress_percent == 100.0
+
+        updated = await memory.update_task_progress(progress_percent=-10.0)
+        assert updated is not None
+        assert updated.progress_percent == 0.0
+
+
+class TestWorkingMemoryScratchpad:
+    """Tests for scratchpad operations."""
+
+    @pytest.mark.asyncio
+    async def test_append_and_get_scratchpad(self, memory: WorkingMemory) -> None:
+        """Test appending to and getting scratchpad."""
+        await memory.append_scratchpad("First note")
+        await memory.append_scratchpad("Second note")
+
+        entries = await memory.get_scratchpad()
+        assert entries == ["First note", "Second note"]
+
+    @pytest.mark.asyncio
+    async def test_get_scratchpad_empty(self, memory: WorkingMemory) -> None:
+        """Test getting empty scratchpad."""
+        entries = await memory.get_scratchpad()
+        assert entries == []
+
+    @pytest.mark.asyncio
+    async def test_get_scratchpad_with_timestamps(self, memory: WorkingMemory) -> None:
+        """Test getting scratchpad with timestamps."""
+        await memory.append_scratchpad("Test note")
+
+        entries = await memory.get_scratchpad_with_timestamps()
+        assert len(entries) == 1
+        assert entries[0]["content"] == "Test note"
+        assert "timestamp" in entries[0]
+
+    @pytest.mark.asyncio
+    async def test_clear_scratchpad(self, memory: WorkingMemory) -> None:
+        """Test clearing scratchpad."""
+        await memory.append_scratchpad("Note 1")
+        await memory.append_scratchpad("Note 2")
+
+        count = await memory.clear_scratchpad()
+        assert count == 2
+
+        entries = await memory.get_scratchpad()
+        assert entries == []
+
+
+class TestWorkingMemoryCheckpoints:
+    """Tests for checkpoint operations."""
+
+    @pytest.mark.asyncio
+    async def test_create_checkpoint(self, memory: WorkingMemory) -> None:
+        """Test creating a checkpoint."""
+        await memory.set("key1", "value1")
+        await memory.set("key2", "value2")
+
+        checkpoint_id = await memory.create_checkpoint("Test checkpoint")
+
+        assert checkpoint_id is not None
+        assert len(checkpoint_id) == 8  # UUID prefix
+
+    @pytest.mark.asyncio
+    async def test_restore_checkpoint(self, memory: WorkingMemory) -> None:
+        """Test restoring from a checkpoint."""
+        await memory.set("key1", "original")
+        checkpoint_id = await memory.create_checkpoint()
+
+        # Modify state
+        await memory.set("key1", "modified")
+        await memory.set("key2", "new")
+
+        # Restore
+        await memory.restore_checkpoint(checkpoint_id)
+
+        # Check restoration
+        assert await memory.get("key1") == "original"
+        # key2 didn't exist in checkpoint, so it should be gone
+        # But due to checkpoint being restored with clear, it's gone
+
+    @pytest.mark.asyncio
+    async def test_restore_nonexistent_checkpoint(self, memory: WorkingMemory) -> None:
+        """Test restoring from nonexistent checkpoint raises error."""
+        with pytest.raises(MemoryNotFoundError):
+            await memory.restore_checkpoint("nonexistent")
+
+    @pytest.mark.asyncio
+    async def test_list_checkpoints(self, memory: WorkingMemory) -> None:
+        """Test listing checkpoints."""
+        cp1 = await memory.create_checkpoint("First")
+        cp2 = await memory.create_checkpoint("Second")
+
+        checkpoints = await memory.list_checkpoints()
+
+        assert len(checkpoints) == 2
+        ids = [cp["id"] for cp in checkpoints]
+        assert cp1 in ids
+        assert cp2 in ids
+
+    @pytest.mark.asyncio
+    async def test_delete_checkpoint(self, memory: WorkingMemory) -> None:
+        """Test deleting a checkpoint."""
+        checkpoint_id = await memory.create_checkpoint()
+
+        result = await memory.delete_checkpoint(checkpoint_id)
+        assert result is True
+
+        checkpoints = await memory.list_checkpoints()
+        assert len(checkpoints) == 0
+
+
+class TestWorkingMemoryScope:
+    """Tests for scope handling."""
+
+    @pytest.mark.asyncio
+    async def test_scope_property(
+        self, memory: WorkingMemory, scope: ScopeContext
+    ) -> None:
+        """Test scope property."""
+        assert memory.scope == scope
+
+    @pytest.mark.asyncio
+    async def test_for_session_factory(self) -> None:
+        """Test for_session factory method."""
+        # This would normally try Redis and fall back to in-memory
+        # In tests, Redis won't be available, so it uses fallback
+        wm = await WorkingMemory.for_session(
+            session_id="session-abc",
+            project_id="project-123",
+            agent_instance_id="agent-456",
+        )
+
+        assert wm.scope.scope_type == ScopeLevel.SESSION
+        assert wm.scope.scope_id == "session-abc"
+        assert wm.scope.parent is not None
+        assert wm.scope.parent.scope_type == ScopeLevel.AGENT_INSTANCE
+
+
+class TestWorkingMemoryHealth:
+    """Tests for health and lifecycle."""
+
+    @pytest.mark.asyncio
+    async def test_is_healthy(self, memory: WorkingMemory) -> None:
+        """Test health check."""
+        assert await memory.is_healthy() is True
+
+    @pytest.mark.asyncio
+    async def test_get_stats(self, memory: WorkingMemory) -> None:
+        """Test getting stats."""
+        await memory.set("key1", "value1")
+        await memory.append_scratchpad("Note")
+
+        state = TaskState(task_id="t1", task_type="test", description="Test")
+        await memory.set_task_state(state)
+
+        stats = await memory.get_stats()
+
+        assert stats["scope_type"] == "session"
+        assert stats["scope_id"] == "test-session-123"
+        assert stats["user_keys"] == 1
+        assert stats["scratchpad_entries"] == 1
+        assert stats["has_task_state"] is True
+
+    @pytest.mark.asyncio
+    async def test_is_using_fallback(self, memory: WorkingMemory) -> None:
+        """Test fallback detection."""
+        # In-memory storage is always fallback
+        assert memory.is_using_fallback is False  # Not set in fixture
+
+    @pytest.mark.asyncio
+    async def test_close(self, memory: WorkingMemory) -> None:
+        """Test close doesn't error."""
+        await memory.close()  # Should not raise

backend/tests/unit/services/memory/working/test_storage.py

@@ -0,0 +1,303 @@
+# tests/unit/services/memory/working/test_storage.py
+"""Unit tests for working memory storage backends."""
+
+import asyncio
+
+import pytest
+
+from app.services.memory.exceptions import MemoryStorageError
+from app.services.memory.working.storage import InMemoryStorage
+
+
+class TestInMemoryStorageBasicOperations:
+    """Tests for basic InMemoryStorage operations."""
+
+    @pytest.fixture
+    def storage(self) -> InMemoryStorage:
+        """Create a fresh storage instance."""
+        return InMemoryStorage(max_keys=100)
+
+    @pytest.mark.asyncio
+    async def test_set_and_get(self, storage: InMemoryStorage) -> None:
+        """Test basic set and get."""
+        await storage.set("key1", "value1")
+        result = await storage.get("key1")
+        assert result == "value1"
+
+    @pytest.mark.asyncio
+    async def test_get_nonexistent_key(self, storage: InMemoryStorage) -> None:
+        """Test getting a key that doesn't exist."""
+        result = await storage.get("nonexistent")
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_set_overwrites_existing(self, storage: InMemoryStorage) -> None:
+        """Test that set overwrites existing values."""
+        await storage.set("key1", "original")
+        await storage.set("key1", "updated")
+        result = await storage.get("key1")
+        assert result == "updated"
+
+    @pytest.mark.asyncio
+    async def test_delete_existing_key(self, storage: InMemoryStorage) -> None:
+        """Test deleting an existing key."""
+        await storage.set("key1", "value1")
+        result = await storage.delete("key1")
+        assert result is True
+        assert await storage.get("key1") is None
+
+    @pytest.mark.asyncio
+    async def test_delete_nonexistent_key(self, storage: InMemoryStorage) -> None:
+        """Test deleting a key that doesn't exist."""
+        result = await storage.delete("nonexistent")
+        assert result is False
+
+    @pytest.mark.asyncio
+    async def test_exists(self, storage: InMemoryStorage) -> None:
+        """Test exists check."""
+        await storage.set("key1", "value1")
+        assert await storage.exists("key1") is True
+        assert await storage.exists("nonexistent") is False
+
+
+class TestInMemoryStorageTTL:
+    """Tests for TTL functionality."""
+
+    @pytest.fixture
+    def storage(self) -> InMemoryStorage:
+        """Create a fresh storage instance."""
+        return InMemoryStorage(max_keys=100)
+
+    @pytest.mark.asyncio
+    async def test_set_with_ttl(self, storage: InMemoryStorage) -> None:
+        """Test that TTL is stored correctly."""
+        await storage.set("key1", "value1", ttl_seconds=10)
+        # Key should exist immediately
+        assert await storage.exists("key1") is True
+
+    @pytest.mark.asyncio
+    async def test_ttl_expiration(self, storage: InMemoryStorage) -> None:
+        """Test that expired keys return None."""
+        await storage.set("key1", "value1", ttl_seconds=1)
+
+        # Key exists initially
+        assert await storage.get("key1") == "value1"
+
+        # Wait for expiration
+        await asyncio.sleep(1.1)
+
+        # Key should be expired
+        assert await storage.get("key1") is None
+        assert await storage.exists("key1") is False
+
+    @pytest.mark.asyncio
+    async def test_remove_ttl_on_update(self, storage: InMemoryStorage) -> None:
+        """Test that updating without TTL removes expiration."""
+        await storage.set("key1", "value1", ttl_seconds=1)
+        await storage.set("key1", "value2")  # No TTL
+
+        await asyncio.sleep(1.1)
+
+        # Key should still exist (TTL removed)
+        assert await storage.get("key1") == "value2"
+
+
+class TestInMemoryStorageListAndClear:
+    """Tests for list and clear operations."""
+
+    @pytest.fixture
+    def storage(self) -> InMemoryStorage:
+        """Create a fresh storage instance."""
+        return InMemoryStorage(max_keys=100)
+
+    @pytest.mark.asyncio
+    async def test_list_keys_all(self, storage: InMemoryStorage) -> None:
+        """Test listing all keys."""
+        await storage.set("key1", "value1")
+        await storage.set("key2", "value2")
+        await storage.set("other", "value3")
+
+        keys = await storage.list_keys()
+        assert set(keys) == {"key1", "key2", "other"}
+
+    @pytest.mark.asyncio
+    async def test_list_keys_with_pattern(self, storage: InMemoryStorage) -> None:
+        """Test listing keys with pattern."""
+        await storage.set("key1", "value1")
+        await storage.set("key2", "value2")
+        await storage.set("other", "value3")
+
+        keys = await storage.list_keys("key*")
+        assert set(keys) == {"key1", "key2"}
+
+    @pytest.mark.asyncio
+    async def test_get_all(self, storage: InMemoryStorage) -> None:
+        """Test getting all key-value pairs."""
+        await storage.set("key1", "value1")
+        await storage.set("key2", "value2")
+
+        result = await storage.get_all()
+        assert result == {"key1": "value1", "key2": "value2"}
+
+    @pytest.mark.asyncio
+    async def test_clear(self, storage: InMemoryStorage) -> None:
+        """Test clearing all keys."""
+        await storage.set("key1", "value1")
+        await storage.set("key2", "value2")
+
+        count = await storage.clear()
+        assert count == 2
+        assert await storage.get_all() == {}
+
+
+class TestInMemoryStorageCapacity:
+    """Tests for capacity limits."""
+
+    @pytest.mark.asyncio
+    async def test_capacity_limit_exceeded(self) -> None:
+        """Test that exceeding capacity raises error."""
+        storage = InMemoryStorage(max_keys=2)
+
+        await storage.set("key1", "value1")
+        await storage.set("key2", "value2")
+
+        with pytest.raises(MemoryStorageError, match="capacity exceeded"):
+            await storage.set("key3", "value3")
+
+    @pytest.mark.asyncio
+    async def test_update_existing_key_within_capacity(self) -> None:
+        """Test that updating existing key doesn't count against capacity."""
+        storage = InMemoryStorage(max_keys=2)
+
+        await storage.set("key1", "value1")
+        await storage.set("key2", "value2")
+        await storage.set("key1", "updated")  # Should succeed
+
+        assert await storage.get("key1") == "updated"
+
+    @pytest.mark.asyncio
+    async def test_expired_keys_freed_for_capacity(self) -> None:
+        """Test that expired keys are cleaned up for capacity."""
+        storage = InMemoryStorage(max_keys=2)
+
+        await storage.set("key1", "value1", ttl_seconds=1)
+        await storage.set("key2", "value2")
+
+        await asyncio.sleep(1.1)
+
+        # Should succeed because key1 is expired and will be cleaned
+        await storage.set("key3", "value3")
+        assert await storage.get("key3") == "value3"
+
+
+class TestInMemoryStorageDataTypes:
+    """Tests for different data types."""
+
+    @pytest.fixture
+    def storage(self) -> InMemoryStorage:
+        """Create a fresh storage instance."""
+        return InMemoryStorage(max_keys=100)
+
+    @pytest.mark.asyncio
+    async def test_store_dict(self, storage: InMemoryStorage) -> None:
+        """Test storing dict values."""
+        data = {"nested": {"key": "value"}, "list": [1, 2, 3]}
+        await storage.set("dict_key", data)
+        result = await storage.get("dict_key")
+        assert result == data
+
+    @pytest.mark.asyncio
+    async def test_store_list(self, storage: InMemoryStorage) -> None:
+        """Test storing list values."""
+        data = [1, 2, {"nested": "dict"}]
+        await storage.set("list_key", data)
+        result = await storage.get("list_key")
+        assert result == data
+
+    @pytest.mark.asyncio
+    async def test_store_numbers(self, storage: InMemoryStorage) -> None:
+        """Test storing numeric values."""
+        await storage.set("int_key", 42)
+        await storage.set("float_key", 3.14)
+
+        assert await storage.get("int_key") == 42
+        assert await storage.get("float_key") == 3.14
+
+    @pytest.mark.asyncio
+    async def test_store_boolean(self, storage: InMemoryStorage) -> None:
+        """Test storing boolean values."""
+        await storage.set("true_key", True)
+        await storage.set("false_key", False)
+
+        assert await storage.get("true_key") is True
+        assert await storage.get("false_key") is False
+
+    @pytest.mark.asyncio
+    async def test_store_none(self, storage: InMemoryStorage) -> None:
+        """Test storing None value."""
+        await storage.set("none_key", None)
+        # Note: None is stored, but get returns None for both missing and None values
+        # Use exists to distinguish
+        assert await storage.exists("none_key") is True
+
+
+class TestInMemoryStorageHealth:
+    """Tests for health and lifecycle."""
+
+    @pytest.mark.asyncio
+    async def test_is_healthy(self) -> None:
+        """Test health check."""
+        storage = InMemoryStorage()
+        assert await storage.is_healthy() is True
+
+    @pytest.mark.asyncio
+    async def test_close(self) -> None:
+        """Test close is no-op but doesn't error."""
+        storage = InMemoryStorage()
+        await storage.close()  # Should not raise
+
+
+class TestInMemoryStorageConcurrency:
+    """Tests for concurrent access."""
+
+    @pytest.mark.asyncio
+    async def test_concurrent_writes(self) -> None:
+        """Test concurrent write operations don't corrupt data."""
+        storage = InMemoryStorage(max_keys=1000)
+
+        async def write_batch(prefix: str, count: int) -> None:
+            for i in range(count):
+                await storage.set(f"{prefix}_{i}", f"value_{i}")
+
+        # Run concurrent writes
+        await asyncio.gather(
+            write_batch("a", 100),
+            write_batch("b", 100),
+            write_batch("c", 100),
+        )
+
+        # Verify all writes succeeded
+        keys = await storage.list_keys()
+        assert len(keys) == 300
+
+    @pytest.mark.asyncio
+    async def test_concurrent_read_write(self) -> None:
+        """Test concurrent read and write operations."""
+        storage = InMemoryStorage()
+        await storage.set("key", 0)
+
+        async def increment() -> None:
+            for _ in range(100):
+                val = await storage.get("key") or 0
+                await storage.set("key", val + 1)
+
+        # Run concurrent increments
+        await asyncio.gather(
+            increment(),
+            increment(),
+        )
+
+        # Final value depends on interleaving
+        # Just verify we don't crash and value is positive
+        result = await storage.get("key")
+        assert result > 0

docs/architecture/memory-system-plan.md

@@ -0,0 +1,526 @@
+# Agent Memory System - Implementation Plan
+
+## Issue #62 - Part of Epic #60 (Phase 2: MCP Integration)
+
+**Branch:** `feature/62-agent-memory-system`
+**Parent Epic:** #60 [EPIC] Phase 2: MCP Integration
+**Dependencies:** #56 (LLM Gateway), #57 (Knowledge Base), #61 (Context Management Engine)
+
+---
+
+## Executive Summary
+
+The Agent Memory System provides multi-tier cognitive memory for AI agents, enabling them to:
+- Maintain state across sessions (Working Memory)
+- Learn from past experiences (Episodic Memory)
+- Store and retrieve facts (Semantic Memory)
+- Develop and reuse procedures (Procedural Memory)
+
+### Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           Agent Memory System                                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  ┌─────────────────┐                      ┌─────────────────┐               │
+│  │ Working Memory  │───────────────────▶  │ Episodic Memory │               │
+│  │ (Redis/In-Mem)  │    consolidate       │  (PostgreSQL)   │               │
+│  │                 │                      │                 │               │
+│  │ • Current task  │                      │ • Past sessions │               │
+│  │ • Variables     │                      │ • Experiences   │               │
+│  │ • Scratchpad    │                      │ • Outcomes      │               │
+│  └─────────────────┘                      └────────┬────────┘               │
+│                                                    │                         │
+│                                           extract  │                         │
+│                                                    ▼                         │
+│  ┌─────────────────┐                      ┌─────────────────┐               │
+│  │Procedural Memory│◀─────────────────────│ Semantic Memory │               │
+│  │  (PostgreSQL)   │      learn from      │  (PostgreSQL +  │               │
+│  │                 │                      │    pgvector)    │               │
+│  │ • Procedures    │                      │                 │               │
+│  │ • Skills        │                      │ • Facts         │               │
+│  │ • Patterns      │                      │ • Entities      │               │
+│  └─────────────────┘                      │ • Relationships │               │
+│                                           └─────────────────┘               │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Memory Scoping Hierarchy
+
+```
+Global Memory (shared by all)
+└── Project Memory (per project)
+    └── Agent Type Memory (per agent type)
+        └── Agent Instance Memory (per instance)
+            └── Session Memory (ephemeral)
+```
+
+---
+
+## Sub-Issue Breakdown
+
+### Phase 1: Foundation (Critical Path)
+
+#### Sub-Issue #62-1: Project Setup & Core Architecture
+**Priority:** P0 - Must complete first
+**Estimated Complexity:** Medium
+
+**Tasks:**
+- [ ] Create `backend/app/services/memory/` directory structure
+- [ ] Create `__init__.py` with public API exports
+- [ ] Create `config.py` with `MemorySettings` (Pydantic)
+- [ ] Define base interfaces in `types.py`:
+  - `MemoryItem` - Base class for all memory items
+  - `MemoryScope` - Enum for scoping levels
+  - `MemoryStore` - Abstract base for storage backends
+- [ ] Create `manager.py` with `MemoryManager` class (facade)
+- [ ] Create `exceptions.py` with memory-specific errors
+- [ ] Write ADR-010 documenting memory architecture decisions
+- [ ] Create dependency injection setup
+- [ ] Unit tests for configuration and types
+
+**Deliverables:**
+- Directory structure matching existing patterns (like `context/`, `safety/`)
+- Configuration with MEM_ env prefix
+- Type definitions for all memory concepts
+- Comprehensive unit tests
+
+---
+
+#### Sub-Issue #62-2: Database Schema & Storage Layer
+**Priority:** P0 - Required for all memory types
+**Estimated Complexity:** High
+
+**Database Tables:**
+
+1. **`working_memory`** - Ephemeral key-value storage
+   - `id` (UUID, PK)
+   - `scope_type` (ENUM: global/project/agent_type/agent_instance/session)
+   - `scope_id` (VARCHAR - the ID for the scope level)
+   - `key` (VARCHAR)
+   - `value` (JSONB)
+   - `expires_at` (TIMESTAMP WITH TZ)
+   - `created_at`, `updated_at`
+
+2. **`episodes`** - Experiential memories
+   - `id` (UUID, PK)
+   - `project_id` (UUID, FK)
+   - `agent_instance_id` (UUID, FK, nullable)
+   - `agent_type_id` (UUID, FK, nullable)
+   - `session_id` (VARCHAR)
+   - `task_type` (VARCHAR)
+   - `task_description` (TEXT)
+   - `actions` (JSONB)
+   - `context_summary` (TEXT)
+   - `outcome` (ENUM: success/failure/partial)
+   - `outcome_details` (TEXT)
+   - `duration_seconds` (FLOAT)
+   - `tokens_used` (BIGINT)
+   - `lessons_learned` (JSONB - list of strings)
+   - `importance_score` (FLOAT, 0-1)
+   - `embedding` (VECTOR(1536))
+   - `occurred_at` (TIMESTAMP WITH TZ)
+   - `created_at`, `updated_at`
+
+3. **`facts`** - Semantic knowledge
+   - `id` (UUID, PK)
+   - `project_id` (UUID, FK, nullable - null for global)
+   - `subject` (VARCHAR)
+   - `predicate` (VARCHAR)
+   - `object` (TEXT)
+   - `confidence` (FLOAT, 0-1)
+   - `source_episode_ids` (UUID[])
+   - `first_learned` (TIMESTAMP WITH TZ)
+   - `last_reinforced` (TIMESTAMP WITH TZ)
+   - `reinforcement_count` (INT)
+   - `embedding` (VECTOR(1536))
+   - `created_at`, `updated_at`
+
+4. **`procedures`** - Learned skills
+   - `id` (UUID, PK)
+   - `project_id` (UUID, FK, nullable)
+   - `agent_type_id` (UUID, FK, nullable)
+   - `name` (VARCHAR)
+   - `trigger_pattern` (TEXT)
+   - `steps` (JSONB)
+   - `success_count` (INT)
+   - `failure_count` (INT)
+   - `last_used` (TIMESTAMP WITH TZ)
+   - `embedding` (VECTOR(1536))
+   - `created_at`, `updated_at`
+
+5. **`memory_consolidation_log`** - Consolidation tracking
+   - `id` (UUID, PK)
+   - `consolidation_type` (ENUM)
+   - `source_count` (INT)
+   - `result_count` (INT)
+   - `started_at`, `completed_at`
+   - `status` (ENUM: pending/running/completed/failed)
+   - `error` (TEXT, nullable)
+
+**Tasks:**
+- [ ] Create SQLAlchemy models in `backend/app/models/memory/`
+- [ ] Create Alembic migration with all tables
+- [ ] Add pgvector indexes (HNSW for episodes, facts, procedures)
+- [ ] Create repository classes in `backend/app/crud/memory/`
+- [ ] Add composite indexes for common query patterns
+- [ ] Unit tests for all repositories
+
+---
+
+#### Sub-Issue #62-3: Working Memory Implementation
+**Priority:** P0 - Core functionality
+**Estimated Complexity:** Medium
+
+**Components:**
+- `backend/app/services/memory/working/memory.py` - WorkingMemory class
+- `backend/app/services/memory/working/storage.py` - Redis + in-memory backend
+
+**Features:**
+- [ ] Session-scoped containers with automatic cleanup
+- [ ] Variable storage (get/set/delete)
+- [ ] Task state tracking (current step, status, progress)
+- [ ] Scratchpad for reasoning steps
+- [ ] Configurable capacity limits
+- [ ] TTL-based expiration
+- [ ] Checkpoint/snapshot support for recovery
+- [ ] Redis primary storage with in-memory fallback
+
+**API:**
+```python
+class WorkingMemory:
+    async def set(self, key: str, value: Any, ttl_seconds: int | None = None) -> None
+    async def get(self, key: str, default: Any = None) -> Any
+    async def delete(self, key: str) -> bool
+    async def exists(self, key: str) -> bool
+    async def list_keys(self, pattern: str = "*") -> list[str]
+    async def get_all(self) -> dict[str, Any]
+    async def clear(self) -> int
+    async def set_task_state(self, state: TaskState) -> None
+    async def get_task_state(self) -> TaskState | None
+    async def append_scratchpad(self, content: str) -> None
+    async def get_scratchpad(self) -> list[str]
+    async def create_checkpoint(self) -> str  # Returns checkpoint ID
+    async def restore_checkpoint(self, checkpoint_id: str) -> None
+```
+
+---
+
+### Phase 2: Memory Types
+
+#### Sub-Issue #62-4: Episodic Memory Implementation
+**Priority:** P1
+**Estimated Complexity:** High
+
+**Components:**
+- `backend/app/services/memory/episodic/memory.py` - EpisodicMemory class
+- `backend/app/services/memory/episodic/recorder.py` - Episode recording
+- `backend/app/services/memory/episodic/retrieval.py` - Retrieval strategies
+
+**Features:**
+- [ ] Episode recording during agent execution
+- [ ] Store task completions with context
+- [ ] Store failures with error context
+- [ ] Retrieval by semantic similarity (vector search)
+- [ ] Retrieval by recency
+- [ ] Retrieval by outcome (success/failure)
+- [ ] Importance scoring based on outcome significance
+- [ ] Episode summarization for long-term storage
+
+**API:**
+```python
+class EpisodicMemory:
+    async def record_episode(self, episode: EpisodeCreate) -> Episode
+    async def search_similar(self, query: str, limit: int = 10) -> list[Episode]
+    async def get_recent(self, limit: int = 10, since: datetime | None = None) -> list[Episode]
+    async def get_by_outcome(self, outcome: Outcome, limit: int = 10) -> list[Episode]
+    async def get_by_task_type(self, task_type: str, limit: int = 10) -> list[Episode]
+    async def update_importance(self, episode_id: UUID, score: float) -> None
+    async def summarize_episodes(self, episode_ids: list[UUID]) -> str
+```
+
+---
+
+#### Sub-Issue #62-5: Semantic Memory Implementation
+**Priority:** P1
+**Estimated Complexity:** High
+
+**Components:**
+- `backend/app/services/memory/semantic/memory.py` - SemanticMemory class
+- `backend/app/services/memory/semantic/extraction.py` - Fact extraction from episodes
+- `backend/app/services/memory/semantic/verification.py` - Fact verification
+
+**Features:**
+- [ ] Fact storage with triple format (subject, predicate, object)
+- [ ] Confidence scoring and decay
+- [ ] Fact extraction from episodic memory
+- [ ] Conflict resolution for contradictory facts
+- [ ] Retrieval by query (semantic search)
+- [ ] Retrieval by entity (subject or object)
+- [ ] Source tracking (which episodes contributed)
+- [ ] Reinforcement on repeated learning
+
+**API:**
+```python
+class SemanticMemory:
+    async def store_fact(self, fact: FactCreate) -> Fact
+    async def search_facts(self, query: str, limit: int = 10) -> list[Fact]
+    async def get_by_entity(self, entity: str, limit: int = 20) -> list[Fact]
+    async def reinforce_fact(self, fact_id: UUID) -> Fact
+    async def deprecate_fact(self, fact_id: UUID, reason: str) -> None
+    async def extract_facts_from_episode(self, episode: Episode) -> list[Fact]
+    async def resolve_conflict(self, fact_ids: list[UUID]) -> Fact
+```
+
+---
+
+#### Sub-Issue #62-6: Procedural Memory Implementation
+**Priority:** P2
+**Estimated Complexity:** Medium
+
+**Components:**
+- `backend/app/services/memory/procedural/memory.py` - ProceduralMemory class
+- `backend/app/services/memory/procedural/matching.py` - Procedure matching
+
+**Features:**
+- [ ] Procedure recording from successful task patterns
+- [ ] Trigger pattern matching
+- [ ] Step-by-step procedure storage
+- [ ] Success/failure rate tracking
+- [ ] Procedure suggestion based on context
+- [ ] Procedure versioning
+
+**API:**
+```python
+class ProceduralMemory:
+    async def record_procedure(self, procedure: ProcedureCreate) -> Procedure
+    async def find_matching(self, context: str, limit: int = 5) -> list[Procedure]
+    async def record_outcome(self, procedure_id: UUID, success: bool) -> None
+    async def get_best_procedure(self, task_type: str) -> Procedure | None
+    async def update_steps(self, procedure_id: UUID, steps: list[Step]) -> Procedure
+```
+
+---
+
+### Phase 3: Advanced Features
+
+#### Sub-Issue #62-7: Memory Scoping
+**Priority:** P1
+**Estimated Complexity:** Medium
+
+**Components:**
+- `backend/app/services/memory/scoping/scope.py` - Scope management
+- `backend/app/services/memory/scoping/resolver.py` - Scope resolution
+
+**Features:**
+- [ ] Global scope (shared across all)
+- [ ] Project scope (per project)
+- [ ] Agent type scope (per agent type)
+- [ ] Agent instance scope (per instance)
+- [ ] Session scope (ephemeral)
+- [ ] Scope inheritance (child sees parent memories)
+- [ ] Access control policies
+
+---
+
+#### Sub-Issue #62-8: Memory Indexing & Retrieval
+**Priority:** P1
+**Estimated Complexity:** High
+
+**Components:**
+- `backend/app/services/memory/indexing/index.py` - Memory indexer
+- `backend/app/services/memory/indexing/retrieval.py` - Retrieval engine
+
+**Features:**
+- [ ] Vector embeddings for all memory types
+- [ ] Temporal index (by time)
+- [ ] Entity index (by entities mentioned)
+- [ ] Outcome index (by success/failure)
+- [ ] Hybrid retrieval (vector + filters)
+- [ ] Relevance scoring
+- [ ] Retrieval caching
+
+---
+
+#### Sub-Issue #62-9: Memory Consolidation
+**Priority:** P2
+**Estimated Complexity:** High
+
+**Components:**
+- `backend/app/services/memory/consolidation/service.py` - Consolidation service
+- `backend/app/tasks/memory_consolidation.py` - Celery tasks
+
+**Features:**
+- [ ] Working → Episodic transfer (session end)
+- [ ] Episodic → Semantic extraction (learn facts)
+- [ ] Episodic → Procedural extraction (learn procedures)
+- [ ] Nightly consolidation Celery tasks
+- [ ] Memory pruning (remove low-value)
+- [ ] Importance-based retention
+
+---
+
+### Phase 4: Integration
+
+#### Sub-Issue #62-10: MCP Tools Definition
+**Priority:** P0 - Required for agent usage
+**Estimated Complexity:** Medium
+
+**MCP Tools:**
+
+1. **`remember`** - Store in memory
+   ```json
+   {
+     "memory_type": "working|episodic|semantic|procedural",
+     "content": "...",
+     "importance": 0.8,
+     "ttl_seconds": 3600
+   }
+   ```
+
+2. **`recall`** - Retrieve from memory
+   ```json
+   {
+     "query": "...",
+     "memory_types": ["episodic", "semantic"],
+     "limit": 10,
+     "filters": {"outcome": "success"}
+   }
+   ```
+
+3. **`forget`** - Remove from memory
+   ```json
+   {
+     "memory_type": "working",
+     "key": "temp_calculation"
+   }
+   ```
+
+4. **`reflect`** - Analyze patterns
+   ```json
+   {
+     "analysis_type": "recent_patterns|success_factors|failure_patterns"
+   }
+   ```
+
+5. **`get_memory_stats`** - Usage statistics
+6. **`search_procedures`** - Find relevant procedures
+7. **`record_outcome`** - Record task success/failure
+
+---
+
+#### Sub-Issue #62-11: Component Integration
+**Priority:** P1
+**Estimated Complexity:** Medium
+
+**Integrations:**
+- [ ] Context Engine (#61) - Include relevant memories in context assembly
+- [ ] Knowledge Base (#57) - Coordinate with KB to avoid duplication
+- [ ] LLM Gateway (#56) - Use for embedding generation
+- [ ] Agent lifecycle hooks (spawn, pause, resume, terminate)
+
+---
+
+#### Sub-Issue #62-12: Caching Layer
+**Priority:** P2
+**Estimated Complexity:** Medium
+
+**Features:**
+- [ ] Hot memory caching (frequently accessed)
+- [ ] Retrieval result caching
+- [ ] Embedding caching
+- [ ] Cache invalidation strategies
+
+---
+
+### Phase 5: Intelligence & Quality
+
+#### Sub-Issue #62-13: Memory Reflection
+**Priority:** P3
+**Estimated Complexity:** High
+
+**Features:**
+- [ ] Pattern detection in episodic memory
+- [ ] Success/failure factor analysis
+- [ ] Anomaly detection
+- [ ] Insights generation
+
+---
+
+#### Sub-Issue #62-14: Metrics & Observability
+**Priority:** P2
+**Estimated Complexity:** Low
+
+**Metrics:**
+- `memory_size_bytes` by type and scope
+- `memory_operations_total` counter
+- `memory_retrieval_latency_seconds` histogram
+- `memory_consolidation_duration_seconds` histogram
+- `procedure_success_rate` gauge
+
+---
+
+#### Sub-Issue #62-15: Documentation & Final Testing
+**Priority:** P0
+**Estimated Complexity:** Medium
+
+**Deliverables:**
+- [ ] README with architecture overview
+- [ ] API documentation with examples
+- [ ] Integration guide
+- [ ] E2E tests for full memory lifecycle
+- [ ] Achieve >90% code coverage
+- [ ] Performance benchmarks
+
+---
+
+## Implementation Order
+
+```
+Phase 1 (Foundation) - Sequential
+  #62-1 → #62-2 → #62-3
+
+Phase 2 (Memory Types) - Can parallelize after Phase 1
+  #62-4, #62-5, #62-6 (parallel after #62-3)
+
+Phase 3 (Advanced) - Sequential within phase
+  #62-7 → #62-8 → #62-9
+
+Phase 4 (Integration) - After Phase 2
+  #62-10 → #62-11 → #62-12
+
+Phase 5 (Quality) - Final
+  #62-13, #62-14, #62-15
+```
+
+---
+
+## Performance Targets
+
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Working memory get/set | <5ms | P95 |
+| Episodic memory retrieval | <100ms | P95, as per epic |
+| Semantic memory search | <100ms | P95 |
+| Procedural memory matching | <50ms | P95 |
+| Consolidation batch | <30s | Per 1000 episodes |
+
+---
+
+## Risk Mitigation
+
+1. **Embedding costs** - Use caching aggressively, batch embeddings
+2. **Storage growth** - Implement TTL, pruning, and archival policies
+3. **Query performance** - HNSW indexes, pagination, query optimization
+4. **Scope complexity** - Start simple (instance scope only), add hierarchy later
+
+---
+
+## Review Checkpoints
+
+After each sub-issue:
+1. Run `make validate-all`
+2. Multi-agent code review
+3. Verify E2E stack still works
+4. Commit with granular message