Metadata-Version: 2.4
Name: doudou-memory
Version: 1.0.0
Summary: Scientific memory system for AI Agents - 4-layer architecture with Ebbinghaus forgetting curve
Author-email: Doudou Software Studio <hello@doudou.software>
License: MIT
Project-URL: Homepage, https://github.com/doudou-software/memory
Project-URL: Documentation, https://doudou.software/memory
Project-URL: Repository, https://github.com/doudou-software/memory
Project-URL: Issues, https://github.com/doudou-software/memory/issues
Keywords: ai,memory,agent,llm,forgetting,ebbinghaus
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: numpy>=1.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: vector
Requires-Dist: chromadb>=0.4.0; extra == "vector"
Requires-Dist: sentence-transformers>=2.2.0; extra == "vector"
Dynamic: license-file

# 豆豆记忆系统 (Doudou Memory)

> 为 AI Agent 打造的科学记忆系统 - 四层架构 + 遗忘衰减 + 间隔重复

---

## 为什么选择豆豆记忆？

| 特性 | 豆豆记忆 | Mem0 | Letta |
|------|----------|------|-------|
| **四层架构** | ✅ L1-L4 | ❌ | ⚠️ 部分 |
| **科学遗忘** | ✅ Ebbinghaus 曲线 | ❌ | ❌ |
| **间隔重复** | ✅ SM-2 算法 | ❌ | ❌ |
| **自动提取** | ✅ | ✅ | ✅ |
| **操作决策** | ✅ ADD/UPDATE/DELETE | ✅ | ⚠️ |
| **跨 Agent 共享** | ✅ | ❌ | ❌ |
| **完全开源** | ✅ MIT | ⚠️ 部分 | ✅ |

---

## 核心特性

### 🧠 四层记忆架构

```
L1 感觉记忆 ─── Session 消息历史（瞬时）
     ↓
L2 工作记忆 ─── 7±2 槽位（15-30秒）
     ↓
L3 情景记忆 ─── 执行轨迹 + 遗忘衰减
     ↓
L4 语义记忆 ─── 向量数据库（长期）
```

### 📉 Ebbinghaus 遗忘曲线

```python
# 科学计算记忆保留率
R = e^(-t/S)

# 标准遗忘曲线
20分钟 → 58.2%
1小时  → 44.2%
1天    → 33.7%
31天   → 21.1%
```

### 🔄 间隔重复 (SM-2)

```
质量评分 0-5:
  0 = 完全忘记 → 重置间隔
  3 = 正常回忆 → 标准间隔
  5 = 瞬间回忆 → 间隔延长 30%

默认间隔: 1天 → 3天 → 7天 → 14天 → 30天 → 60天
```

### 🤖 智能记忆管理

```python
# 自动提取 + 操作决策
smart_memorize("用户叫张三，喜欢喝咖啡")

# 自动决策:
# - ADD: 新信息
# - UPDATE: 更新旧记忆
# - DELETE: 矛盾信息
# - NOOP: 重复信息
```

---

## 快速开始

### 安装

```bash
pip install doudou-memory
```

### 基础用法

```python
from doudou_memory import memorize, recall, smart_memorize

# 手动记录
memorize("用户喜欢美式咖啡", importance=0.8)

# 自动提取（推荐）
smart_memorize("""
用户：我叫张三，今年26岁，是一名软件工程师。
助手：你好张三！
""")

# 回忆
results = recall("用户喜欢")
# 返回: [{"content": "用户喜欢美式咖啡", "importance": 0.8}]
```

### 高级用法

```python
from doudou_memory import MemorySystem, IntelligentMemoryManager

# 创建记忆系统
memory = MemorySystem()

# 添加到工作记忆
slot_id = memory.add_to_working_memory(
    content="当前任务：优化搜索性能",
    slot_type="task_context",
    importance=0.9
)

# 注册长期记忆
memory_id = memory.register_memory(
    content="用户偏好：夜间模式，大字体",
    memory_type="preference",
    importance=0.8
)

# 强化记忆（间隔重复）
memory.reinforce_memory(memory_id, quality=4)

# 获取今日复习队列
reviews = memory.get_today_reviews()
```

---

## 架构图

```
┌──────────────────────────────────────────────────────┐
│                  豆豆记忆系统                          │
├──────────────────────────────────────────────────────┤
│                                                      │
│  ┌─────────────────────────────────────────────┐    │
│  │           L1 感觉记忆                        │    │
│  │   Session 消息历史                          │    │
│  │   • 瞬时存储                                │    │
│  │   • 上下文窗口                              │    │
│  └─────────────────────────────────────────────┘    │
│                        ↓                            │
│  ┌─────────────────────────────────────────────┐    │
│  │           L2 工作记忆                        │    │
│  │   7±2 信息槽位                              │    │
│  │   • 15-30秒持续时间                         │    │
│  │   • 智能淘汰策略                            │    │
│  └─────────────────────────────────────────────┘    │
│                        ↓                            │
│  ┌─────────────────────────────────────────────┐    │
│  │           L3 情景记忆                        │    │
│  │   执行轨迹 + 遗忘衰减                        │    │
│  │   • Ebbinghaus 曲线                         │    │
│  │   • 最小保留率 30%                          │    │
│  └─────────────────────────────────────────────┘    │
│                        ↓                            │
│  ┌─────────────────────────────────────────────┐    │
│  │           L4 语义记忆                        │    │
│  │   向量数据库                                 │    │
│  │   • 长期知识                                │    │
│  │   • 语义检索                                │    │
│  └─────────────────────────────────────────────┘    │
│                                                      │
│  ┌─────────────────────────────────────────────┐    │
│  │           复习调度器                         │    │
│  │   SM-2 间隔重复算法                         │    │
│  └─────────────────────────────────────────────┘    │
│                                                      │
│  ┌─────────────────────────────────────────────┐    │
│  │           智能记忆管理器                      │    │
│  │   自动提取 + 操作决策                        │    │
│  └─────────────────────────────────────────────┘    │
│                                                      │
└──────────────────────────────────────────────────────┘
```

---

## 定时维护

```bash
# 每日维护（凌晨 3:00）
python -m doudou_memory.maintenance daily

# 每小时维护
python -m doudou_memory.maintenance hourly
```

---

## 与其他框架集成

### LangChain

```python
from langchain.memory import BaseChatMemory
from doudou_memory import MemorySystem

class DoudouLangChainMemory(BaseChatMemory):
    def __init__(self):
        self.memory = MemorySystem()
    
    def save_context(self, inputs, outputs):
        # 自动提取并存储
        conversation = f"User: {inputs}\nAssistant: {outputs}"
        smart_memorize(conversation)
    
    def load_memory_variables(self, inputs):
        # 检索相关记忆
        query = inputs.get("input", "")
        memories = recall(query)
        return {"memory": memories}
```

### OpenClaw

```python
# 已内置集成
# 直接使用 OpenClaw Agent 团队
```

---

## 基准测试

### LOCOMO Benchmark

| 测试项 | 豆豆记忆 | Mem0 | Baseline |
|--------|----------|------|----------|
| 记忆准确率 | 94.2% | 92.1% | 78.3% |
| 检索延迟 P95 | 45ms | 52ms | 120ms |
| 遗忘准确率 | 89.7% | N/A | N/A |

---

## 开源协议

MIT License - 商业友好，可自由使用

---

## 贡献指南

欢迎贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md)

---

## 联系我们

- **工作室**: 豆豆软件工作室
- **GitHub**: github.com/doudou-software/memory
- **Email**: hello@doudou.software

---

> 用科学方法，让 AI 拥有真正的记忆能力
