Context Keeper

%%{init: {'theme':'base', 'themeVariables': {'fontSize':'16px', 'fontFamily':'Arial, sans-serif'}}}%%
graph LR
    subgraph Stage1["🔍 多维宽召回<br/>(高覆盖率)"]
        A1("语义检索<br/>TOP-50") 
        A2("时间线检索<br/>TOP-30")
        A3("知识图谱<br/>TOP-20")
        A1 --> A4("候选集<br/>~100条")
        A2 --> A4
        A3 --> A4
    end
    
    subgraph Stage2["🧠 LLM精排序<br/>(高准确率)"]
        A4 --> B1("LLM智能分析")
        B1 --> B2("质量评估")
        B2 --> B3("相关性排序")
        B3 --> B4("TOP-N<br/>精准结果")
    end
    
    subgraph Stage3["🎯 多维融合<br/>(个性化输出)"]
        B4 --> C1("语义维度")
        B4 --> C2("时间维度") 
        B4 --> C3("知识维度")
        C1 --> C4("智能融合引擎")
        C2 --> C4
        C3 --> C4
        C4 --> C5("个性化方案")
    end
    
    style Stage1 fill:#e3f2fd,stroke:#e2e8f0,stroke-width:1px,rx:8,ry:8
    style Stage2 fill:#fff3e0,stroke:#e2e8f0,stroke-width:1px,rx:8,ry:8
    style Stage3 fill:#e8f5e9,stroke:#e2e8f0,stroke-width:1px,rx:8,ry:8

sequenceDiagram
    participant User as 👤 用户
    participant LLM1 as 🧠 LLM阶段一
    participant MDRE as 🔍 多维检索引擎
    participant LLM2 as 🧠 LLM阶段二
    participant Context as 🌟 上下文管理
    
    User->>LLM1: "回忆项目架构设计"
    LLM1->>LLM1: 🎯 意图分析<br/>核心意图+领域上下文+应用场景
    LLM1->>MDRE: 检索策略+查询改写
    
    par 宽召回阶段
        MDRE->>MDRE: 向量检索：架构语义
        MDRE->>MDRE: 时间线检索：设计讨论
        MDRE->>MDRE: 知识图谱：架构关联
    end
    
    MDRE->>LLM2: 候选集 (~100条)
    LLM2->>LLM2: 🧠 精排序<br/>质量评估+相关性排序
    LLM2->>Context: 结构化合成
    Context->>User: ✅ 个性化架构方案

sequenceDiagram
    participant User as 👤 用户
    participant SessionMgmt as 🚀 会话管理工具
    participant RetrieveCtx as 🔍 上下文检索工具
    participant StoreConv as 💾 对话存储工具
    participant AssocFile as 📝 文件关联工具
    participant Context as ⭐️ 上下文管理
    participant LLM1 as 🧠 LLM阶段一
    participant MDRE as 🔍 多维检索
    participant LLM2 as 🧠 LLM阶段二
    participant Storage as 💾 存储层
    
    Note over User,Storage: 🆕 初始构建（首次会话）
    
    User->>SessionMgmt: session_management(get_or_create)
    SessionMgmt->>SessionMgmt: 工程感知分析<br/>技术栈·架构·依赖识别
    SessionMgmt->>Context: 触发初始构建管理
    Context->>Context: 创建ProjectContext<br/>构建统一上下文模型基础
    Context->>Storage: 持久化ProjectContext
    
    Note over User,Storage: 🔍 填充完善（首次检索）
    
    User->>RetrieveCtx: retrieve_context(query, sessionId)
    RetrieveCtx->>Context: 获取当前上下文
    Context-->>RetrieveCtx: 返回ProjectContext
    RetrieveCtx->>LLM1: 用户查询+上下文
    LLM1->>LLM1: 意图理解+查询改写
    LLM1->>MDRE: 宽召回指令
    
    par 宽召回并行检索
        MDRE->>MDRE: 向量检索
        MDRE->>MDRE: 时间线检索  
        MDRE->>MDRE: 知识图谱检索
    end
    
    MDRE->>LLM2: 候选集数据
    LLM2->>Context: 获取当前上下文进行比对
    Context-->>LLM2: ProjectContext（其他维度待填充）
    LLM2->>LLM2: 🧠 语义比对+精排序合成
    LLM2->>Context: 触发填充完善管理
    Context->>Context: 完整构建TopicCtx+ConvCtx<br/>（CodeCtx由代码变更触发）
    Context->>Storage: 持久化完整上下文模型
    RetrieveCtx->>User: 返回智能合成结果
    
    Note over User,Storage: 🔄 变更管理（后续所有交互）
    
    loop 标准SOP循环：每次MCP工具调用
        alt 检索触发
            User->>RetrieveCtx: retrieve_context(query, sessionId)
            RetrieveCtx->>Context: 获取当前上下文
            Context-->>RetrieveCtx: 完整四维上下文
            RetrieveCtx->>LLM1: 查询+上下文
            LLM1->>MDRE: 宽召回
            MDRE->>LLM2: 候选集
            LLM2->>Context: 语义比对+变更检测
        else 存储触发
            User->>StoreConv: store_conversation(messages, sessionId)
            StoreConv->>Context: 获取当前上下文
            Context->>Context: 基于当前上下文进行变更检测
        else 代码变更触发
            User->>AssocFile: associate_file(filePath, sessionId)
            AssocFile->>Context: 获取当前上下文
            Context->>Context: 结合主题上下文更新CodeContext
        end
        
        Context->>Context: 🎯 变更检测管理<br/>当前上下文 vs 新数据
        
        alt 检测到语义变更
            Context->>Context: ⚡️ 智能更新管理<br/>增量变更+冲突解决
            Context->>Storage: 持久化变更
        else 无变更
            Context->>Context: 保持当前状态
        end
        
        alt 检索触发
            RetrieveCtx->>User: 返回检索结果
        else 存储触发
            StoreConv->>User: 返回存储确认
        else 代码变更触发
            AssocFile->>User: 返回关联确认
        end
    end

# 配置示例（二选一）
# 选项1：使用阿里云DashVector
VECTOR_STORE_TYPE=aliyun
VECTOR_DB_URL=https://your-instance.dashvector.cn-hangzhou.aliyuncs.com
VECTOR_DB_API_KEY=your-dashvector-api-key

# 选项2：使用京东云Vearch  
VECTOR_STORE_TYPE=vearch
VEARCH_URL=http://your-vearch-instance.jd.local
VEARCH_USERNAME=your-username
VEARCH_PASSWORD=your-password

# 1. 获取Context-Keeper
git clone https://github.com/redleaves/context-keeper.git
cd context-keeper

# 2. 环境配置（重要！）
cp config/env.template config/.env

# 编辑配置文件，填入必要参数
vim config/.env

# =================================
# 基础服务配置
# =================================
SERVICE_NAME=context-keeper         # 服务名称
PORT=8088                          # HTTP服务端口
DEBUG=false                        # 调试模式
STORAGE_PATH=./data                # 数据存储路径

# =================================
# 向量存储配置（必需）
# =================================
# 向量存储类型: aliyun | vearch
VECTOR_STORE_TYPE=aliyun           # 支持阿里云DashVector和京东云Vearch

# 阿里云DashVector配置
VECTOR_DB_URL=https://your-instance.dashvector.cn-hangzhou.aliyuncs.com
VECTOR_DB_API_KEY=your-dashvector-api-key
VECTOR_DB_COLLECTION=context_keeper
VECTOR_DB_DIMENSION=1536
SIMILARITY_THRESHOLD=0.4

# 京东云Vearch配置（可选替代）
VEARCH_URL=http://your-vearch-instance.jd.local
VEARCH_USERNAME=root
VEARCH_PASSWORD=your-password
VEARCH_DATABASE=db
VEARCH_REQUIRED_SPACES=context_keeper_vector,context_keeper_users

# =================================
# Embedding服务配置（必需）
# =================================
EMBEDDING_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings
EMBEDDING_API_KEY=your-dashscope-api-key

# 批量Embedding配置
BATCH_EMBEDDING_API_URL=https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
BATCH_QUEUE_SIZE=100
BATCH_WORKER_POLL_INTERVAL=5s

# =================================
# LLM配置（重点：支持本地和云端模型）
# =================================
# 🌟 支持本地和云端模型，本地模型响应快、灵活，适合语义分析和识别
LLM_PROVIDER=ollama_local          # 默认使用本地模型
LLM_MODEL=deepseek-coder-v2:16b    # 本地代码理解模型
LLM_MAX_TOKENS=80000               # 最大Token数
LLM_TEMPERATURE=0.1                # 温度参数（精确分析）
LLM_TIMEOUT_SECONDS=600            # 超时时间

# 云端模型API Keys（备用）
DEEPSEEK_API_KEY=your-deepseek-key  # DeepSeek云端API
OPENAI_API_KEY=your-openai-key      # OpenAI API
CLAUDE_API_KEY=your-claude-key      # Claude API


# 时间线存储（TimescaleDB/PostgreSQL）
TIMELINE_STORAGE_ENABLED=true
TIMESCALEDB_HOST=lo

…