README.md

---
language:
  - zh
  - en
tags:
  - preference-learning
  - qlora
  - agent
  - personalization
  - peft
  - association-engine
pipeline_tag: text-generation
base_model: Qwen/Qwen2.5-7B-Instruct
---

# Hermes — 联想引擎 / Association Engine

为任意 AI agent 提供基于 **QLoRA 微调**的隐式偏好学习能力。

Agent 推理时主动检索用户历史偏好并默认应用，减少重复沟通成本，同时作为多 agent 协作的共享偏好池。

## 核心机制

| 机制 | 说明 |
|------|------|
| **联想 (Association)** | 不等用户开口，主动检索历史偏好 → 注入推理上下文 |
| **动态语义聚类** | 偏好自动聚合为生活切面（scope），不预设类型和数量 |
| **QLoRA 微调** | 闲时低资源训练，每个 scope 独立 LoRA 权重 |
| **维度递增约束** | 同 scope 内偏好描述精度必须递增，防止信息退化 |

## 架构

```
Agent → CLI / Python SDK → Hermes Daemon (SQLite + QLoRA 训练沙箱)
```

## 快速开始

```bash
pip install -e .
hermes init          # 一键初始化（下载模型、验证环境）
hermes demo          # 交互演示
hermes start         # 后台启动 daemon
```

### Python SDK

```python
from hermes_core import HermesClient

client = HermesClient(user_id="u_alex", agent_id="my-agent")

# 推理前查询偏好
prefs = client.query("帮我写个用户登录接口")

# Agent 自主记录偏好
client.record("后端开发", [
    {"key": "language", "value": "TypeScript", "context": "默认语言"},
    {"key": "framework", "value": "Express", "context": "默认框架"},
])
```

### CLI

```bash
# 记录偏好
hermes record --user u_alex --scope-desc "后端开发" \
  --dimensions '[{"key":"language","value":"TypeScript"}]'

# 查询偏好
hermes query --user u_alex --text "帮我写个API"

# 查看状态
hermes status
```

## 训练 LoRA 权重

每个 scope 独立训练 LoRA 适配器，基于 `Qwen/Qwen2.5-7B-Instruct`：

```bash
# 手动触发训练
hermes train --user u_alex --scope <scope_id>

# 或让 daemon 闲时自动训练
hermes start
```

训练完成后，LoRA 权重保存在 `~/.hermes/data/users/{user_id}/checkpoints/{scope_id}/v{version}/`。

## 项目结构

```
hermes/
├── hermes_core/    # 核心逻辑（Python SDK）
├── cli/            # Click 命令行壳
├── daemon/         # 后台训练守护进程
├── tests/          # 40 个单元测试全部通过
└── pyproject.toml
```