内容
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/alluvia-lockup-dark.svg">
<img src="assets/alluvia-lockup.svg" alt="alluvia" width="420">
</picture>
</p>
<p align="center"><em>为您淘金 AI 历史记录。</em></p>
<p align="center">
<a href="https://github.com/dylanp12/alluvia/actions/workflows/ci.yml"><img src="https://github.com/dylanp12/alluvia/actions/workflows/ci.yml/badge.svg" alt="ci"></a>
<a href="https://pypi.org/project/alluvia/"><img src="https://img.shields.io/pypi/v/alluvia?color=d4a017" alt="pypi"></a>
<img src="https://img.shields.io/badge/license-MIT-d4a017" alt="MIT">
<img src="https://img.shields.io/badge/python-3.12+-d4a017" alt="python">
<img src="https://img.shields.io/badge/local--first-always-d4a017" alt="local-first">
</p>
# alluvia
您与 AI 工具的每一次对话都是沉积物。其中大部分是沙子，但其中散布着一些宝贵的想法：您从未追查的想法，您曾经解决过但忘记了的解决方案，您本想完成但未完成的线程。alluvia 就是为您提炼这些想法的工具。
您在 Claude Code 中思考问题。在 Cursor 中调试。在 ChatGPT 中探索。每个工具都与其他工具无关，您也无法记住它们。您今天需要的想法可能存在于上个月在另一个应用中的某个会话中，主题可能您根本不会搜索。alluvia 可以帮您找到它。
> *"我知道我已经思考过这个问题 — 在我正在使用的工具中重新浮现它，并附上引用，而无需将我的原始历史记录提供给另一个云服务。"* 这句话就是产品的目标。
**基于本地的首选 AI 辅助工作记忆 — 跨工具、附带出处和人为判断。** 不是另一个“AI 记忆”：您的原始会话记录不会离开您的机器，每个浮现的想法都会注明其来源，而 **您** 来决定什么是宝贵的。
alluvia 将所有内容都导入到一个本地存储库中，将其提炼成原子化的想法，将这些想法聚类成主题，然后执行其他工具无法完成的任务：**找到桥梁** — 您的过去的自己已经遇到过的问题，而您的现在的自己正在苦苦寻找的解决方案。
> **alluvia 验证门中的真实故事：** 在一个工具的安全审查中发现了一个服务器端验证漏洞。`alluvia connections` 将其链接到 **14 个月前** 在另一个工具中的调试会话 — 相同的根本原因，早已遗忘。然后，`alluvia propose` 将这个桥梁转化为一个具体的修复计划，并引用了两个来源。人类采用了这个计划。
> README 中的每个声明都源自一个记录的验证门 — 请参阅 [docs/validation](docs/validation/)。
## Sixty seconds
[](https://github.com/dylanp12/alluvia/releases/download/v0.3.0/alluvia-demo.mp4)
*(▶ 60 秒演示 — 或在 [alluvia-three.vercel.app](https://alluvia-three.vercel.app) 上观看)*
```bash
uv tool install alluvia # 或：pip install alluvia
alluvia init # 检测您的来源，设置您的 LLM 提供商
alluvia refresh # 蒸馏 → 嵌入 → 聚类 → 映射（本地嵌入）
alluvia themes && alluvia serve --open
```
无需安装的一次性试用：`uvx alluvia init`.
## 四个视角
```
$ alluvia themes # D — 您的思考，按聚类分组
• Docker 问题 [84 会话/2 来源] (2025-03→2026-06)
• 刷新令牌存储 [9 会话/2 来源]
本地存储令牌容易受到 XSS 攻击；讨论了几种方法...
$ alluvia connections # A — 跨工具和月份的桥梁
🔗 "没有跨 ID 检查导致伪造" [工具-A · 2026-06]
↔ "服务在上传时不存储 ID" [工具-B · 2025-04]
原因：相同的验证问题，两次发现，间隔 14 个月。
$ alluvia unfinished # B — 您一直循环但未完成的线程
🧵 测试基础设施重组 开启 · 4 会话，跨 388 天
$ alluvia propose # C — 基于您笔记的新下一步建议
[prop:50bda956] 添加服务器端一致性检查 （可行性 4/5）
...引用：笔记:104966a3，笔记:93de85cc
$ alluvia rate prop:50bda956 --keep
```
此外，还有一个 **每周摘要** （`alluvia digest run --if-due`），它会向您提出 ≤5 个值得注意的事项 — 当没有任何事项达到标准时，它将保持沉默。
## 查看：仪表盘
```bash
alluvia serve --open # http://localhost:8177
```
五个视图涵盖您的地图 — 库概述、按状态分组的主题气泡、**跨工具桥梁图**、每周活动时间线，显示您最长时间未完成的线程，以及您的完整判断历史记录。一个自成体系的页面，零外部请求，仅在 127.0.0.1 上提供服务。
## 在您的助手（MCP）中
```bash
claude mcp add alluvia -- uv run --directory <repo> alluvia mcp
```
八种工具允许 Claude Code / Cursor / 任何 MCP 客户端在对话过程中查询您的想法地图： *"您在四月份讨论过这个问题 — 这里是您当时确定的内容。"*
## 您的机器，可见
```bash
alluvia status # 每个路径 + 大小，存储按数据类型分组，正在运行的进程
alluvia top # alluvia 进程的实时 CPU/RAM/磁盘使用情况 + 其 LLM 流量
alluvia doctor # 诊断安装并修复可以安全修复的问题
```
并发会话设计上是安全的（WAL 存储，单写入器刷新锁），并且可以在任何时候终止任何 alluvia 进程 — 到目前为止完成的所有工作都已保存，并在下一次运行时恢复。
## 离开您的机器的内容
| 数据 | 去向 |
|---|---|
| 原始对话记录 | **不会离开。** 本地 SQLite，永远属于您 |
| 嵌入 | **不会离开。** 在本地计算（fastembed/ONNX） |
| 蒸馏/标记/建议调用 | 您配置的 LLM 提供商，在您的 API 密钥下，首先进行秘密清洗 |
| 遥测数据 | **没有。** |
提供商由您选择 — Groq、OpenAI 或 Anthropic。**整个产品在 Groq 的免费层上端到端运行** — 无需信用卡，无需云账户，在您的真实历史记录上进行真实试验，而无需离开您的机器 — 每个角色的模型可覆盖（`ALLUVIA_LLM_MODEL_PROPOSE=...` 以使用更强大的生成器，批量提取使用廉价模型）。
速率限制由您处理：每个调用都在提供商无关的控制器后面运行，带有回退、每个模型的熔断器和跨模型的自动回退（在 Groq 的免费层上，每个模型都有自己的每日预算 — 当一个模型达到上限时，alluvia 会移动到下一个模型并稍后返回）。如果某个阶段仍无法完成，`alluvia refresh` 会显示 — 按阶段计数 + 提供商重试时间 — 并完成地图的其他部分，而不是失败。待处理标签和状态会在下一次刷新时自动重试。
## 工作原理
```
来源 ─► 导入 ─► 原始数据（从未被修改） ─► 蒸馏 ─► 笔记 ─► 嵌入
│
视角 ◄── 主题/链接/状态 ◄── 聚类/链接/跟踪
│
CLI · MCP · 每周摘要 评分 ─► 评估语料库（您的）
```
三种数据类型具有不同的保证：**原始数据** （真实来源，从未被修改），**派生数据** （可从原始数据重建 — 改进管道，重新运行，无数据丢失），**判断** （您的评分和摘要 — 持久存储，永不重新生成）。
## 导入您的 ChatGPT 历史记录
ChatGPT 导入使用官方数据导出：ChatGPT → 设置 → 数据控制 → 导出数据。当 ZIP 文件通过电子邮件发送时：
```bash
alluvia ingest --source chatgpt-export --path ~/Downloads/chatgpt-export.zip
alluvia refresh
```
您的 ChatGPT 线程加入与 Claude Code 和 Cursor 相同的地图 — 这就是跨工具桥梁的来源。
## 诚实的限制
- Windsurf/Antigravity 转录本存储在无模式的 protobuf 存储中；alluvia 检测并干净地跳过它们。ChatGPT 导入使用官方数据导出（ZIP），而不是实时捕获。
- 生成的建议由防护栏（必须引用您的笔记、新颖性门控、可行性标记）保护，但它们是 LLM 输出 — 您进行评分，alluvia 进行学习。
- 所有已接受的权衡都记录在 [docs/DEBT.md](docs/DEBT.md) 中，每个权衡都有触发修复的条件。
MIT · 出于本地优先的目的而构建：该项目开始的研究发现，对于开发人员来说，此类别的信任由 **您拥有的数据** 或 **没有数据** 决定。
