内容
<div align="center">
# 法拉第内存
### 为编码代理提供持久、跨会话的内存 - 顶部带有编排层。
您的编码代理每次会话都会忘记所有内容。法拉第内存为您已经运行的代理（如 **Claude Code · Codex · Gemini**）提供了一个 *持久* 的内存：
项目知识在会话之间持续存在，在工具之间共享，并按仓库分区。
<br />
[](https://github.com/faradium/faradium/actions/workflows/ci.yml)
[](LICENSE)
[](https://github.com/faradium/faradium/stargazers)
[](https://github.com/faradium/faradium/issues)
[](https://www.python.org/)
[](https://fastapi.tiangolo.com/)
[](https://react.dev/)
[](https://docs.astral.sh/uv/)
<br />
[**快速开始**](#快速开始) ·
[**工作原理**](#工作原理) ·
[**仓库布局**](#仓库布局) ·
[**自托管**](#自托管) ·
[**编排层**](#编排层) ·
[**贡献**](#贡献)
</div>
<p align="center">
<img src="docs/screen.png" alt="法拉第内存仪表盘" width="820" />
</p>
---
## 快速开始
法拉第内存有三种规模 - 选择适合您需求的最小规模：
| 模式 | 命令 | 您将获得的内容 |
| --- | --- | --- |
| **本地优先内存** | `python quickstart.py` | SQLite 内存连接到您的代理 CLI。无需 Postgres，无需 Docker。 |
| **全栈（Docker）** | `docker compose up --build` | 后端 + 网页仪表盘 + Postgres，以及编排层。 |
| **团队自托管** | `faradium deploy` → `enroll` → `connect` | 您自己的主机上的共享后端；队友无需管理员令牌即可加入。 |
### 本地优先内存（克隆并运行）
无需 Postgres，无需云账户，无需 PyPI - 只需克隆并运行一个命令。它启动一个本地内存后端（SQLite）并将其连接到您的代理 CLI：
```bash
git clone https://github.com/faradium/faradium && cd faradium
python quickstart.py # --agent claude （默认）| codex | gemini | all
```
**它做了什么：**
1. 从此克隆安装 `faradium` CLI（`faradium-memory` 包）（通过 `uv`），
2. 在 **内存模式** 下启动内存后端（使用 SQLite）（`services/backend`，无 Postgres），
3. 生成一个账户 API 密钥并将 `faradium serve` 注册到您的代理 CLI（在每个仓库中都有效；服务器按仓库分区内存），
4. 让后端保持运行 - 保持该终端打开并在其他地方使用您的代理。
> **要求：** Python 3.11+ 和 [`uv`](https://docs.astral.sh/uv/)。嵌入式内存是可选的 - 设置 `OPENAI_API_KEY` 以进行语义召回；如果没有，则内存会退回到关键词搜索。
已经有一个后端（自托管或托管）？直接将一个代理连接到它：
```bash
python quickstart.py --backend https://your-backend --connect-only
```
### 全栈（Docker）
使用 Docker Compose 运行所有内容 - 后端、网页仪表盘、Postgres 和对象存储。使用此方法获取仪表盘和 `full` 模式下的 [编排层](#编排层)：
```bash
cp services/backend/.env.example services/backend/.env # 然后设置您的密钥
docker compose up --build
# 后端：:8000 · 仪表盘：:5173 · Postgres：:5432 · MinIO 控制台：:9001
```
配置参考（环境变量、部署模式）：
[`services/backend/README.md`](services/backend/README.md)。
### 团队自托管（远程）
在您自己的主机上建立一个共享后端（一个 VM，一个 microVM，您的机器 - 任何可以运行 Docker 的地方）。**管理员令牌永远不会离开该主机：**
```bash
faradium deploy # 在主机上：启动堆栈，打印一个 solo 启动器密钥
faradium enroll --backend https://your-backend --admin-token "$ADMIN_TOKEN" --agent all
faradium connect fde1_… # 每个队友粘贴注册字符串
```
> ⚠️ `deploy` 只启动堆栈 - **TLS、DNS 和身份验证由您提供。**
> 管理员令牌和 API 密钥是承载机密，因此请将后端放在 HTTPS 后，并为任何非本地部署设置 `ADMIN_TOKEN`。当前的一个注意事项：
> 仪表盘无法发送 `ADMIN_TOKEN`，因此请用 VPN 或您自己的身份验证方式保护安全堆栈。详细信息请参见 [SECURITY.md](SECURITY.md)。
完整的 `deploy → enroll → connect` 操作指南：
[`packages/faradium-memory/README.md`](packages/faradium-memory/README.md)。
## 工作原理
内存是前门。使其有用且值得信赖的是 **它拒绝存储的内容和允许写入它的内容**:
- **它只存储代理无法通过读取代码恢复的内容。** 五类输入：
`MISTAKE`、`CONVENTION`、`GOTCHA`、`DECISION`、`FINDINGS`。不会重新总结仓库。
- **代理只能写入三类输入** - `MISTAKE` / `DECISION` / `FINDINGS` - 通过 MCP 工具在会话中。`CONVENTION` / `GOTCHA` 保留给被动分析器（一种廉价的模型，读取会话 *之后* 的记录），因此代理无法为自己声明项目范围的约定。
- **信任通过相互验证获得。** 从一个供应商看到的事实开始
低置信度并等待审查；同一个事实由第二个供应商（例如 Claude **和** Codex）独立报告，自动提升为高置信度。只有受信任的条目会在下一个会话开始时被注入。
- **按仓库分区**，从 git 远程仓库派生 - 因此每个项目都记住自己的事实，并且知识在机器和会话之间跟随仓库，而不是跟随运行代理的人员。
您的代理通过一个小的本地 **MCP 服务器**（`faradium serve`）访问所有这些功能，因此您无需学习新内容 - `record_*` / `recall` 工具只需在您已经使用的 CLI 中出现。
## 仓库布局
一个包含三个组件的 monorepo，每个组件都有自己的更深入的 README：
| 路径 | 堆栈 | 它是什么 |
| --- | --- | --- |
| [`services/backend/`](services/backend/) | Python · FastAPI | 后端 + 内存存储。在 `memory` 模式（独立，SQLite - 快速启动使用的）或 `full` 模式（编排 + Postgres上的内存）下运行。 |
| [`packages/faradium-memory/`](packages/faradium-memory/) | Python | 本地代理运行的 `faradium` CLI（`serve` · `connect` · `enroll` · `deploy` · `init`）。与云虚拟机烘焙的 **相同** 包。 |
| [`apps/dashboard/`](apps/dashboard/) | TypeScript · React | 网页仪表盘 - 内存审查队列 + 编排 UI。 |
## 内存存储后端
一个 `MemoryStore` 接口，两个通过配置（`MEMORY_STORE_BACKEND`）选择的实现：
- **SQLite** - 本地，单用户；克隆并运行的默认后端。
- **Postgres + pgvector** - 主机 / 多租户。
所有策略 - 去重，置信度提升，信任门槛 - 都位于接口 *之上*，因此两个后端不会漂移。
## 编排层
`full` 模式（上面的 [Docker 堆栈](#全栈-docker)）添加了夜间云代理，在 [E2B](https://e2b.dev) 沙盒中运行，在自己的分支上处理 GitHub 仓库，并打开一个 PR - 每个会话都从共享内存池中读取和写入。 它需要一个 E2B 账户和一个公开可达的后端。 有关设置和 E2B 模板构建，请参见 [`services/backend/README.md`](services/backend/README.md)。
## 贡献
欢迎 PR！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以了解本地设置、仓库布局和 CI 运行的测试命令。简而言之：
```bash
cd services/backend && uv run pytest # 后端
cd packages/faradium-memory && uv run pytest # CLI / MCP
cd apps/dashboard && yarn build # 仪表盘（类型检查）
```
## 安全
法拉第内存处理凭证并针对您的仓库运行代理。请阅读 [SECURITY.md](SECURITY.md) 以了解凭证模型以及如何报告漏洞 - **不要为安全问题公开一个公共问题。**
## 许可证
[MIT](LICENSE) - 您可以随意使用，无需担保。
<div align="center">
<sub>为您的现有代理而构建。</sub>
</div>
