Phase 5.5-5.9: Plugin-Marketplace, Agent Memory, GraphRAG, Subagents, External Agent API

5.5 Plugin-Marketplace:
- New plugin: marketplace/ (models, routes, services, schemas, config)
- MarketplaceListing model (global, no tenant_id)
- Ed25519 signature verification via PluginSignature
- Endpoints: list, detail, install, verify, categories
- Config: MARKETPLACE_SERVER_URL setting

5.6 Agent Memory (persistent):
- New plugin: agent_memory/ (models, routes, services, schemas)
- AgentMemory model with embedding vector(768) + HNSW index
- store_memory() with auto-embedding
- retrieve_relevant_memories() with pgvector cosine similarity
- Semantic search endpoint

5.7 GraphRAG:
- New plugin: graph_rag/ (models, routes, services, provider, schemas)
- EntityRelationship model (source/target type+id, relationship_type, metadata)
- BFS graph traversal (bidirectional, configurable depth)
- GraphRAGSearchProvider registered in unified_search

5.8 Subagents / Multi-Agent:
- AgentCoordinator class (create_subtask, wait_for_subtask, aggregate, cancel)
- AgentSubtask model + migration 0002_agent_subtasks.sql
- 6 new API endpoints for subtask management
- Tools registered in AI tool registry

5.9 External Agent API:
- external_api.py: POST /run, GET /status, POST /stream (SSE)
- Bearer API token authentication
- Rate limiting: 10 req/min per token
- ExternalAgentRequest/Response schemas

3 new plugins registered in main.py and __init__.py
All files py_compile clean

app/plugins/builtins/agent_memory/__init__.py

@@ -0,0 +1,5 @@
+"""Agent Memory plugin package."""
+
+from app.plugins.builtins.agent_memory.plugin import AgentMemoryPlugin
+
+__all__ = ["AgentMemoryPlugin"]

app/plugins/builtins/agent_memory/migrations/0001_initial.sql

@@ -0,0 +1,19 @@
+-- Agent Memory plugin initial migration: creates agent_memories table with pgvector
+CREATE TABLE IF NOT EXISTS agent_memories (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id UUID NOT NULL,
+    agent_id UUID NOT NULL,
+    memory_type VARCHAR(50) NOT NULL DEFAULT 'fact',
+    content TEXT NOT NULL,
+    embedding vector(768),
+    owner_id UUID REFERENCES users(id) ON DELETE SET NULL,
+    deleted_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS ix_agent_memories_tenant_agent ON agent_memories(tenant_id, agent_id);
+CREATE INDEX IF NOT EXISTS ix_agent_memories_tenant_type ON agent_memories(tenant_id, memory_type);
+CREATE INDEX IF NOT EXISTS ix_agent_memories_agent_id ON agent_memories(agent_id);
+
+-- HNSW index for fast vector similarity search on agent_memories.embedding
+CREATE INDEX IF NOT EXISTS ix_agent_memories_embedding_hnsw ON agent_memories USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 200);

app/plugins/builtins/agent_memory/models.py

@@ -0,0 +1,39 @@
+"""AgentMemory model for persistent agent memory with pgvector embeddings."""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import Index, String, Text
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
+
+
+class AgentMemory(Base, TenantMixin, OwnedMixin):
+    """Persistent agent memory with semantic search via pgvector.
+
+    Stores agent memories (facts, context, learned patterns) with
+    vector embeddings for semantic retrieval.
+    """
+
+    __tablename__ = "agent_memories"
+    __table_args__ = (
+        Index("ix_agent_memories_tenant_agent", "tenant_id", "agent_id"),
+        Index("ix_agent_memories_tenant_type", "tenant_id", "memory_type"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    agent_id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), nullable=False, index=True
+    )
+    memory_type: Mapped[str] = mapped_column(
+        String(50), nullable=False, default="fact"
+    )
+    content: Mapped[str] = mapped_column(Text, nullable=False)
+    # embedding column is managed via raw SQL (pgvector extension)
+    # embedding vector(768) — see migration 0001_initial.sql

app/plugins/builtins/agent_memory/plugin.py

@@ -0,0 +1,41 @@
+"""Agent Memory plugin — persistent agent memory with pgvector semantic search."""
+
+from __future__ import annotations
+
+from app.plugins.base import BasePlugin
+from app.plugins.manifest import PluginManifest, PluginRouteDef
+
+
+class AgentMemoryPlugin(BasePlugin):
+    """Agent Memory plugin for persistent agent memory with semantic search."""
+
+    manifest = PluginManifest(
+        name="agent_memory",
+        version="1.0.0",
+        display_name="Agent Memory",
+        description="Persistent agent memory with pgvector semantic search. Stores facts, context, patterns, and instructions for AI agents.",
+        dependencies=["unified_search"],
+        routes=[
+            PluginRouteDef(
+                path="/api/v1/agent-memory",
+                module="app.plugins.builtins.agent_memory.routes",
+                router_attr="router",
+            ),
+        ],
+        events=[],
+        migrations=["0001_initial.sql"],
+        permissions=[
+            "agent_memory:read",
+            "agent_memory:write",
+        ],
+        is_core=True,
+        author="LeoCRM Team",
+        min_app_version="1.0.0",
+        contract_version="1.0.0",
+    )
+
+    async def on_deactivate(self, db, service_container, event_bus) -> None:
+        """Deactivate plugin: unregister contract and event listeners."""
+        from app.plugins.builtins.contracts import get_contract_registry
+        get_contract_registry().unregister(self.manifest.name)
+        await super().on_deactivate(db, service_container, event_bus)

app/plugins/builtins/agent_memory/routes.py

@@ -0,0 +1,202 @@
+"""Agent Memory plugin routes — CRUD for persistent agent memories."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.db import get_db
+from app.deps import get_current_user, require_permission
+from app.plugins.builtins.agent_memory.models import AgentMemory
+from app.plugins.builtins.agent_memory.schemas import (
+    AgentMemoryCreate,
+    AgentMemoryRead,
+    AgentMemoryUpdate,
+)
+from app.plugins.builtins.agent_memory.services import (
+    delete_memory,
+    retrieve_relevant_memories,
+    store_memory,
+)
+
+router = APIRouter(prefix="/api/v1/agent-memory", tags=["agent-memory"])
+
+
+@router.post("", status_code=status.HTTP_201_CREATED, dependencies=[Depends(require_permission("agent_memory:write"))])
+async def create_memory(
+    body: AgentMemoryCreate,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Create a new agent memory with embedding."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    user_id = uuid.UUID(current_user["user_id"])
+    agent_id = _parse_uuid(body.agent_id, "agent_id")
+
+    result = await store_memory(
+        db=db,
+        tenant_id=tenant_id,
+        agent_id=agent_id,
+        content=body.content,
+        memory_type=body.memory_type,
+        owner_id=user_id,
+    )
+    return result
+
+
+@router.get("", dependencies=[Depends(require_permission("agent_memory:read"))])
+async def list_memories(
+    agent_id: str = Query(..., description="Filter by agent UUID"),
+    memory_type: str | None = Query(None, description="Filter by memory type"),
+    page: int = Query(1, ge=1),
+    page_size: int = Query(50, ge=1, le=200),
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """List memories for an agent, with optional type filter."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    aid = _parse_uuid(agent_id, "agent_id")
+
+    base = select(AgentMemory).where(
+        AgentMemory.tenant_id == tenant_id,
+        AgentMemory.agent_id == aid,
+        AgentMemory.deleted_at.is_(None),
+    )
+    if memory_type:
+        base = base.where(AgentMemory.memory_type == memory_type)
+
+    # Count total
+    count_q = select(func.count()).select_from(base.subquery())
+    total_result = await db.execute(count_q)
+    total = total_result.scalar_one()
+
+    # Paginated query
+    offset = (page - 1) * page_size
+    stmt = base.order_by(AgentMemory.created_at.desc()).offset(offset).limit(page_size)
+    result = await db.execute(stmt)
+    memories = result.scalars().all()
+
+    return {
+        "items": [
+            {
+                "id": str(m.id),
+                "agent_id": str(m.agent_id),
+                "memory_type": m.memory_type,
+                "content": m.content,
+                "owner_id": str(m.owner_id) if m.owner_id else None,
+                "created_at": m.created_at.isoformat() if m.created_at else None,
+                "updated_at": m.updated_at.isoformat() if m.updated_at else None,
+                "score": 0.0,
+            }
+            for m in memories
+        ],
+        "total": total,
+    }
+
+
+@router.get("/search", dependencies=[Depends(require_permission("agent_memory:read"))])
+async def search_memories(
+    agent_id: str = Query(..., description="Agent UUID"),
+    query: str = Query(..., min_length=1, description="Natural language query"),
+    memory_type: str | None = Query(None, description="Optional type filter"),
+    limit: int = Query(10, ge=1, le=100),
+    min_score: float = Query(0.5, ge=0.0, le=1.0),
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Semantic search over agent memories using pgvector."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    aid = _parse_uuid(agent_id, "agent_id")
+
+    results = await retrieve_relevant_memories(
+        db=db,
+        tenant_id=tenant_id,
+        agent_id=aid,
+        query=query,
+        limit=limit,
+        memory_type=memory_type,
+        min_score=min_score,
+    )
+    return {"items": results, "total": len(results)}
+
+
+@router.patch("/{memory_id}", dependencies=[Depends(require_permission("agent_memory:write"))])
+async def update_memory(
+    memory_id: str,
+    body: AgentMemoryUpdate,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Update a memory's content or type."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    mid = _parse_uuid(memory_id, "memory_id")
+
+    result = await db.execute(
+        select(AgentMemory).where(
+            AgentMemory.id == mid,
+            AgentMemory.tenant_id == tenant_id,
+        )
+    )
+    memory = result.scalar_one_or_none()
+    if memory is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"detail": "Memory not found", "code": "not_found"},
+        )
+
+    data = body.model_dump(exclude_unset=True)
+    if "content" in data:
+        memory.content = data["content"]
+        # Regenerate embedding for updated content
+        from app.plugins.builtins.unified_search.embedding import generate_embedding
+        embedding = await generate_embedding(data["content"], db=db, tenant_id=tenant_id)
+        if embedding:
+            from sqlalchemy import text as sql_text
+            sql = sql_text(
+                "UPDATE agent_memories SET embedding = cast(:emb AS vector) WHERE id = :mid"
+            )
+            await db.execute(sql, {"emb": str(embedding), "mid": memory.id})
+    if "memory_type" in data:
+        memory.memory_type = data["memory_type"]
+
+    await db.flush()
+    return {
+        "id": str(memory.id),
+        "agent_id": str(memory.agent_id),
+        "memory_type": memory.memory_type,
+        "content": memory.content,
+        "owner_id": str(memory.owner_id) if memory.owner_id else None,
+        "updated_at": memory.updated_at.isoformat() if memory.updated_at else None,
+    }
+
+
+@router.delete("/{memory_id}", status_code=status.HTTP_204_NO_CONTENT, dependencies=[Depends(require_permission("agent_memory:write"))])
+async def delete_memory_route(
+    memory_id: str,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Delete a memory by ID."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    mid = _parse_uuid(memory_id, "memory_id")
+
+    success = await delete_memory(db, tenant_id, mid)
+    if not success:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"detail": "Memory not found", "code": "not_found"},
+        )
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+def _parse_uuid(val: str, field: str) -> uuid.UUID:
+    try:
+        return uuid.UUID(val)
+    except (ValueError, TypeError):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"detail": f"Invalid {field}", "code": "invalid_id"},
+        ) from None

app/plugins/builtins/agent_memory/schemas.py

@@ -0,0 +1,34 @@
+"""Pydantic schemas for the Agent Memory plugin."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class AgentMemoryCreate(BaseModel):
+    agent_id: str = Field(..., description="UUID of the agent")
+    memory_type: str = Field("fact", max_length=50, description="Type of memory (fact, context, pattern, instruction)")
+    content: str = Field(..., min_length=1, description="Memory content text")
+
+
+class AgentMemoryUpdate(BaseModel):
+    content: str | None = Field(None, min_length=1)
+    memory_type: str | None = Field(None, max_length=50)
+
+
+class AgentMemoryRead(BaseModel):
+    id: str
+    agent_id: str
+    memory_type: str
+    content: str
+    owner_id: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    score: float = 0.0
+
+
+class AgentMemoryListResponse(BaseModel):
+    items: list[AgentMemoryRead]
+    total: int

app/plugins/builtins/agent_memory/services.py

@@ -0,0 +1,176 @@
+"""Agent Memory services — store and retrieve memories with semantic search."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from sqlalchemy import select, text as sql_text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.plugins.builtins.agent_memory.models import AgentMemory
+from app.plugins.builtins.unified_search.embedding import generate_embedding
+
+
+async def store_memory(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    agent_id: uuid.UUID,
+    content: str,
+    memory_type: str = "fact",
+    owner_id: uuid.UUID | None = None,
+) -> dict[str, Any]:
+    """Store a new memory with embedding generation.
+
+    Args:
+        db: Database session.
+        tenant_id: Tenant UUID.
+        agent_id: Agent UUID.
+        content: Memory content text.
+        memory_type: Type of memory (fact, context, pattern, instruction).
+        owner_id: Optional owner user UUID.
+
+    Returns:
+        Dict with the created memory data.
+    """
+    # Generate embedding for semantic search
+    embedding = await generate_embedding(content, db=db, tenant_id=tenant_id)
+
+    memory = AgentMemory(
+        tenant_id=tenant_id,
+        agent_id=agent_id,
+        memory_type=memory_type,
+        content=content,
+        owner_id=owner_id,
+    )
+    db.add(memory)
+    await db.flush()
+    await db.refresh(memory)
+
+    # Store embedding if generated successfully
+    if embedding:
+        sql = sql_text(
+            "UPDATE agent_memories SET embedding = cast(:emb AS vector) WHERE id = :mid"
+        )
+        await db.execute(sql, {"emb": str(embedding), "mid": memory.id})
+        await db.flush()
+
+    return {
+        "id": str(memory.id),
+        "agent_id": str(memory.agent_id),
+        "memory_type": memory.memory_type,
+        "content": memory.content,
+        "owner_id": str(memory.owner_id) if memory.owner_id else None,
+        "created_at": memory.created_at.isoformat() if memory.created_at else None,
+    }
+
+
+async def retrieve_relevant_memories(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    agent_id: uuid.UUID,
+    query: str,
+    limit: int = 10,
+    memory_type: str | None = None,
+    min_score: float = 0.5,
+) -> list[dict[str, Any]]:
+    """Retrieve semantically relevant memories for an agent.
+
+    Uses pgvector cosine similarity search to find memories whose
+    embedding is closest to the query embedding.
+
+    Args:
+        db: Database session.
+        tenant_id: Tenant UUID.
+        agent_id: Agent UUID.
+        query: Natural language query to match against memories.
+        limit: Maximum number of results.
+        memory_type: Optional filter by memory type.
+        min_score: Minimum similarity score threshold (0.0 to 1.0).
+
+    Returns:
+        List of memory dicts with similarity scores, sorted by relevance.
+    """
+    # Generate embedding for the query
+    query_embedding = await generate_embedding(query, db=db, tenant_id=tenant_id)
+    if not query_embedding:
+        # Fallback: return recent memories if embedding fails
+        stmt = select(AgentMemory).where(
+            AgentMemory.tenant_id == tenant_id,
+            AgentMemory.agent_id == agent_id,
+            AgentMemory.deleted_at.is_(None),
+        )
+        if memory_type:
+            stmt = stmt.where(AgentMemory.memory_type == memory_type)
+        stmt = stmt.order_by(AgentMemory.created_at.desc()).limit(limit)
+        result = await db.execute(stmt)
+        memories = result.scalars().all()
+        return [
+            {
+                "id": str(m.id),
+                "agent_id": str(m.agent_id),
+                "memory_type": m.memory_type,
+                "content": m.content,
+                "score": 0.0,
+                "created_at": m.created_at.isoformat() if m.created_at else None,
+            }
+            for m in memories
+        ]
+
+    # Vector similarity search
+    type_filter = "AND m.memory_type = :mtype" if memory_type else ""
+    sql = sql_text(f"""
+        SELECT m.*, 1 - (m.embedding <=> cast(:emb AS vector)) AS score
+        FROM agent_memories m
+        WHERE m.tenant_id = :tid
+          AND m.agent_id = :aid
+          AND m.deleted_at IS NULL
+          AND m.embedding IS NOT NULL
+          {type_filter}
+        ORDER BY m.embedding <=> cast(:emb AS vector)
+        LIMIT :lim
+    """)
+
+    params: dict[str, Any] = {
+        "emb": str(query_embedding),
+        "tid": tenant_id,
+        "aid": agent_id,
+        "lim": limit,
+    }
+    if memory_type:
+        params["mtype"] = memory_type
+
+    result = await db.execute(sql, params)
+    rows = result.mappings().all()
+
+    return [
+        {
+            "id": str(row["id"]),
+            "agent_id": str(row["agent_id"]),
+            "memory_type": row["memory_type"],
+            "content": row["content"],
+            "score": float(row["score"]),
+            "created_at": row["created_at"].isoformat() if row.get("created_at") else None,
+        }
+        for row in rows
+        if float(row["score"]) >= min_score
+    ]
+
+
+async def delete_memory(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    memory_id: uuid.UUID,
+) -> bool:
+    """Delete a memory by ID."""
+    result = await db.execute(
+        select(AgentMemory).where(
+            AgentMemory.id == memory_id,
+            AgentMemory.tenant_id == tenant_id,
+        )
+    )
+    memory = result.scalar_one_or_none()
+    if memory is None:
+        return False
+    await db.delete(memory)
+    return True