su-memory SDK是一个Python SDK，为AI应用提供持久化记忆、因果推理、时空感知和三维世界建模能力，支持本地优先部署和隐私保护。

su-memory SDK：为AI赋予持久记忆与因果推理能力的开源框架\n\n## 背景：为什么AI需要真正的记忆？\n\n当前的大语言模型（LLM）虽然在推理和生成能力上表现出色，但它们有一个根本性的局限：缺乏真正的持久化记忆。每次对话都是独立的，模型无法记住你是谁、你们之前聊过什么、你的偏好是什么。开发者通常通过简单的对话历史拼接来解决这个问题，但这种方式存在明显缺陷：上下文长度有限、检索效率低下、无法建立概念之间的深层关联。\n\n更关键的是，人类的记忆不仅仅是信息的存储，而是包含因果推理、时间感知、空间认知等复杂维度。当我们回忆"上周在会议室讨论的项目方案"时，大脑同时调用了语义内容（项目方案）、时间信息（上周）、空间信息（会议室）以及因果关联（讨论导致了什么决策）。这种多维度的记忆检索正是当前AI系统所欠缺的。\n\n## 项目介绍\n\nsu-memory SDK是一个开源的Python SDK，旨在为AI应用构建真正的"世界模型"（World Model）。它不仅提供传统的向量记忆存储，更引入了因果推理引擎、时空感知系统和三维空间认知能力。项目的核心理念是：让AI像人类一样理解和利用记忆——不只是记住事实，而是理解事实之间的因果关系、时间演变和空间位置。\n\n该项目采用本地优先（Local-First）架构，所有数据处理都在本地完成，无需依赖外部云服务，既保护了用户隐私，又消除了API调用成本。\n\n## 核心架构与功能模块\n\nsu-memory SDK提供两个主要版本：轻量版（SuMemoryLite）和增强版（SuMemoryLitePro），满足不同场景的需求。\n\n### SuMemoryLite：快速上手的轻量方案\n\n轻量版适合快速验证和简单应用，特点包括：\n\n- TF-IDF检索：基于经典信息检索算法，无需GPU\n- N-gram分词：支持中文和英文文本处理\n- 持久化存储：记忆数据可保存到本地文件\n- 极小内存占用：低于5MB\n\n使用示例：\n\npython\nfrom su_memory.sdk import SuMemoryLite\n\nclient = SuMemoryLite()\n\n# 添加记忆\nclient.add(\"今天天气很好，阳光明媚\")\nclient.add(\"明天可能下雨，记得带伞\")\n\n# 查询记忆\nresults = client.query(\"天气\", top_k=2)\n\n\n### SuMemoryLitePro：生产级增强方案\n\n增强版是项目的核心亮点，集成了多种先进的记忆和推理技术：\n\n#### 1. 向量语义检索（Vector RAG）\n\n使用本地Ollama部署的bge-m3嵌入模型（1024维），实现高质量的语义相似度匹配。相比简单的关键词匹配，语义检索能够理解概念的深层含义，例如查询"学习"可以召回"读书"、"上课"等相关但不完全相同的概念。\n\n采用HNSW（Hierarchical Navigable Small World）索引优化，参数设置为m=32、ef=64，在保持O(log n)搜索复杂度的同时，实现高效的近似最近邻搜索。\n\n#### 2. VectorGraphRAG：多跳因果推理引擎\n\n这是su-memory最具创新性的功能之一。传统RAG（检索增强生成）只能做简单的相似度匹配，而VectorGraphRAG能够进行多跳推理（Multi-hop Reasoning）。\n\n例如，给定以下记忆：\n\n\n\"如果努力学习，成绩会提高\"\n\"成绩提高了会获得奖学金\"\n\"获得奖学金可以减轻家庭负担\"\n\n\n通过建立因果链（努力学习 → 成绩提高 → 获得奖学金 → 减轻负担），系统可以回答"努力学习会带来什么结果？"这样的间接问题，即使原始记忆中从未直接陈述"努力学习减轻家庭负担"。\n\n技术实现上，VectorGraphRAG结合了向量检索和图遍历：先用向量检索找到起点，然后在记忆图谱上进行BFS（广度优先搜索）遍历，支持3跳以上的深度推理。因果类型包括cause（原因）、condition（条件）、result（结果）、sequence（序列）等。\n\n#### 3. 时空感知系统\n\n人类的记忆与时间紧密关联。su-memory通过以下组件实现时序感知：\n\n- SpacetimeIndex：时空索引，同时记录记忆的内容和时间戳\n- TemporalSystem：时序编码系统，理解时间衰减（越久远的记忆相关性越低）\n- 时序预测模块：基于历史趋势预测未来事件\n\n这种设计使AI能够理解"上周"、"上个月"、"即将发生"等时间概念，并在检索时考虑时效性权重。\n\n#### 4. SpatialRAG：三维世界模型\n\n更进一步，su-memory支持空间认知能力：\n\n- KD-Tree空间索引：高效的三维空间数据结构\n- 空间+时间+语义三维检索：可以查询"会议室A上周发生的与技术相关的讨论"\n- 空间邻域搜索：查找某个位置附近发生的所有事件\n\n这为构建具身智能（Embodied AI）和机器人应用奠定了基础。\n\n#### 5. 多模态记忆\n\n除了文本，su-memory还支持图像和音频记忆：\n\n- CLIP图像编码器：将图像转换为512维向量\n- Whisper音频编码器：处理语音内容\n- 多模态融合检索：可以同时检索"与会议相关的图片和文字记录"\n\n#### 6. 可解释性\n\n每条记忆的检索结果都附带详细的解释，说明为什么这条记忆被召回：\n\n\n针对查询'项目'，系统检索到3条相关记忆。\n\n最相关记忆：项目进展顺利\n相关度得分：85.52%\n\n检索因素：\n• 语义匹配（权重40%）：85.52%\n• 因果关联（权重30%）：基于图谱推理\n• 时序相关性（权重20%）：时效性已计算\n\n\n这种透明度对于调试和优化AI应用至关重要。\n\n#### 7. 跨会话召回\n\n通过SessionManager，系统可以管理多个对话会话，并支持跨会话的话题关联。例如，在"项目会议"会话中讨论的技术方案，可以在之后的"日常对话"中被关联召回。\n\n## 性能优化与量化\n\nsu-memory在性能优化上做了大量工作：\n\n### 向量量化压缩\n\n支持多种精度模式，在内存占用和检索精度之间灵活权衡：\n\n| 量化模式 | 压缩比 | 精度损失 | 适用场景 |\n|---------|--------|---------|---------|\n| FP32 | 1x | 0% | 高精度需求 |\n| FP16 | 2x | <1% | 平衡场景 |\n| INT8 | 4x | <1% | 推荐 |\n| Binary | 32x | ~20% | 极端内存限制 |\n\n使用INT8量化，内存占用可减少到原来的25%，而精度损失不到1%。\n\n### 性能基准\n\n官方测试数据显示：\n\n- 插入性能：94条/秒，平均耗时10.66ms/条\n- 查询性能：P50延迟0.27ms，P95延迟0.39ms，P99延迟0.43ms\n- 内存占用：1000条记忆仅需1.53MB\n- 语义检索：约50ms/查询（本地Ollama）\n\n经过优化后，多跳推理召回率从60%提升到87.8%（+46%），查询延迟从500ms降至19ms（↓96%）。\n\n## 与LangChain集成\n\nsu-memory提供官方LangChain适配器，可以轻松替换默认的记忆组件：\n\npython\nfrom su_memory.sdk import SuMemoryLite\nfrom su_memory.adapters import SuMemoryChatMemory\n\nclient = SuMemoryLite()\nmemory = SuMemoryChatMemory(client=client)\n\n# 保存对话上下文\nmemory.save_context(\n inputs={\"input\": \"我叫张三\"},\n outputs={\"output\": \"你好张三，很高兴认识你！\"}\n)\n\n# 加载记忆用于后续对话\nvars = memory.load_memory_variables({})\n\n\n## 应用场景\n\nsu-memory适用于多种AI应用场景：\n\n### 1. 个人AI助手\n\n构建真正"了解你"的AI助手，记住你的喜好、习惯、历史对话，支持长期陪伴。\n\n### 2. 企业知识管理\n\n将企业文档、会议记录、决策过程存入记忆系统，支持基于因果关系的智能问答（"为什么我们在2023年选择了技术方案A？"）。\n\n### 3. 具身智能与机器人\n\n结合SpatialRAG的三维空间能力，让机器人记住环境布局、物体位置、历史交互。\n\n### 4. 多Agent协作系统\n\n在VMC（Vision-Memory-Controller）框架中，su-memory作为Memory组件，与Claude 4（Controller）、Gemini 2.0（Vision）等模型协同工作，构建完整的认知架构。\n\n## 安装与快速开始\n\nbash\npip install su-memory\n\n\n验证安装：\n\npython\nfrom su_memory import SuMemoryLitePro\nprint('✅ 安装成功')\n\n\n## 总结与展望\n\nsu-memory SDK代表了AI记忆系统的一个新方向：从简单的向量存储，演进为支持因果推理、时空感知、空间认知的"世界模型"。本地优先的架构设计既保护了隐私，又降低了使用成本。\n\n项目成熟度评估（综合4.9/5）：\n\n- 长期记忆：⭐⭐⭐⭐⭐\n- 因果推理：⭐⭐⭐⭐⭐\n- 时空感知：⭐⭐⭐⭐⭐\n- 多模态支持：⭐⭐⭐⭐\n- 可解释性：⭐⭐⭐⭐\n\n对于需要构建具有"真正记忆"的AI应用的开发者来说，su-memory提供了一个功能丰富、性能优异、隐私友好的开源选择。

su-memory SDK：为AI赋予持久记忆与因果推理能力的开源框架\n\n背景：为什么AI需要真正的记忆？\n\n当前的大语言模型（LLM）虽然在推理和生成能力上表现出色，但它们有一个根本性的局限：缺乏真正的持久化记忆。每次对话都是独立的，模型无法记住你是谁、你们之前聊过什么、你的偏好是什么。开发者通常通过简单的对话历史拼接来解决这个问题，但这种方式存在明显缺陷：上下文长度有限、检索效率低下、无法建立概念之间的深层关联。\n\n更关键的是，人类的记忆不仅仅是信息的存储，而是包含因果推理、时间感知、空间认知等复杂维度。当我们回忆"上周在会议室讨论的项目方案"时，大脑同时调用了语义内容（项目方案）、时间信息（上周）、空间信息（会议室）以及因果关联（讨论导致了什么决策）。这种多维度的记忆检索正是当前AI系统所欠缺的。\n\n项目介绍\n\nsu-memory SDK是一个开源的Python SDK，旨在为AI应用构建真正的"世界模型"（World Model）。它不仅提供传统的向量记忆存储，更引入了因果推理引擎、时空感知系统和三维空间认知能力。项目的核心理念是：让AI像人类一样理解和利用记忆——不只是记住事实，而是理解事实之间的因果关系、时间演变和空间位置。\n\n该项目采用本地优先（Local-First）架构，所有数据处理都在本地完成，无需依赖外部云服务，既保护了用户隐私，又消除了API调用成本。\n\n核心架构与功能模块\n\nsu-memory SDK提供两个主要版本：轻量版（SuMemoryLite）和增强版（SuMemoryLitePro），满足不同场景的需求。\n\nSuMemoryLite：快速上手的轻量方案\n\n轻量版适合快速验证和简单应用，特点包括：\n\n- TF-IDF检索：基于经典信息检索算法，无需GPU\n- N-gram分词：支持中文和英文文本处理\n- 持久化存储：记忆数据可保存到本地文件\n- 极小内存占用：低于5MB\n\n使用示例：\n\npython\nfrom su_memory.sdk import SuMemoryLite\n\nclient = SuMemoryLite()\n\n添加记忆\nclient.add(\"今天天气很好，阳光明媚\")\nclient.add(\"明天可能下雨，记得带伞\")\n\n查询记忆\nresults = client.query(\"天气\", top_k=2)\n\n\nSuMemoryLitePro：生产级增强方案\n\n增强版是项目的核心亮点，集成了多种先进的记忆和推理技术：\n\n1. 向量语义检索（Vector RAG）\n\n使用本地Ollama部署的bge-m3嵌入模型（1024维），实现高质量的语义相似度匹配。相比简单的关键词匹配，语义检索能够理解概念的深层含义，例如查询"学习"可以召回"读书"、"上课"等相关但不完全相同的概念。\n\n采用HNSW（Hierarchical Navigable Small World）索引优化，参数设置为m=32、ef=64，在保持O(log n)搜索复杂度的同时，实现高效的近似最近邻搜索。\n\n2. VectorGraphRAG：多跳因果推理引擎\n\n这是su-memory最具创新性的功能之一。传统RAG（检索增强生成）只能做简单的相似度匹配，而VectorGraphRAG能够进行多跳推理（Multi-hop Reasoning）。\n\n例如，给定以下记忆：\n\n\n\"如果努力学习，成绩会提高\"\n\"成绩提高了会获得奖学金\"\n\"获得奖学金可以减轻家庭负担\"\n\n\n通过建立因果链（努力学习 → 成绩提高 → 获得奖学金 → 减轻负担），系统可以回答"努力学习会带来什么结果？"这样的间接问题，即使原始记忆中从未直接陈述"努力学习减轻家庭负担"。\n\n技术实现上，VectorGraphRAG结合了向量检索和图遍历：先用向量检索找到起点，然后在记忆图谱上进行BFS（广度优先搜索）遍历，支持3跳以上的深度推理。因果类型包括cause（原因）、condition（条件）、result（结果）、sequence（序列）等。\n\n3. 时空感知系统\n\n人类的记忆与时间紧密关联。su-memory通过以下组件实现时序感知：\n\n- SpacetimeIndex：时空索引，同时记录记忆的内容和时间戳\n- TemporalSystem：时序编码系统，理解时间衰减（越久远的记忆相关性越低）\n- 时序预测模块：基于历史趋势预测未来事件\n\n这种设计使AI能够理解"上周"、"上个月"、"即将发生"等时间概念，并在检索时考虑时效性权重。\n\n4. SpatialRAG：三维世界模型\n\n更进一步，su-memory支持空间认知能力：\n\n- KD-Tree空间索引：高效的三维空间数据结构\n- 空间+时间+语义三维检索：可以查询"会议室A上周发生的与技术相关的讨论"\n- 空间邻域搜索：查找某个位置附近发生的所有事件\n\n这为构建具身智能（Embodied AI）和机器人应用奠定了基础。\n\n5. 多模态记忆\n\n除了文本，su-memory还支持图像和音频记忆：\n\n- CLIP图像编码器：将图像转换为512维向量\n- Whisper音频编码器：处理语音内容\n- 多模态融合检索：可以同时检索"与会议相关的图片和文字记录"\n\n6. 可解释性\n\n每条记忆的检索结果都附带详细的解释，说明为什么这条记忆被召回：\n\n\n针对查询'项目'，系统检索到3条相关记忆。\n\n最相关记忆：项目进展顺利\n相关度得分：85.52%\n\n检索因素：\n• 语义匹配（权重40%）：85.52%\n• 因果关联（权重30%）：基于图谱推理\n• 时序相关性（权重20%）：时效性已计算\n\n\n这种透明度对于调试和优化AI应用至关重要。\n\n7. 跨会话召回\n\n通过SessionManager，系统可以管理多个对话会话，并支持跨会话的话题关联。例如，在"项目会议"会话中讨论的技术方案，可以在之后的"日常对话"中被关联召回。\n\n性能优化与量化\n\nsu-memory在性能优化上做了大量工作：\n\n向量量化压缩\n\n支持多种精度模式，在内存占用和检索精度之间灵活权衡：\n\n| 量化模式 | 压缩比 | 精度损失 | 适用场景 |\n|---------|--------|---------|---------|\n| FP32 | 1x | 0% | 高精度需求 |\n| FP16 | 2x | <1% | 平衡场景 |\n| INT8 | 4x | <1% | 推荐 |\n| Binary | 32x | ~20% | 极端内存限制 |\n\n使用INT8量化，内存占用可减少到原来的25%，而精度损失不到1%。\n\n性能基准\n\n官方测试数据显示：\n\n- 插入性能：94条/秒，平均耗时10.66ms/条\n- 查询性能：P50延迟0.27ms，P95延迟0.39ms，P99延迟0.43ms\n- 内存占用：1000条记忆仅需1.53MB\n- 语义检索：约50ms/查询（本地Ollama）\n\n经过优化后，多跳推理召回率从60%提升到87.8%（+46%），查询延迟从500ms降至19ms（↓96%）。\n\n与LangChain集成\n\nsu-memory提供官方LangChain适配器，可以轻松替换默认的记忆组件：\n\npython\nfrom su_memory.sdk import SuMemoryLite\nfrom su_memory.adapters import SuMemoryChatMemory\n\nclient = SuMemoryLite()\nmemory = SuMemoryChatMemory(client=client)\n\n保存对话上下文\nmemory.save_context(\n inputs={\"input\": \"我叫张三\"},\n outputs={\"output\": \"你好张三，很高兴认识你！\"}\n)\n\n加载记忆用于后续对话\nvars = memory.load_memory_variables({})\n\n\n应用场景\n\nsu-memory适用于多种AI应用场景：\n\n1. 个人AI助手\n\n构建真正"了解你"的AI助手，记住你的喜好、习惯、历史对话，支持长期陪伴。\n\n2. 企业知识管理\n\n将企业文档、会议记录、决策过程存入记忆系统，支持基于因果关系的智能问答（"为什么我们在2023年选择了技术方案A？"）。\n\n3. 具身智能与机器人\n\n结合SpatialRAG的三维空间能力，让机器人记住环境布局、物体位置、历史交互。\n\n4. 多Agent协作系统\n\n在VMC（Vision-Memory-Controller）框架中，su-memory作为Memory组件，与Claude 4（Controller）、Gemini 2.0（Vision）等模型协同工作，构建完整的认知架构。\n\n安装与快速开始\n\nbash\npip install su-memory\n\n\n验证安装：\n\npython\nfrom su_memory import SuMemoryLitePro\nprint('✅ 安装成功')\n\n\n总结与展望\n\nsu-memory SDK代表了AI记忆系统的一个新方向：从简单的向量存储，演进为支持因果推理、时空感知、空间认知的"世界模型"。本地优先的架构设计既保护了隐私，又降低了使用成本。\n\n项目成熟度评估（综合4.9/5）：\n\n- 长期记忆：⭐⭐⭐⭐⭐\n- 因果推理：⭐⭐⭐⭐⭐\n- 时空感知：⭐⭐⭐⭐⭐\n- 多模态支持：⭐⭐⭐⭐\n- 可解释性：⭐⭐⭐⭐\n\n对于需要构建具有"真正记忆"的AI应用的开发者来说，su-memory提供了一个功能丰富、性能优异、隐私友好的开源选择。