faradium

<div align="center"> # Faradium ### Durable, cross-session memory for coding agents - with an orchestration tier on top. Your coding agent forgets everything between sessions. Faradium gives the agent you already run - **Claude Code · Codex · Gemini** - a memory that *survives*: project knowledge that persists across sessions, is shared between tools, and is partitioned per repository. <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 /> [**Quickstart**](#quickstart) · [**How it works**](#how-it-works) · [**Repo layout**](#repo-layout) · [**Self-host**](#self-host-for-a-team-remote) · [**Orchestration**](#the-orchestration-tier) · [**Contributing**](#contributing) </div> <p align="center"> <img src="docs/screen.png" alt="Faradium dashboard" width="820" /> </p> --- ## Quickstart Faradium runs at three sizes - pick the smallest that fits your need: | Mode | Command | What you get | | --- | --- | --- | | **Local-first memory** | `python quickstart.py` | SQLite memory wired into your agent CLI. No Postgres, no Docker. | | **Full stack (Docker)** | `docker compose up --build` | Backend + web dashboard + Postgres, and the orchestration tier. | | **Self-host for a team** | `faradium deploy` → `enroll` → `connect` | A shared backend on your own host; teammates onboarded without the admin token. | ### Local-first memory (clone-and-run) No Postgres, no cloud account, no PyPI - just a clone and one command. It starts a local memory backend (SQLite) and wires it into your agent CLI: ```bash git clone https://github.com/faradium/faradium && cd faradium python quickstart.py # --agent claude (default) | codex | gemini | all ``` **What it does:** 1. installs the `faradium` CLI (the `faradium-memory` package) from this checkout (via `uv`), 2. starts the memory backend in **memory mode** on SQLite (`services/backend`, no Postgres), 3. mints an account API key and registers `faradium serve` with your agent CLI (works in every repo; the server partitions memory by the repo you're in), 4. leaves the backend running - keep that terminal open and use your agent elsewhere. > **Requirements:** Python 3.11+ and [`uv`](https://docs.astral.sh/uv/). Embeddings are > optional - set `OPENAI_API_KEY` for semantic recall; without it, memory falls > back to keyword search. Already have a backend (self-hosted or hosted)? Wire an agent straight to it: ```bash python quickstart.py --backend https://your-backend --connect-only ``` ### Full stack (Docker) Runs everything - backend, the web dashboard, Postgres, and object storage - with Docker Compose. Use this to get the dashboard and, in `full` mode, the [orchestration tier](#the-orchestration-tier): ```bash cp services/backend/.env.example services/backend/.env # then set your keys docker compose up --build # backend :8000 · dashboard :5173 · Postgres :5432 · MinIO console :9001 ``` Config reference (env vars, deployment modes): [`services/backend/README.md`](services/backend/README.md). ### Self-host for a team (remote) Stand up a shared backend on your own host (a VM, a microVM, your box - anywhere Docker runs). **The admin token never leaves that host:** ```bash faradium deploy # on the host: boots the stack, prints a solo starter key faradium enroll --backend https://your-backend --admin-token "$ADMIN_TOKEN" --agent all faradium connect fde1_… # each teammate pastes the enrollment string ``` > ⚠️ `deploy` boots the stack only - **TLS, DNS, and auth are yours to provide.** > The admin token and API keys are bearer secrets, so put the backend behind > HTTPS, and set `ADMIN_TOKEN` for any non-local deployment. One current caveat: > the dashboard can't send `ADMIN_TOKEN` yet, so gate a secured stack behind a VPN > or your own auth. Details in [SECURITY.md](SECURITY.md). Full `deploy → enroll → connect` walkthrough: [`packages/faradium-memory/README.md`](packages/faradium-memory/README.md). ## How it works Memory is the front door. The thing that makes it useful - and trustworthy - is **what it refuses to store and who's allowed to write it**: - **It stores only what an agent can't recover by reading the code.** Five typed categories: `MISTAKE`, `CONVENTION`, `GOTCHA`, `DECISION`, `FINDINGS`. No re-summarizing the repo back to itself. - **Agents can only write three of them** - `MISTAKE` / `DECISION` / `FINDINGS` - mid-session via MCP tools. `CONVENTION` / `GOTCHA` are reserved for a passive analyzer (a cheap model that reads the transcript *after* the session), so an agent can't declare a project-wide convention about itself. - **Trust is earned by corroboration.** A fact seen from one vendor starts low-confidence and pending review; the *same* fact independently reported by a second vendor (e.g. Claude **and** Codex) auto-promotes to high confidence. Only trusted entries are injected at the start of the next session. - **Partitioned per repository**, derived from the git remote - so each project remembers its own facts, and the knowledge follows the repo across machines and sessions, not the person who happened to run the agent. Your agent reaches all of this through a tiny local **MCP server** (`faradium serve`), so there's nothing new to learn - the `record_*` / `recall` tools just appear in the CLI you already use. ## Repo layout A monorepo with three components, each with its own deeper README: | Path | Stack | What it is | | --- | --- | --- | | [`services/backend/`](services/backend/) | Python · FastAPI | The backend + memory store. Runs in `memory` mode (standalone, SQLite - what the quickstart uses) or `full` mode (orchestration + memory on Postgres). | | [`packages/faradium-memory/`](packages/faradium-memory/) | Python | The `faradium` CLI your local agents run (`serve` · `connect` · `enroll` · `deploy` · `init`). The **same** package the cloud VMs bake. | | [`apps/dashboard/`](apps/dashboard/) | TypeScript · React | The web dashboard - memory review queue + orchestration UI. | ## Memory store backends One `MemoryStore` interface, two implementations selected by config (`MEMORY_STORE_BACKEND`): - **SQLite** - local, single-user; the default for clone-and-run. - **Postgres + pgvector** - hosted / multi-tenant. All policy - dedup, confidence promotion, the trust gate - lives once *above* the interface, so the two backends can't drift. ## The orchestration tier `full` mode (the [Docker stack](#full-stack-docker) above) adds overnight cloud agents that run in [E2B](https://e2b.dev) sandboxes, work a GitHub repo on their own branch, and open a PR - each session drawing from and writing back to the shared memory pool. It needs an E2B account and a publicly reachable backend. See [`services/backend/README.md`](services/backend/README.md) for setup and the E2B template build. ## Contributing PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, the repo layout, and the test commands CI runs. In short: ```bash cd services/backend && uv run pytest # backend cd packages/faradium-memory && uv run pytest # CLI / MCP cd apps/dashboard && yarn build # dashboard (type-checks) ``` ## Security Faradium handles credentials and runs agents against your repos. Please read [SECURITY.md](SECURITY.md) for the credential model and how to report a vulnerability - **don't open a public issue for security problems.** ## License [MIT](LICENSE) - do what you like, no warranty. <div align="center"> _{Built for the agents you already run.} </div>