内容
<div align="center">
# 🌿 FERNme
### 模糊边缘回忆网络
**一种用户拥有、近乎零LLM内存层的AI代理。它通过每个人的行为（包括他们的谈话方式和情感）来学习——保持 token 平坦，并让用户查看、编辑和拥有被记住的内容。引擎是独立于底层技术的：它在今天的网站（购物、支持、预订、医疗保健、辅导、政府）、桌面和移动设备上记住代理的行为。**
[](LICENSE)
[](https://fernme.dev)
[](https://www.python.org/)
[](#-tested-not-claimed)
[](#-architecture)
[](#-honest-status)
*便宜写作 · 读取平面 · 设计可解释 · 用户拥有*
[**fernme.dev**](https://fernme.dev)
</div>
---
## ✨ 项目简介
大多数代理内存都是**由LLM在每次对话中写入**（昂贵，易产生幻觉），**评估基于问答**（不是行为），并且**假设单个用户**。FERNme是为相反的世界而构建的——为**许多**人、任何领域（销售、预订、解决的票据、完成的课程、预约的约会——“结果”就是目标）**行动**的代理。它从代理已经行动的网站开始——今天的网站——相同的用户拥有内存设计扩展到桌面和移动设备。每个用户都是一个稀疏的、模糊加权的节点在一个每站图;边通过**赫布学习规则与零LLM调用**更新，检索是**扩散激活**，而面向提示的“卡片”仅存储**与人口先验的偏差**。结果：每轮成本保持扁平，因为配置文件随着多年的增长而增长，用户可以读取和纠正自己的内存，并且相同的引擎在用户的同意下组装成一个跨站点的**超级节点**，用户完全控制。
---
## 🎯 为什么选择FERNme（优势）
| | |
|---|---|
| 🪶 **零LLM写入** | 内存更新是图的算术运算——**每交互0个LLM调用** vs. 提取式内存的~2个。无写入成本，无写入幻觉。 |
| 📉 **永久扁平令牌成本** | 提示卡始终保持**~25个令牌**，无论是访问者的第一天还是第五年。一个完整的历史基线在120次交互后**大77倍**。 |
| 🧠 **在每个领域都表现强大** | 与静态回忆的频率计数器绑定，**在漂移上击败它0.72→0.13**，并在**上下文**上获胜（0.62→0.51）。衰减+扩散激活统一稳定性和适应性。 |
| 🪟 **玻璃盒和用户拥有** | 每个偏好都可见和可编辑。人们可以修复错误的东西，删除所有内容，或导出它。隐私成为一个功能，而不是负债。 |
| 🏬 **为结果而构建** | 通过**转化**评估，而不是问答。一个模拟的商店前端显示**+16％的转化率提升**，相比非个性化推荐。 |
| 🧩 **用户拥有的超级节点** | 跨站点登录→您的记忆像乐高一样组装成一个配置文件**您控制**，默认拒绝，敏感数据隔离。不是监控——它的镜像。 |
| 🎚 **成本/质量拨号** | 一个引擎，一个`memory_mode`开关：免费无密钥`pure`默认，付费`gated`/`offline`LLM增强时您需要Mem0级细微差别——仅为使用的计算付费。 |
| 🔐 **可验证和无法学习** | 每个操作都记录在用户的**可回放的HMAC链**中，以检测任何更改；`forget_everywhere`擦除配置文件**和**从人群先验中抹去个人——可证明的被遗忘权。 |
| 🛡 **设计上防止注入** | 写入是算术运算，而不是LLM提取，因此页面/用户文本不能被“谈论”成信仰——测试注入指令从未进入内存。 |
| 🧠 **私人集体智能** | 新用户从**人群模式**中受益（冷启动），具有**k匿名性和差分隐私**，因此没有个人数据泄露。一个网络效应的护城河，单一用户内存无法拥有。 |
| 🗣 **风格和情绪记忆** | 学习**每个人如何交流**（简洁/冗长，正式/随意，能量）和**跟踪他们的情绪**，以便代理可以匹配语气并注意到某人的沮丧正在上升——在任何领域。 |
| 🎯 **结果学习，任何目标** | 内存通过**结果**加强——不仅仅是回忆。`record_outcome（success）`加强有效的方法并削弱失败的方法，其中“成功”是任何目标（购买，预订，解决的票据，完成的课程...）。 |
| 🔍 **可解释** | 询问`why（user，attr）`——获取证据（观察+好/坏结果+日期）。没有黑盒。 |
| 🔌 **可部署的管道** （研究预览;根据SECURITY.md加强）| SQLite或**Postgres**（在真正的PG 16上测试），REST + **MCP**服务器，同意门控，防注入写入，主动触发器——所有测试。 |
---
## 📊 基准测试
> **诚实范围：** 以下数字基于**合成或LLM作者**的数据，而不是真正的用户。它们验证了**机制**并浮现故障；真正的用户试点是下一个待完成的步骤。
### 在LLM作者的人（最接近真实，代理摄入）
十六个92个第三人称配置文件样本（ChatGPT作者），作为**仅散文**读取并代理记住，然后针对隐藏的答案键进行评分：
| 指标 | 结果 |
|---|---|
| 与隐藏键相比的偏好覆盖率 | **75%** |
| 沟通风格——正式性 | **100%** |
| 情绪符号/情绪弧线 | **94%/100%** |
| 检测到的偏好漂移 | **94%** |
| 注入尝试被忽略 | **100%** |
| 笔记→卡片压缩 | **7.3倍** |
*(这里的“代理”是阅读散文的LLM，因此这些反映代理+引擎一起——引擎是可靠的;提取质量是代理的。)*
---
## 🎚 内存模式（一款引擎，一个成本/质量拨号开关）
FERNme配备了一个**核心**，并具有部署级别的开关——`FernService（memory_mode = ...）`。默认是免费、无密钥、经过测试的；LLM模式是可选的，并且是可插拔的。
| 模式 | LLM使用 | 成本 | 状态 |
|---|---|---|---|
| **`pure`**（默认） | 无 | 最便宜，平坦 | ✅ 已测试，无密钥 |
| **`gated`** | 仅在新型自由文本上进行一次小调用 | ~微小 | 🧪 实验中——需要模型 |
| **`offline`** | 批处理`consolidate()`丰富，不在热路径上 | ~微小，摊销 | 🧪 实验中——需要模型 |
- 一个**可插拔的标签器**（`tagging.py`）执行LLM工作;您可以传递`llm_fn`，可选地约束为**受控词汇**（跨模型的实际一致性杠杆）。
- 热写入路径在**每种模式下保持无LLM**; gated仅在确定性映射找不到时花费一次调用，并且`svc.llm_calls`计算每次调用以实现成本透明度。
- 有关每个模式的位置，请参见上面的成本/质量帕累托。 *诚实说明：* gated/offline质量是**建模**的，直到针对真实模型运行——测试中使用模拟LLM，未验证质量。
---
## 快速开始
```bash
pip install -e ".[dev,api]"
python run_demo.py # 冷启动 → 学习 → 玻璃盒编辑
python supernode_demo.py # 一个人，三个站点，一个拥有的配置文件
pytest -q # 88个测试（引擎，存储，超级节点，安全，身份验证...)
# 实验
python -m fernme.eval.drift # FERNme在品味改变时优于频率计数器
python -m fernme.eval.pilot # +16% 模拟转化率提升
# 现场运行
FERNME_API_KEY=secret uvicorn fernme.api.rest:app --port 8077 # REST API（/docs）
open http://localhost:8077/ui # 玻璃盒内存编辑器
open http://localhost:8077/graph # 您的内存作为图表 — 按站点/PC/手机聚焦
python -m fernme.api.mcp_server # 代理/Claude的MCP服务器
```
> 🗄 **存储：** 默认存储在`~/.fernme/fernme.db`（SQLite）。在生产环境中使用`PostgresStore` — 同一接口，已在真正的Postgres 16上测试。 将SQLite存储在云同步的文件夹之外。
---
## 布局
```
fernme/
core/ 图类型 · 模糊0-9边 · 事件记录
write/ 事件→属性映射（无LLM）· 赫布更新 · 衰减
retrieve/ 基础级别 + 扩散激活 · 标记最小卡
prior/ 人口先验 · 差分编码 · IDF冷启动
store/ sqlite_store · postgres_store（一接口）
supernode.py · auth.py · triggers.py · safety.py · service.py
api/ rest.py（FastAPI）· mcp_server.py · web/glassbox.html · web/graph.html
eval/ 模拟器 · 成本 · 质量 · 漂移 · 上下文 · 消融 · 试点
tests/ 88个测试 · *_demo.py演练
```
