Context-Keeper

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

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

English | 简体中文

%%{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=localhost
TIMESCALEDB_PORT=5432
TIMESCALEDB_DATABASE=context_keeper_timeline
TIMESCALEDB_USERNAME=your-username
TIMESCALEDB_PASSWORD=your-password

# 知识图谱存储（Neo4j）
KNOWLEDGE_GRAPH_ENABLED=true
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-neo4j-password
NEO4J_DATABASE=neo4j

# =================================
# 会话管理配置
# =================================
SESSION_TIMEOUT=120m               # 会话超时时间（分钟）
CLEANUP_INTERVAL=30m               # 清理任务间隔
SHORT_MEMORY_MAX_AGE=3            # 短期记忆保留天数

llm:
  default:
    primary_provider: "ollama_local"    # 🔥 优先使用本地模型
    fallback_provider: "deepseek"      # 云端模型作为备用
    
  providers:
    # 🏠 本地模型配置（推荐）
    ollama_local:
      base_url: "http://localhost:11434"
      model: "deepseek-coder-v2:16b"   # 默认本地模型
      timeout: "60s"                   # 本地响应更快
      rate_limit: 0                    # 无限流限制
      available_models:                # 支持多种本地模型
        - "codeqwen:7b"               # 代码生成专用
        - "deepseek-coder:33b"        # 高性能代码模型
        - "deepseek-coder-v2:16b"     # 新一代代码模型
    
    # ☁️ 云端模型配置（备用）
    deepseek:
      api_key: "${DEEPSEEK_API_KEY}"
      model: "deepseek-chat"
      timeout: "120s"
      rate_limit: 6000
      
    openai:
      api_key: "${OPENAI_API_KEY}"
      model: "gpt-3.5-turbo"
      
    claude:
      api_key: "${CLAUDE_API_KEY}"
      model: "claude-3-sonnet-20240229"

# 3. 一键启动
./scripts/manage.sh deploy http --port 8088

# 4. 验证部署
curl http://localhost:8088/health
# 预期输出: {"status":"healthy","version":"v2.0.0"}

# 测试MCP协议连接
curl -X POST http://localhost:8088/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 测试智能记忆功能  
curl -X POST http://localhost:8088/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":2,"method":"tools/call",
    "params":{
      "name":"memorize_context",
      "arguments":{
        "sessionId":"test_session",
        "content":"这是一个架构设计讨论，采用微服务模式"
      }
    }
  }'

# 测试智能检索功能
curl -X POST http://localhost:8088/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":3,"method":"tools/call",
    "params":{
      "name":"retrieve_context", 
      "arguments":{
        "sessionId":"test_session",
        "query":"架构设计"
      }
    }
  }'

{
  "mcpServers": {
    "context-keeper": {
      "url": "http://localhost:8088/mcp"
    }
  }
}

# 复制预置的记忆管理规则（或者根据IDE实际情况拷贝复制）
cp .cursor/rules/memory-rules.md ~/.cursor/rules/context-keeper.md

# 规则内容预览
cat ~/.cursor/rules/context-keeper.md
# 包含：自动代码关联、实时记忆同步、智能检索提示等

// 在Cursor中测试
你: "帮我回忆一下这个项目的Redis缓存策略"
AI: [自动触发Context-Keeper检索]
   "根据8月15日的架构讨论，你们选择了Redis集群模式，
    主要考虑了以下因素：[显示历史讨论详情]"

# 安装扩展
code --install-extension context-keeper.cursor-integration

# 1. 构建镜像
docker build -t context-keeper:latest .

# 2. 使用Docker Compose部署
cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  context-keeper:
    image: context-keeper:latest
    ports:
      - "8088:8088"
    environment:
      - PORT=8088
      - LLM_PROVIDER=openai
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - VECTOR_PROVIDER=dashvector
      - DASHVECTOR_API_KEY=${DASHVECTOR_API_KEY}
    volumes:
      - ./data:/app/data
      - ./config:/app/config
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8088/health"]
      interval: 30s
      timeout: 10s
      retries: 3
EOF

# 3. 启动服务
docker-compose up -d

# 4. 查看服务状态
docker-compose ps
docker-compose logs -f context-keeper

# 1. 构建镜像（使用项目提供的Dockerfile）
docker build -t context-keeper:latest .

# 2. 运行容器
docker run -d \
  --name context-keeper \
  -p 8088:8088 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config:/app/config \
  --env-file config/.env \
  context-keeper:latest

# 3. 查看运行状态
docker ps
docker logs context-keeper

# 使用项目提供的docker-compose.yml
docker-compose up -d

# 查看服务状态
docker-compose ps
docker-compose logs -f context-keeper

# 停止服务
docker-compose down

gantt
    title Context-Keeper 产品发展路线图
    dateFormat  YYYY-MM-DD
    section 🏗️ 基础架构
    双层记忆系统          :done, basic1, 2025-04-01, 2025-06-30
    MCP协议集成          :done, basic2, 2025-04-01, 2025-06-30
    多向量引擎支持        :done, basic3, 2025-04-01, 2025-06-30
    
    section 🧠 智能大脑  
    用户/工作空间隔离      :done, brain0, 2025-07-01, 2025-09-30
    LLM两阶段分析        :done, brain1, 2025-07-01, 2025-09-30
    三要素智能识别        :done, brain2, 2025-07-01, 2025-09-30
    多维检索融合         :done, brain3, 2025-07-01, 2025-09-30
    
    section 🕸️ 知识图谱
    知识图谱存储引擎       :done, kg1, 2025-10-01, 2025-12-31
    图谱向量混合检索       :done, kg2, 2025-10-01, 2026-01-15
    跨项目知识复用        :active, kg3, 2026-01-01, 2026-03-31
    
    section 🏢 企业级
    多租户SaaS架构       :enterprise1, 2026-01-01, 2026-03-31
    安全合规体系         :enterprise2, 2026-01-01, 2026-03-31
    全球化部署           :enterprise3, 2026-01-01, 2026-03-31

%%{init: {'theme':'base', 'themeVariables': {'fontSize':'16px', 'fontFamily':'Arial, sans-serif'}}}%%
graph LR
    A[开源项目] -->|开发者贡献| B[技术创新]
    B -->|产品优化| C[用户体验提升]
    C -->|社区壮大| D[生态繁荣]
    D -->|反哺开源| A
    
    style A fill:#e8f5e9,stroke:#e2e8f0,stroke-width:0.5px,rx:8,ry:8
    style B fill:#e3f2fd,stroke:#e2e8f0,stroke-width:0.5px,rx:8,ry:8
    style C fill:#fff3e0,stroke:#e2e8f0,stroke-width:0.5px,rx:8,ry:8
    style D fill:#f3e5f5,stroke:#e2e8f0,stroke-width:0.5px,rx:8,ry:8

# 1. Fork并克隆项目
git clone https://github.com/YOUR_USERNAME/context-keeper.git
cd context-keeper

# 2. 环境准备
go version  # 确保Go 1.21+
node --version  # 确保Node.js 16+

# 3. 依赖安装
go mod download
npm install

# 4. 本地开发启动
cp config/.env.example config/.env
go run main.go --dev

# 5. 运行测试套件
go test ./...
npm test

# 6. 代码质量检查
golangci-lint run
npm run lint

# 1. 创建功能分支
git checkout -b feature/amazing-new-feature

# 2. 开发与测试
# ... 进行开发工作 ...
go test ./...

# 3. 提交代码（遵循Conventional Commits）
git add .
git commit -m "feat: add intelligent query rewriting engine

- Implement semantic query expansion
- Add multi-language support for query analysis  
- Integrate with LLM providers for intent recognition
- Add comprehensive test coverage

Closes #123"

# 4. 推送并创建PR
git push origin feature/amazing-new-feature
# 在GitHub上创建Pull Request

🧠 Context-Keeper - 重新定义AI助手的记忆边界

让每一次对话都有意义，让每一个决策都有传承

🚀 三步开启智能记忆时代

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

# 2️⃣ 一键启动服务  
./scripts/manage.sh deploy http --port 8088

# 3️⃣ 集成到您的IDE
# Cursor用户：配置MCP连接
# VSCode用户：安装官方扩展

🎯 选择最适合您的方案

🔗 快速链接

⭐ 如果Context-Keeper对您有帮助，请给我们一个Star！

📢 分享给更多需要智能记忆的开发者：