Context-Keeper

基于LLM驱动的智能记忆与上下文管理系统

重新定义AI助手的记忆边界，让每一次对话都有意义

📋 目录导航

• 🎯 为什么选择Context-Keeper？
• 🎯 核心特性
• 🏗️ 架构设计
• 📖 部署与集成
• 🗺️ 产品发展路线图
• 🤝 贡献指南

1. AI时代的开发困境：当智能工具遇到记忆断层

"还记得昨天讨论的微服务架构方案吗？" → "抱歉，我不记得..." → 😤

📊 四维痛点：你是哪一种？

🔥 行业现状数据

• 📊 50%开发者每天重复解释项目背景给AI助手
• 💰 平均成本：替换一个资深工程师需要6-12个月
• ⏱️ 时间损失：新人完全熟悉复杂项目需要3-6个月
• 🔄 重复工作：团队中30-40%的技术问题是重复性的

核心问题：AI工具缺乏持续记忆能力，无法形成智能的知识积累和传承体系。面对这些困境，我们需要的不是另一个记忆工具，而是一个真正理解开发者意图的智能大脑。🚀 Context-Keeper：突破传统边界的智能解决方案

2. 核心特性

%%{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

🚀 三大核心突破

🎯 业务价值

对开发团队的价值

对企业的价值

• 📈 开发效率提升: 减少重复性解释和讨论
• 💰 人力成本节省: 新员工培训时间大幅度缩短
• 🎯 决策质量提升: 基于历史经验的智能建议
• 🔄 知识资产积累: 团队智慧的系统性沉淀

3. 架构设计

Context-Keeper目前经历了两个版本的迭代：

🧠 一期核心设计

📚 长短期记忆分层设计

• 短期记忆：存储完整的近期对话，使用本地文件系统，保证高速访问
• 长期记忆：存储关键信息摘要，使用向量数据库永久保存
• 渐进式压缩：信息从短期记忆的详细记录逐步转化为长期记忆的语义摘要

👤 用户隔离与个性化

• 会话隔离：每个用户拥有独立的会话空间，确保数据安全和隐私保护
• 工作空间隔离：不同项目/工作空间的上下文完全隔离，避免信息串扰
• 个性化记忆策略：根据用户工作风格自动调整记忆阈值和摘要策略
• 跨会话知识传递：在同一用户的不同会话间建立智能关联

🔄 记忆与批次管理机制

• 记忆ID (memoryID)：用户视角的"完整记忆"，对应一个工作任务或主题
• 批次ID (batchID)：系统视角的"存储单元"，对应连续对话片段
• 智能重要性评估：自动识别关键决策点，确保核心内容永久保存

🚀 二期LLM驱动升级

Context-Keeper基于LLM驱动的智能上下文记忆管理系统，在一期基础上实现了两个关键突破：

🧠 LLM驱动的宽召回+精排序架构 - 构建"意图理解 → 宽召回 → 精排序 → 智能合成"的LLM驱动架构

⭐️ 智能上下文管理 - 四维统一上下文模型+LLM驱动的全生命周期智能管理

🧠 3.1 LLM驱动的宽召回+精排序架构

🏗️ 架构图

⏱️ 时序图

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: ✅ 个性化架构方案

📋 架构核心特性

📋 3.2 智能上下文管理

Context-Keeper构建了四维统一上下文模型作为上下文信息的载体，通过LLM驱动的智能管理机制，实现上下文从初始构建→填充完善→智能分析&更新上下文（循环往复）的全生命周期管理

核心设计：

• 🏗️ 统一上下文模型：四维协同的数据存储基石
• 🔄 智能管理过程：LLM驱动的全生命周期管理机制
• ⚡️ 实时变更感知：语义级别的上下文变化检测与更新

🏗️ 智能上下文管理分层架构

⏱️ 智能上下文管理时序

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

🔥 管理机制核心优势：

• ✅ 统一存储基石：四维统一上下文模型作为所有管理操作的数据基础
• ✅ 全生命周期覆盖：从初始构建→填充完善→循环变更的完整管理链路
• ✅ LLM智能驱动：每个管理环节都有LLM参与决策，非传统规则引擎
• ✅ 实时变更感知：基于语义分析的上下文变化检测
• ✅ 无冲突合并：LLM驱动的智能冲突解决和优先级仲裁

4. 部署与集成

🛠️ 前置准备

在部署Context-Keeper之前，需要准备以下基础设施：

📊 多维存储基础设施

1. 向量数据库（必需）

我们设计了统一的向量存储接口，可按照开发者/企业需要自行扩展，支持多种向量数据库：

• 阿里云DashVector：可在阿里云控制台快速申请
• 京东云Vearch：可在京东云快速申请
• 自定义实现扩展：基于统一接口可扩展实现其他向量存储（如Milvus、Weaviate等）

# 配置示例（二选一）
# 选项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

2. 时序数据库（必须）

自行安装：TimescaleDB/PostgreSQL（用于时间线存储）

3. 图数据库（必须）

自行安装：Neo4j（用于知识图谱和关联分析）

4. LLM模型配置（必须）

我们支持本地和云端大模型配置，灵活满足不同场景需求：

🏠 本地模型（推荐）

• 基于Ollama框架，响应快、成本低、数据安全
• 安装Ollama：curl -fsSL https://ollama.ai/install.sh | sh
• 按需安装模型：ollama pull deepseek-coder-v2:16b
• 支持模型：CodeQwen、DeepSeek Coder、Llama等

☁️ 云端模型（备用）

• 申请对应LLM厂商的API密钥即可
• 支持：OpenAI、DeepSeek、Claude、通义千问等
• 配置简单，按需调用

5分钟快速开始

环境要求

• Go 1.21+
• 4GB+ 内存
• 支持Docker环境（可选）

一键本地部署

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

# 2. 环境配置（重要！）
cp confi