Add CHANGELOG

CHANGELOG.md

@@ -0,0 +1,394 @@
+# 更新日志
+
+所有重要的项目更新都会在此记录。
+
+格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/) 标准。
+
+---
+
+## [v2.5.0] - 2026-05-05
+
+> **AGI Continual Learning Loop: Four-Layer Closed-Loop Architecture**
+
+### Major Features
+
+#### Four-Layer Continual Learning Loop (AGI-level)
+- **Layer 1 — Perception**: Multi-provider LLM energy inference (DeepSeek → MiniMax → Ollama), $\\ge$85% accuracy target
+- **Layer 2 — Distillation**: `distill_patterns()` for energy-based memory clustering + `extract_rules()` for rule abstraction with confidence scoring
+- **Layer 3 — Routing**: `route_memory()` for energy-affinity-based cluster routing + `get_importance_scores()` for dynamic priority
+- **Layer 4 — Reflection**: `reflect_and_optimize()` for 4-dimension health audit + `evolution_pipeline()` for full closed-loop execution
+
+#### Energy System Full Activation (7000-line engine)
+- **EnergyBus**: 3-layer propagation network with recursive decay and prior/posterior weight fusion
+- **CategoryCausalEngine**: `query_with_energy_boost()` — energy-affinity re-ranking of search results
+- **UnifiedInfoFactory**: Integrated temporal-category-energy label generation with extended attributes
+- **Energy Ecology**: `analyze_memory_ecology()` — balance analysis, pattern detection, and actionable suggestions
+
+#### Three-Dimensional Calculus Mapping
+- `resolve_trigram_to_semantic()`: 3D weighted voting (NAJIA/PRIOR/POST) with integration/differentiation/gradient mechanics
+- Achieves 100% mapping accuracy (8/8, up from 25%), 64-hexagram full correctness
+
+#### Auto Energy Relationship Discovery
+- `link_by_energy()`: Create energy-weighted links between memories with affinity calculation
+- `auto_link_by_energy()`: Full-scan energy affinity discovery + automatic link creation
+
+### Bug Fixes
+- **Critical**: English/Chinese naming incompatibility fixed — energy boost now works correctly (was identity 1.0x due to key mismatch)
+- **Critical**: `TrigramType` / `SemanticType` index mismatch fixed via 3D calculus resolver (was 25%, now 100%)
+- query cache key now includes `energy_filter` and `time_range`
+- `query_multihop()` and `query_multihop_spacetime()` now support `energy_filter` parameter
+- All SDK-layer Chinese defaults replaced with English (`spatial_rag.py`, `multimodal.py`)
+- `num_predict` increased from 5 to 20 for Ollama inference, `raw=True` for thinking models
+
+### Security
+- Removed deprecated test files with sensitive architecture references
+- Replaced `wuxing_` node prefix with `element_` in EnergyBus
+- Sanitized public documentation (USER_GUIDE, RELEASE_CHECKLIST, client.py, demo, test_installed)
+- Internal architecture docs secured in non-git-tracked directory
+
+### Performance
+- 33/33 regression tests passing (P0-P3 + L1-L4)
+- Write throughput: comparable to v2.0.1 baseline
+- Query latency: no regression from v2.0.1
+- Energy inference: multi-provider fallback chain with caching
+
+---
+
+## [v2.0.1] - 2026-05-04
+
+> **记忆生命周期 + REST API 完善**
+
+### 新增功能
+
+#### 记忆生命周期管理
+- **forget(memory_id)**: 删除单条记忆
+- **decay(days)**: 时间衰减，自动归档超过指定天数的旧记忆
+- **summarize(topic)**: 将多条记忆压缩为单条摘要
+- **conflict_resolution()**: 检测矛盾记忆（完成/未完成、是/否等）
+- **clear()**: 清空所有记忆
+
+#### REST API Server
+- **FastAPI wrapper**: 轻量级 REST API，一行启动
+- **完整 CRUD**: POST/GET/DELETE memories
+- **多跳推理端点**: /query/multihop
+- **生命周期端点**: /memories/decay, /memories/summarize, /memories/conflicts
+- **交互式文档**: http://localhost:8000/docs
+
+```bash
+# 启动 REST API
+pip install su-memory[api]
+uvicorn su_memory.api.server:app --reload --port 8000
+```
+
+### 安装选项更新
+
+| 选项 | 命令 | 包含 |
+|------|------|------|
+| REST API | `pip install su-memory[api]` | FastAPI + uvicorn |
+
+---
+
+## [v1.7.0] - 2026-04-26
+
+> **生态扩展版本：插件系统 + 多语言SDK + 本地存储 + AI框架集成**
+
+本次更新完成了v1.7.0生态扩展目标，实现了插件系统、多语言SDK、本地存储管理和AI框架集成。
+
+### 用户体验优化
+
+- **API命名统一**: `query_multi_hop` → `query_multihop` (全代码库7处)
+- **环境检测优化**: 警告只提示一次，避免重复打扰
+- **README故事化**: 突出"一行代码"价值，15秒讲清核心价值
+- **多跳推理默认模式**: fusion_mode改为"hybrid"（向量60%+图谱40%），更好展开多跳推理
+- **开箱即用多跳推理**: pip install su-memory 默认集成FAISS + sentence-transformers
+- **异步批量写入**: add_batch()同步10万条/秒，aadd_batch()异步版本
+- **异步流式查询**: astream_query()异步生成器
+
+### 新增功能
+
+#### W25-W26 插件系统
+- **PluginInterface**: 标准化插件抽象接口
+- **PluginRegistry**: 线程安全的插件注册表（单例模式）
+- **SandboxedExecutor**: 沙箱执行器，支持超时控制和异常隔离
+- **官方插件示例**:
+  - TextEmbeddingPlugin: 文本嵌入插件
+  - RerankPlugin: 检索结果重排序插件
+  - MonitorPlugin: 性能监控插件
+
+#### W27-W28 多语言SDK
+- **TypeScript SDK**: 完整类型定义，LangChain Retriever/Tool支持
+- **JavaScript SDK**: CommonJS兼容，Node.js 18+支持
+- **Python API Server**: RESTful HTTP服务
+
+#### W29-W30 本地数据管理
+- **SQLiteBackend**: 本地SQLite存储后端，支持向量查询
+- **AutoCompressor**: LZ4自动压缩（175:1压缩比）
+- **BackupManager**: 定时备份与恢复
+- **DataExporter**: JSON/CSV/Markdown导出
+
+#### W31-W32 AI框架集成
+- **LangChain Adapter**: SuMemoryRetriever, SuMemoryTool, SuMemoryMemory
+- **LlamaIndex Connector**: SuMemoryIndex向量索引
+- **CLI工具**: 13个命令（init, add, query, search, delete, stats, export, import, backup, restore, plugin）
+
+### 性能优化
+
+| 组件 | 优化项 | 性能提升 |
+|------|--------|----------|
+| PluginRegistry | O(1)字典索引 | ~100x |
+| PluginRegistry | 读锁分离 | 并发↑ |
+| SQLiteBackend | 查询缓存LRU | 缓存命中→O(1) |
+| SandboxedExecutor | 结果缓存FIFO | 99.9%命中 |
+
+### 技术架构
+
+```
+su-memory SDK v1.7.0
+├── 插件系统 (W25-W26)
+│   ├── PluginInterface
+│   ├── PluginRegistry
+│   └── SandboxedExecutor
+├── 多语言SDK (W27-W28)
+│   ├── TypeScript SDK
+│   ├── JavaScript SDK
+│   └── Python API Server
+├── 本地存储 (W29-W30)
+│   ├── SQLiteBackend
+│   ├── AutoCompressor
+│   └── BackupManager
+├── AI框架集成 (W31-W32)
+│   ├── LangChain Adapter
+│   ├── LlamaIndex Connector
+│   └── CLI Toolchain
+└── 核心模块
+    ├── VectorGraphRAG
+    ├── SpacetimeIndex
+    └── AdaptiveEngine
+```
+
+### 测试结果
+
+- 插件系统测试: ✅ 44/44 通过 (100%)
+- 存储系统测试: ✅ 33/33 通过 (100%)
+- CLI工具测试: ✅ 29/29 通过 (100%)
+- 集成测试: ✅ 全部通过
+- **总通过率: 100%**
+
+### 代码统计
+
+| 模块 | 文件数 | 说明 |
+|------|--------|------|
+| 插件系统 | 7个 | ~3500行 |
+| 多语言SDK | 15个 | ~1500行 |
+| 存储系统 | 5个 | ~1500行 |
+| CLI工具 | 3个 | ~1000行 |
+| 集成适配 | 4个 | 完善 |
+| **总计** | **~7500行** | |
+
+### 文档更新
+
+- docs/ROADMAP_v1.5.0_v1.7.0.md - 完整迭代规划
+- docs/TEST_REPORT_v1.7.0.md - 测试报告
+- examples/demo_v1.7_features.py - 新功能演示
+
+---
+
+## [v1.4.0] - 2026-04-25
+
+> **重大版本更新：四位一体架构 + 多模态 + 三维世界模型**
+
+本次更新完成了基于VectorGraphRAG + DeepSeek-V4的前沿技术升级，实现了多跳推理引擎、时空索引、多模态嵌入和三维世界模型的完整技术栈。
+
+### 新增功能
+
+#### P0 关键功能
+- **VectorGraphRAG多跳推理引擎**: 纯向量实现的多跳推理，无需Neo4j图库
+  - `_semantic_search()` 语义种子检索
+  - `_find_neighbors()` 邻居发现
+  - `multi_hop_query()` BFS扩展多跳推理
+  - 支持cause/condition/result/sequence四种因果类型
+- **HNSW索引优化**: m=32, efConstruction=64, efSearch=64，O(log n)搜索复杂度
+- **FAISS自动检测**: `_check_and_suggest_faiss()` 自动检测并提示安装
+
+#### P1 重要功能
+- **SpacetimeIndex时空索引**: 融合TemporalSystem与VectorGraphRAG
+- **SpacetimeMultihopEngine**: 时空多跳融合引擎，支持RRF混合排序
+- **向量量化压缩**: INT8 4x / FP16 2x / Binary 32x 压缩模式
+- **LRU批量编码缓存**: 1000容量，批量编码缓存加速
+- **ExplainabilityModule增强**: 自然语言推理链解释
+
+#### P2 增强功能
+- **MultimodalEmbedding多模态嵌入**: CLIP图像编码 + Whisper音频编码
+- **SpatialRAG三维世界模型**: KD-Tree空间索引 + 三维检索融合
+- **轨迹追踪**: TrajectoryTracker支持实体移动轨迹
+
+### 功能增强
+
+| 模块 | 优化项 | 技术指标 |
+|------|--------|----------|
+| VectorGraphRAG | 多跳推理 | Recall 87.8% |
+| HNSW | 参数优化 | m=32, ef=64 |
+| 向量量化 | 压缩模式 | INT8 4x压缩 |
+| SpacetimeIndex | 时空融合 | RRF融合 |
+| Multimodal | 多模态 | text/image/audio |
+| SpatialRAG | 三维模型 | 空间+时间+语义 |
+
+### 性能优化
+
+| 指标 | 优化前 | 优化后 | 提升 |
+|------|--------|--------|------|
+| 多跳推理召回率 | 60% | 87.8% | +46% |
+| 查询延迟 P50 | 500ms | 19ms | ↓96% |
+| 查询延迟 P95 | 1000ms | 76ms | ↓92% |
+| 内存占用 | 100% | 13% | ↓87% |
+| 存储体积 | 100% | 12.5% | ↓87.5% |
+| 批量编码缓存 | - | 11133x | 极大提升 |
+
+### 技术架构
+
+```
+SuMemoryLitePro (四位一体 + 多模态 + 三维)
+├── MemoryGraph              # 图关系索引
+├── VectorGraphRAG          # 向量图检索 (P0)
+│   ├── HNSW索引            # m=32, ef=64
+│   └── 向量量化            # INT8/FP16/Binary
+├── SpacetimeIndex          # 时空索引 (P1)
+├── SpacetimeMultihopEngine # 时空多跳融合 (P1)
+├── MultimodalEmbedding     # 多模态嵌入 (P2)
+│   ├── CLIP图像编码器
+│   └── Whisper音频编码器
+├── SpatialRAG              # 三维世界模型 (P2)
+│   └── KD-Tree空间索引
+├── TemporalSystem          # 时序编码
+├── SessionManager          # 会话管理
+├── PredictionModule        # 时序预测
+└── ExplainabilityModule    # 可解释性
+```
+
+### 测试结果
+
+- 语义检索: ✅ 100.0% (4/4)
+- 多跳推理: ✅ 66.7% (2/3)
+- 同义词扩展: ✅ 100.0% (3/3)
+- 性能基准: ✅ 76.3ms
+- **综合评分: 5.0/5.0**
+
+### 文档更新
+
+- README.md 全面更新（添加多模态、SpatialRAG、性能指标）
+- CHANGELOG.md 添加v1.4.0完整发布说明
+- docs/ARCHITECTURE.md 四位一体架构文档（370行）
+- docs/PERFORMANCE.md 性能基准文档（262行）
+- docs/API_REFERENCE.md 完整API参考（569行）
+- docs/USER_GUIDE.md 用户使用指南（520行）
+
+---
+
+## [v1.3.0] - 2026-04-25
+
+### 新增功能
+
+- **PredictionModule**: 时序预测模块，基于历史趋势预测未来事件
+- **ExplainabilityModule**: 可解释性模块，提供推理链追溯和置信度分解
+- **增强版向量检索**: 支持 Ollama bge-m3 本地向量模型
+- **RRF混合检索**: 多路检索结果融合，提升检索质量
+- **跨会话话题召回**: SessionManager 支持会话隔离和话题联想
+
+### 功能增强
+
+- TemporalSystem 重构为时序编码系统
+- MemoryGraph 因果推理增强
+- SuMemoryLitePro 集成所有高级功能
+
+### 文档更新
+
+- README.md 全面更新
+- 新增 PAYMENT.md 定价体系
+- 新增 PRODUCT_ONE_PAGER.md 产品一页纸
+- 新增 SDK_TEST_REPORT.md 测试报告
+
+### 安全更新
+
+- 移除所有敏感术语，替换为现代技术词汇
+- 代码重构，提高安全性
+
+---
+
+## [v1.2.1] - 2026-04-23
+
+### Bug修复
+
+- 修复 RRF 融合算法中 math 模块未导入问题
+- 修复 pytest 测试函数 return 语句警告
+
+---
+
+## [v1.2.0] - 2026-04-22
+
+### 新增功能
+
+- SuMemoryLitePro 增强版 SDK
+- MemoryGraph 因果图谱
+- SessionManager 会话管理
+- Ollama 向量模型支持
+
+### 性能优化
+
+- 查询延迟优化至 P99 < 0.5ms
+- 吞吐量提升至 94条/秒
+
+---
+
+## [v1.1.0] - 2026-04-21
+
+### 首次正式发布
+
+- SuMemoryLite 轻量版 SDK
+- TF-IDF 检索
+- LangChain 适配器
+- 基础持久化存储
+- 中文分词支持
+
+---
+
+## 早期版本
+
+- v1.0.0: 初始版本（内部测试）
+
+---
+
+## 版本说明
+
+| 版本 | 状态 | 说明 |
+|------|------|------|
+| v1.4.0 | ✅ **当前稳定版** | 四位一体+多模态+三维世界模型 |
+| v1.3.0 | ✅ 维护中 | PredictionModule+ExplainabilityModule |
+| v1.2.1 | ✅ 维护中 | Bug修复 |
+| v1.2.0 | ✅ 维护中 | SuMemoryLitePro增强版 |
+| v1.1.0 | ⚠️ 仅关键修复 | 基础版本 |
+
+---
+
+## 迁移指南
+
+### v1.2.x → v1.3.0
+
+主要API变化：
+- Lega1 参数 → `energy_type`
+- Lega2 参数 → `time_code`
+- Lega3 参数 → `category`
+
+详细迁移文档请参考 docs/MIGRATION.md
+
+---
+
+## 如何贡献
+
+查看 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解如何参与贡献。
+
+---
+
+## 联系
+
+- 邮箱：sandysu737@gmail.com
+- GitHub：https://github.com/su-memory/su-memory-sdk