flowchart LR
    subgraph Clients["MCP clients"]
        Codex[Codex]
        Claude[Claude]
        Copilot[Copilot]
        OpenCode[OpenCode]
        VSCode[VS Code]
    end

    subgraph Repository["AI Memory MCP repository"]
        MCP["MCP facade<br/>Eight public tools"]
        Service["MemoryService<br/>Policy and orchestration"]
        Retrieval["RetrievalEngine<br/>Scope, fusion, and reranking"]
        Indexer["Memory indexer<br/>Validation and snapshots"]
        Adapter["GraphifyAdapter<br/>Replaceable provider boundary"]
        Skill["Canonical ai-memory skill"]
    end

    subgraph Authority["Canonical authority"]
        Markdown["Markdown memory<br/>Durable source of truth"]
    end

    subgraph Derived["Derived state"]
        SQLite["Versioned SQLite<br/>FTS5 and semantic vectors"]
        Graph["Graphify graph<br/>Nodes, edges, and paths"]
    end

    Clients --> MCP
    MCP --> Service
    Service --> Retrieval
    Retrieval --> SQLite
    Retrieval --> Adapter
    Adapter --> Graph
    Markdown --> Indexer
    Indexer --> SQLite
    Markdown --> Graph
    Skill -. guides .-> Clients

sequenceDiagram
    participant Agent
    participant MCP as MCP facade
    participant Service as MemoryService
    participant Engine as RetrievalEngine
    participant SQLite as SQLite index
    participant Graphify as GraphifyAdapter

    Agent->>MCP: memory_search query and scope
    MCP->>Service: Validate tool input
    Service->>Engine: Search request
    Engine->>Engine: Resolve scope and ticket identifiers
    Engine->>SQLite: Get scoped lexical candidates
    SQLite-->>Engine: Ranked lexical hits
    Engine->>SQLite: Get scoped semantic vectors
    SQLite-->>Engine: Ranked semantic hits
    Engine->>Graphify: Rank scoped candidate paths
    Graphify-->>Engine: Relationship signals
    Engine->>Engine: Fuse results with RRF
    Engine->>Engine: Deduplicate and rerank
    Engine->>SQLite: Expand bounded context
    Engine-->>Service: Evidence packet with source paths
    Service-->>MCP: Structured result
    MCP-->>Agent: Cited memory evidence

flowchart TD
    Change[Canonical Markdown change] --> Mode{Refresh mode}
    Mode -->|index| IndexStage[Build staged SQLite snapshot]
    Mode -->|full| GraphStage[Build staged Graphify data]
    GraphStage --> GraphValidate{Graph validation}
    GraphValidate -->|pass| GraphPublish[Publish Graphify graph]
    GraphValidate -->|fail| GraphKeep[Keep the last satisfactory graph]
    GraphPublish --> IndexStage
    IndexStage --> IndexValidate{Index validation}
    IndexValidate -->|pass| Pointer[Publish the current-index pointer]
    IndexValidate -->|fail| IndexKeep[Keep the last satisfactory index]
    Pointer --> Health[Run health and retrieval checks]

.\scripts\setup.ps1 -MemoryRoot 'C:\path\to\AI-Memory' -InstallClients