afair

<p align="center"> <img src="assets/logo/afair-elephant.png" alt="afair" width="160" /> </p> <h1 align="center">afair</h1> <p align="center"> <em>你的记忆贯穿你使用的所有人工智能。</em> </p> <p align="center"> <a href="https://github.com/afairai/afair/actions/workflows/ci.yml"><img src="https://github.com/afairai/afair/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL_v3-blue.svg" alt="License: AGPL v3" /></a> <a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg" alt="Python 3.12+" /></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Model_Context_Protocol-7c3aed.svg" alt="MCP" /></a> <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/lint-ruff-261230.svg" alt="Ruff" /></a> </p> --- 你使用多个人工智能，每个人工智能都单独记住你。在一个工具中建立的信息在下一个工具中并不存在，因此你需要反复解释自己的决定、生活中的人、偏好和历史，这些信息你已经厌倦在每次会话开始时重复。 afair 是一个所有人工智能共享的记忆。它作为你的私人保险库运行，通过 [模型上下文协议](https://modelcontextprotocol.io)（MCP）与每个工具连接，这样相同的记忆可以从 Claude 到你的编码代理再到你选择的下一个工具中延续。一个人工智能层为你维护结构化的记忆，因此你无需管理和维护任何信息。你可以查看它学到的关于你的信息，并在有误时进行纠正。 你可以存储整个生活中的信息：工作、你爱的人和你希望人工智能知道的个人信息。 数据是只追加的，并且归你所有。afair 是开源的，单租户的，你可以随时导出所有数据。名字的由来是为了减少不必要的顾虑。 ## 使用方式 **自行运行。** 该仓库包含完整的内容，遵循 AGPLv3 许可协议。你可以在自己的机器或服务器上自行托管，终身免费。快速入门指南见下。 **或让 afair.ai 为你运行。** 托管服务即将推出，届时将提供独立的 EU 实例、备份、导出和更新服务。你可以加入早期访问列表，网址为 **[afair.ai](https://afair.ai)**。 无论哪种方式，代码都是相同的。托管产品是此仓库的一个部署版本，而不是一个单独的专有分支。 ## 三个命令 afair 暴露了三个工具，并且它们是固定的： - **`remember`** 存储持久的信息：决策、重要人物、约会或偏好。 - **`recall`** 调用与当前情境相关的信息。 - **`observe`** 记录人工智能刚刚执行的操作，以便保险库保持更新。 一旦你将简短的 [设置代码片段](docs/clients/_snippet.md)交给人工智能，它就会自动调用这些命令。没有调用不会将信息放入保险库中。 ## 自行运行 需要 Python 3.12+ 和 [uv](https://docs.astral.sh/uv/)。 ```bash uv sync cp .env.example .env # 添加 ANTHROPIC_API_KEY，或其他提供商的密钥（模型由您选择） uv run python -m afair ``` 服务器启动后，地址为 `http://127.0.0.1:8765`。指向一个 CLI 或桌面客户端（Claude Code、Codex、Cursor），连接后即可使用。云端运行的 Web 客户端（Claude.ai、ChatGPT）则需要公共 HTTPS 部署和快速 OAuth 设置，详见 [docs/self-hosting.md](docs/self-hosting.md)。每个环境变量都在 `.env.example` 中有文档；每个客户端的连接指南位于 [docs/clients](docs/clients)。 ## 使用编码代理安装 已经在 Claude Code、Codex 或其他编码代理中？将以下提示交给它，它将自行设置：克隆、依赖项、配置和 MCP 连接，然后验证往返过程。 > 在此机器上设置 afair（开源 MCP 记忆服务器，地址为 https://github.com/afairai/afair），并连接到此工具。克隆它，运行 `uv sync`，复制 `.env.example` 到 `.env`，并向我询问 LLM 提供商的 API 密钥。然后运行 `uv run python scripts/install_clients.py` 以连接我的 MCP 客户端并添加 afair 指令代码段。告诉我启动服务器的命令（`uv run python -m afair`）以及如何保持它运行。一旦启动，记得一个测试事实并回忆它以证明它有效。遵循 `docs/self-hosting.md` 和 `docs/clients/`；仅在 `.env` 中放置我的 API 密钥，不要放在其他地方。 该命令在本地运行，默认情况下为 CLI 和桌面客户端提供服务。要访问 Web 客户端（Claude.ai、ChatGPT），请遵循 [docs/self-hosting.md](docs/self-hosting.md) 中的公共部署说明。 ## 教你的 AI 使用它 连接服务器是其中一半；另一半是让你的 AI 自动使用这些工具。将简短的 [指令代码段](docs/clients/_snippet.md) 粘贴到客户端的持久指令中（CLAUDE.md、AGENTS.md、自定义指令或 `.cursorrules`），它将在对话开始时回忆上下文，记住持久信息，并观察其操作，无需你每次都提示。相同的代码段适用于每个客户端。对于 Claude Code、Codex 和 Cursor，`scripts/install_clients.py` 会为你编写连接配置和代码段。 ## 支持的工具 Claude Code、Claude.ai、ChatGPT、Codex CLI、Cursor、Windsurf、Copilot 以及其他通过 Streamable HTTP 支持 MCP 的工具。 ## 架构 四层，一致性来源： - **基础层。** 追加式 SQLite，支持 FTS5 和 sqlite-vec，内容寻址存储。日志永远不会被重写。 - **解释层。** 在基础层上构建的版本化视图。可以重新生成视图而不需修改任何存储的事件。 - **MCP 接口层。** 版本化和增量式。已发布的签名将继续有效。 - **代理层。** 后台工作器，负责提取、链接实体和合成，所有操作都读取相同的基础层。 完整的设计和八个不变式位于 [VISION.md](VISION.md)。如果您想了解原因，可以从那里开始。 ## 文档 | 文档 | 内容 | |---|---| | [VISION.md](VISION.md) | 完整设计和八个不变式。从这里开始了解原因。 | | [docs/self-hosting.md](docs/self-hosting.md) | 运行您自己的保险库：本地、Docker 或公共部署，CLI 与 Web 客户端和 OAuth 设置。 | | [docs/clients](docs/clients) | 每个客户端的连接指南（Claude Code、Codex、Cursor、Claude.ai、ChatGPT、Perplexity）和通用的指令代码段。 | | [CONTRIBUTING.md](CONTRIBUTING.md) | 开发设置、四个检查和变更不能破坏的不变式。 | | [SECURITY.md](SECURITY.md) | 如何报告漏洞以及针对 afair 的安全模型。 | | [docs/adr](docs/adr) | 架构决策记录：不变式的原因、实体图为何是信念层。 | | [CHANGELOG.md](CHANGELOG.md) | 版本发布历史。 | ## 贡献 欢迎拉取请求。请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，了解设置、检查和变更不能破坏的不变式。发现安全问题？请参见 [SECURITY.md](SECURITY.md)，并请私下报告。 ## 许可证 afair 在 GNU Affero 通用公共许可证 v3.0 下发布（[LICENSE](LICENSE)。您可以自行托管、 fork 和修改，免费。如果您为他人运行修改后的版本作为网络服务，您需要在相同许可证下发布您的更改。在 [afair.ai](https://afair.ai) 上的托管服务是此代码的部署版本，而不是一个单独的专有分支。 一句话：免费使用、免费托管、与他人共享时需回馈。 ## 源自德国 在德国构建。托管实例在欧盟运行，遵循欧盟法律。