afair is an open-source, self-organizing memory system for all AI tools, with the core idea that each AI you use only remembers one version of you, and when you switch tools, what was previously learned disappears, so you have to repeat your decisions, relationships, preferences, and history in every new session. afair provides them with a shared memory repository, connected through the Model Context Protocol (MCP), so that the same memory is accessible in Claude, your coding agents, and whatever tool you use next.
Purpose and Positioning
afair automates the work of maintaining memory. A background agent reads what your tools have recorded, discovers which pieces of information belong to the same topic, maintains a useful evolving understanding, and lets old noise gradually fade from attention. The memory structure follows your life rather than applying a fixed template; you do not need to archive, tag, or manually organize anything. At the same time, the results remain visible: you can view what afair considers correct, trace its sources, and correct it when it understands something wrong; corrections become part of the history rather than quietly replacing the original content. Data is append-only and belongs to you. afair is open-source and single-tenant, and you can export all data at any time.
Main Capabilities
afair exposes only three tools, and these interfaces are already fixed and unchanging: remember is used to store persistent information, such as a decision, an important person, a date that must not be missed, or a preference; recall is used to retrieve content relevant to the present when needed; observe is used to record what the AI has just done, keeping the memory repository in sync. After your AI receives a short configuration snippet, it will call these tools on its own; unless there is a write call, nothing enters the memory repository. The system is divided into four layers and one source of truth: the Substrate is an append-only SQLite using FTS5 and sqlite-vec, content-addressed, and the log is never rewritten; the Interpretation layer is a versioned view built on top of the substrate, which can be regenerated without touching any stored events; the MCP surface is versioned and incremental, and published signatures remain continuously available; the Agents layer consists of background workers that extract evidence, discover connections, and maintain dynamic synthesis with citations. Cluster names and boundaries change as evidence changes, and users do not need to define any categories.
How to Use
Self-hosting: this project requires Python 3.12+ and uv. The installation steps are to first clone the repository, run uv sync, and copy .env.example to .env and fill in the LLM provider's API key, then run uv run python scripts/install_clients.py to configure the MCP client and add the afair instruction snippet. The command to start the server is uv run python -m afair, and the server by default runs on http://127.0.0.1:8765 Run. Point a CLI or desktop client (Claude Code, Codex, Cursor, GitHub Copilot) at that address and connect. Cloud web clients (Claude.ai, ChatGPT) require a public HTTPS deployment and quick OAuth configuration; see docs/self-hosting.md for details. All environment variables are documented inline in .env.example, and connection guides for each client are in docs/clients. afair is personal-use by default; two environment variables can also make one memory store belong to a single organization (one instance, one team).
Getting the AI to use it proactively: connecting the server is only half the job; the other half is getting the AI to call the tools itself. Paste a short instruction snippet into the client's persistent instructions (such as CLAUDE.md, AGENTS.md, custom instructions, or .cursorrules), and it will recall context at the start of a conversation, remember persistent information, and observe its own behavior without you having to prompt it each time. The same snippet works for all clients. For Claude Code, Codex, and Cursor, scripts/install_clients.py writes both the connection configuration and the instruction snippet; for GitHub Copilot, it writes the connection configuration and prints a step for setting the instruction snippet per repository (Copilot reads instructions per workspace). Supported scope includes Claude Code, Claude.ai, ChatGPT, Codex CLI, Cursor, Windsurf, Copilot, and any other tool that uses MCP over Streamable HTTP.
Use cases
afair is for individual users who want to share personal memory across different AI tools and avoid repeating background context, and is especially suited to developers who use multiple AI coding agents or chat assistants at the same time. It also supports teams sharing one organization's memory store as a single instance. It emphasizes data ownership, transparent traceability, and correctability, making it suitable for users who value privacy and self-hosting.
Limitations and license
afair is single-tenant by design, aimed at individuals by default, and team sharing requires configuring a single-organization instance via environment variables. Web clients require a public HTTPS deployment and OAuth, and cannot connect using only a local address. The project uses the GNU Affero General Public License v3.0, and you are free toself-host, fork, and modify it; if you provide a modified version as a network service for others to run, you must publish your changes under the same license. The official hosted service is at afair.ai, runs in the EU, is subject to EU jurisdiction, is coming soon, and uses the same code as self-hosting rather than a separate closed-source branch. The project's complete design and the eight invariants that sustain it are in VISION.md; contribution guidelines are in CONTRIBUTING.md, and security reports are in SECURITY.md. The project is built in Germany.
