# 更新日志

所有重要的项目更新都会在此记录。

格式遵循 [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