LucieEveille/kiwi-mem

🥝 kiwi‑mem – AI 作为大脑

是什么

• 一个位于聊天客户端与大语言模型（LLM）API（OpenAI 兼容或 Anthropic 原生）之间的自托管网关。它在每次请求中注入 类人 的长期记忆，并从模型的回复中提取新的记忆片段。

核心理念

• 记忆热度 – 每个存储的事实都有一个“温度”。它会随时间冷却，当对话重新提及它时会升温，若很少被提及则冷却得更快。热度高的记忆会完整注入，温热的以摘要形式注入，冷的则被忽略。
• 梦境（睡眠）周期 – 每晚运行的流程，清理过时的碎片，将相关片段合并为 记忆场景，并运行小型推理步骤以推断未明说的事实。结果以高层级记忆形式存回。
• 日历压缩 – 聊天记录会自动汇总为分层摘要（日 → 周 → 月 → 季度 → 年），使旧时期仅占用少量 token。
• 冲突解决与锁定 – 当新事实与旧事实矛盾时，旧条目将被废弃。用户可锁定重要记忆，使其永不衰减。
• 节省 token 的提示布局 – 静态数据（角色设定、锁定记忆、日历）置于缓存前缀中，动态数据（搜索结果、睡眠提示）随后，可减少高达 ~90% 的输入 token 成本。

如何工作

1. 你的聊天客户端向 https://your‑domain/v1/chat/completions 发送请求（kiwi‑mem 网关）。
2. 网关使用混合 RRF 搜索（向量 + 关键词）查找相关记忆，并根据其热度水平将其前置到提示中。
3. 请求被转发至配置的 LLM 提供商。
4. LLM 的回复返回给客户端 并 被解析以提取新的记忆片段，这些片段以初始热度存储。
5. 定期（或按需）运行 Dream 任务以整合与推断。

主要功能

功能	作用
基于热度的衰减与强化	记忆自动衰减；重复提及可重新加热。
梦境睡眠集成	三阶段清理、合并与前瞻推理。
分层日历	日 → 周 → 月 → 季度 → 年的摘要，注入时细节递减。
冲突处理	新的矛盾事实会停用旧条目；锁定的记忆永久保留。
工具抽屉	20 多个内置工具（搜索、提醒、网页搜索等）仅在系统预测需要时加载，节省 token。
多提供方支持	支持任何 OpenAI 兼容端点 和 Anthropic 原生 API，无需额外转换。
项目隔离	全局记忆共享，但每个“项目”可拥有私有指令、文件和对话历史，永不泄露给其他项目。
Web 管理面板	配置提供方、查看/编辑记忆、运行 Dream、管理项目、导出/导入备份。
Docker 优先部署	docker compose up -d 一键启动完整栈（FastAPI 网关 + PostgreSQL + pgvector）。

技术栈

• Python + FastAPI – HTTP 网关与记忆逻辑。
• PostgreSQL + pgvector – 存储记忆、嵌入向量与热度值。
• Docker / Docker‑Compose – 一键部署，可在 VPS、云虚拟机或 Zeabur 等平台间轻松迁移。
• AGPL‑3.0‑or‑later – 确保任何托管修改版本均保持开源。

适合谁

• 需要记住你的习惯、偏好、健康数据等的个人 AI 助手。
• 长期聊天伙伴（情感支持、角色扮演、讲故事）。
• 需要在多次会话中保留世界观细节的创意伙伴。
• 跟踪你进度与薄弱点的学习导师。

快速入门

# 在新服务器上
curl -fsSL https://get.docker.com | sh
git clone https://github.com/LucieEveille/kiwi-mem.git
cd kiwi-mem
cp .env.example .env   # 仅当你想预填充 API_KEY 时才编辑
docker compose up -d

• 用 curl http://localhost:8080 验证 → "status":"running"。
• 打开 https://your‑domain/admin（默认无密码）添加 LLM 提供方，测试连接，并通过支持 OpenAI 风格 API 的任意客户端开始聊天。

更新方法

• 运行 bash scripts/update.sh – 自动备份数据库，拉取最新代码，重建容器，若新版本无法启动则自动回滚。
• 可选安装 cron（--install‑cron）实现每日自动更新。

限制

• 专为 个人记忆 设计，不适用于企业文档搜索或知识图谱场景。
• 网关本身无认证；若公开暴露，必须保护端点（如 Cloudflare Access、基本认证、IP 白名单）。

许可证

• AGPL‑3.0‑or‑later – 可使用、修改、分发，但若通过网络提供服务，必须向用户公开源码（含你的修改）。

---

kiwi‑mem 致力于打造一个真正“记住你”的 AI，其遗忘与整合机制模仿人类记忆。