# human-memory · 类人脑记忆

给 AI 装一套像人脑的记忆：**重要的记牢，日常的会淡，被提起才想起，可以手动抢救。**

零第三方依赖、纯本地、单文件 SQLite。

> **第一次用？看 [TUTORIAL.md](TUTORIAL.md)**（5 分钟上手 + 场景化用法 + 常见问题）。

> 现在的 AI 记忆要么全量塞上下文（很快撑爆），要么粗暴摘要（压缩后没有主次）。这个项目试着按人脑的方式处理：不同的记忆有不同的权重和寿命，遗忘不是删除，是沉下去。

---

## 它和现有方案的区别

| | mem0 | MemoryOS | 本项目 |
|---|---|---|---|
| 记忆分主次 | 部分（有层级、无权重） | ✅ | ✅ 11 种类型 + 七因子权重 |
| 会遗忘 | ❌ ADD-only，只增不减 | 部分（只升温） | ✅ 按类型分半衰期 |
| 遗忘后可唤醒 | — | — | ✅ 休眠记忆被线索命中自动唤醒 |
| 手动抢救 | ❌ | ❌ | ✅ 钉住 / 手动唤醒 |
| 情绪建模 | — | — | ✅ 效价 × 唤醒度两维 |
| 时间维度 | — | — | ✅ 余波期 / 心结 / 连续低迷 |

## 核心机制

1. **记忆分主次**：写入时按七因子打分（自我参照、情绪冲击、社会关系、身份目标、状态持续、新奇、细节），偏好类 0.81 分，日常待办 0.35 分。
2. **分类型衰减**：心结近乎不衰减（36500 天）、身份十年、偏好一年、事件十天。情绪冲击强的翻倍。
3. **休眠不删除**：`active` / `dormant` 状态，沉下去但内容还在，被线索命中会自动唤醒。
4. **情绪两维**：效价（-1~1）× 唤醒度（0~1），记忆强度看 `|效价| × 唤醒度`——暴怒和狂喜都记得牢，“有点烦”和“还行”都不留痕。
5. **时间维度**：高冲击事件有余波期（3~11 天）；赌气、冷战记为“心结”，靠时间 + 多次表达 + 状态转正多路证据才消退，一句话不够。

## 快速开始

需要 Python 3.10+，不需要装任何包。

```powershell
git clone https://github.com/zyj52742-cloud/human-memory.git
cd human-memory

# 记一句话
python memcli.py add "我讨厌香菜，闻到就想吐"

# 换一天再问
python memcli.py recall "我讨厌什么"

# 看情绪轨迹
python memcli.py mood
```

跑测试：

```powershell
python selftest.py       # 75 项断言
python mcp_test.py       # MCP 协议 9 项
python bench.py          # 1 万条记忆性能
```

## 三种用法

### 1. 命令行（最简单）

```powershell
python memcli.py add "用户原话"
python memcli.py recall "当前话题"
python memcli.py mood
python memcli.py list
python memcli.py explain 3      # 看第 3 条为什么是这个分
```

### 2. 作为 AI skill（推荐，零配置）

把仓库里的 `skills/memory/` 复制到你的 AI 技能目录（例如 `~/.dsh/skills/memory/`），AI 读到 `SKILL.md` 后会自己决定何时记忆、何时召回。

数据独立存在 `~/.human-memory/memory.db`，skill 升级不会丢记忆。

### 3. 作为 MCP 服务（给 Claude Desktop / Cursor 等）

```json
{
  "mcpServers": {
    "human-memory": {
      "command": "python",
      "args": ["<绝对路径>/mcp_server.py"]
    }
  }
}
```

提供 14 个工具：remember / recall / list / pin / sleep / wake / stats / alias / explain / mood / update / delete / resolve / export。

## 评分体系

### 重要度（写入时算一次）

```
0.25 基础
+0.28 自我参照（关于"我"）
+0.30 情绪冲击（|效价| × 唤醒度）
+0.12 社会关系（家人、伴侣）
+0.10 身份目标
+0.10 状态持续（疲惫、低落）
+0.08 新奇意外
+0.05 细节丰富
```

### 召回（每轮实时）

```
0.45×相关性 + 0.25×重要度 + 0.12×时近性 + 0.10×权重 + 0.08×情绪冲击
休眠 ×0.35；钉住 +0.25；相关性 < 0.10 且没钉住 → 丢弃
```

## 实测

- 1 万条记忆：召回 **10–45 ms**，写入 12 ms/条，库约 20 MB
- 四轮对话注入约 39 tokens，全量注入需 144，**省 73%**
- 自动化测试 75 项 + MCP 协议 9 项

## 已知限制（诚实说明）

1. **抽取是规则版**：靠约 95 个情绪词 + 规则，识别不了“说不上来哪里不对”这类隐性表达。
2. **本地小模型不可用（实测）**：在 RTX 4060 8 GB 显存 + 16 GB 内存的机器上，qwen2.5 的 1.5B 能跑但会照抄示例，3B/7B 输出退化成一串重复数字。大显存机器可能不同。
3. **可接外部 API**：`extractor.py` 支持任何 OpenAI 兼容接口，配三个环境变量即可；失败自动回退规则版，不会丢记忆。
4. **权重是先验值**：七因子权重有心理学依据的排序，但具体数字没拿大规模真实对话调过。`tune.py` 可以做自动调参。
5. **中文按 2-gram 切词**：单字情绪词（累/怕/烦）已特殊处理，但跨词表达仍可能漏召回。
6. **不做复杂的记忆冲突仲裁**：只做“同对象 + 态度反转 → 旧的标记为被取代”，不做时效推理。

## 文件

```
├── scoring.py          评判标准：情绪词典、七因子、类型、衰减、心结
├── memory_core.py      引擎：存储、状态机、召回、情绪分析、迁移、导入导出
├── extractor.py        抽取层：规则版 / 模型版（可切换、失败自动回退）
├── memcli.py           命令行入口
├── mcp_server.py       MCP 服务（14 工具）
├── chat_play.py        交互式体验
├── skills/memory/      可直接安装的 AI skill
├── selftest.py         75 项断言
├── mcp_test.py         MCP 协议验收
├── bench.py            1 万条性能测试
├── tune.py             召回参数自动调优
├── ARCHITECTURE.md     架构说明
└── data/               记忆库（已 gitignore）
```

## 许可

MIT