双层MemCube代理后端
一个强大的模块化人工智能后端，实现 双层内存架构它针对低延迟对话（热内存）和大规模历史回忆（冷内存/矢量数据库）进行了优化。
内置于 快速API, ChromaDB，并设计为完全可定制——轻松切换 开放人工智能, 奥拉玛, vLLM，或任何与OpenAI兼容的API。
🚀 主要特点
- 双层存储系统:
- L1（热存储器）：用于最近上下文的内存LRU缓存。包括一个“重要性”锁，以防止关键信息被驱逐。 - L2（冷记忆）：持久向量数据库（ChromaDB），用于长期存储溢出的内存。
- 瀑布检索：智能上下文查找，首先查询L1，必要时才回退到Vector DB，从而减少延迟和成本。
- 可定制的AI提供商：无缝支持：
- 开放人工智能 （GPT-3.5/4） - 本地LLMs （Ollama、vLLM、LocalAI） - 模拟模式 （零成本测试）
- 生产就绪：基于FastAPI构建，具有异步请求处理、模块化架构和结构化日志记录。
📊 基准结果
我们将MemCube与传统的聊天历史系统（将最后30条消息保存在上下文中）进行了比较。两者都使用相同的人工智能API进行公平比较。
绩效总结
| 度量 | MemCube | 传统 | 优势 |
|---|---|---|---|
| 平均延迟 | 7758毫秒 | 12272毫秒 | 速度提高37% ⚡ |
| 最小延迟 | 5368毫秒 | 6141毫秒 | 快13% |
| 最大延迟 | 16218毫秒 | 19746毫秒 | 18%更快 |
| 召回率 | 100% | 100% | 相等✓ |
| API调用 | 30 | 30 | 相等 |
视觉比较
为什么MemCube更快
- 延迟嵌入 -立即保存内存；在背景中生成嵌入
- 智能检索 -如果L1中存在足够多的最近上下文，则跳过昂贵的向量搜索
- 无查询嵌入 -对于最近的对话，不需要嵌入生成
与传统系统相比的其他优势
| 功能 | MemCube | 传统 |
|---|---|---|
| 可扩展性 | 处理1000+个对话 | 上下文窗口有限 |
| 跨会话内存 | ✅ 持续 | ❌ 仅限会话 |
| 旧记忆检索 | ✅ 矢量搜索 | ❌ 窗户后丢失 |
| 关键信息保护 | ✅ 重要性锁定 | ❌ FIFO驱逐 |
运行基准
# Start the backend
python -m app.main
# In another terminal, run benchmark
python benchmark.py
# Generate charts (optional)
python generate_charts.py🛠️ 安装
- 克隆存储库 （如果适用）或导航到项目文件夹：
cd memcube_backend- 安装依赖项:
建议使用虚拟环境（venv/conda）。
pip install -r requirements.txt⚙️ 配置
复制示例配置文件：
cp .env.example .env选项A：使用OpenAI
编辑 .env 使用官方的OpenAI API：
AI_PROVIDER_TYPE=openai
AI_API_KEY=sk-proj-...
AI_CHAT_MODEL=gpt-3.5-turbo
AI_EMBEDDING_MODEL=text-embedding-3-small选项B：使用本地LLM（Ollama）
编辑 .env 指向您的本地实例。 不需要API密钥。
AI_PROVIDER_TYPE=custom
AI_BASE_URL=http://localhost:11434/v1
AI_API_KEY=ollama
AI_CHAT_MODEL=llama3
AI_EMBEDDING_MODEL=nomic-embed-text选项C：模拟模式（测试）
非常适合在不运行LLM的情况下测试逻辑。
AI_PROVIDER_TYPE=mock🏃♂️ 用法
启动服务器：
python -m app.main服务器将在以下时间启动 http://localhost:8000.
API终点
互动文档可在 http://localhost:8000/docs.
1.与记忆聊天
POST /api/v1/chat
{
"message": "My secret code is 42",
"importance": "high"
}*代理将使用来自L1或L2内存的上下文进行响应。高度重要的消息不会被遗忘（从L1中删除）。*
2.手动添加内存
POST /api/v1/memory
{
"content": "The project deadline is next Friday.",
"importance": "normal",
"source": "slack_integration"
}🔌 MCP服务器支持（克劳德桌面集成）
MemCube实现了 模型上下文协议（MCP），允许它被智能代理用作本机内存工具，如 克劳德桌面 或 光标.
特性
- 持久内存：克劳德可以保存关于你的重要事实，这些事实在会话中持续存在。
- 语义搜索：Claude可以根据您当前的查询检索相关的过去上下文。
Claude桌面设置
- 确保本地后端正在运行(
python -m app.main) - 编辑您的Claude桌面配置(
~/Library/Application Support/Claude/claude_desktop_config.json在Mac上，或%APPDATA%\Claude\claude_desktop_config.json在Windows上）：
{
"mcpServers": {
"memcube": {
"command": "python",
"args": ["/absolute/path/to/memcube_backend/mcp_server.py"]
}
}
}- 重新启动克劳德桌面。你会看到🛠️ 表示MemCube工具的图标(
save_memory,retrieve_memory)可用。
📂 项目结构
memcube_backend/
├── app/
│ ├── api/ # API Routes
│ ├── core/ # Config & Settings
│ ├── llm/ # AI Provider Factory (OpenAI/Custom/Mock)
│ ├── models/ # Pydantic Data Models
│ ├── services/ # Business Logic
│ │ ├── manager.py # Memory Manager (Orchestrator)
│ │ ├── memory_l1.py # Hot Memory Logic
│ │ └── memory_l2.py # Cold Memory Logic
│ └── main.py # App Entry Point
├── .env # Environment Variables
└── requirements.txt # Dependencies🧠 建筑细部
“溢出”机制
当L1（热存储器）达到容量时，它会驱逐 最近最少使用（LRU） 将项目转换为L2（冷内存）。
- 异常：如果一个项目被标记
importance="high"，它被移动到缓存的前面 未被驱逐，确保关键指令（如“我的名字是爱丽丝”或“充当python专家”）始终能够快速访问。
“瀑布”检索
检索用户查询的上下文时：
- 搜索L1：计算所有热记忆的余弦相似度。
- 提前退出：如果找到具有相似性的匹配项>
0.85，它立即返回。 - 后备方案：如果在L1中没有找到良好的匹配，它将搜索向量数据库（L2）。