phygital-brain

What it is

Phygital Brain is an OS (operating system) for your notes and your AI agent. It builds one folder in your cloud drive (Google Drive, Nextcloud, Dropbox or any drive your agent can connect to), with three kinds of things inside:

• Rules: a CLAUDE.md file in every folder. It tells your agent where each kind of information goes, how each note starts, and what to ask you before it changes anything.

• Notes: plain Markdown files (simple text files with light formatting) about you, your projects, your people, your decisions and your days. Your agent writes them as you talk, and links them together.

• The Brain Keeper: a scheduled task that tidies the brain every work day, plus a full check-up whenever you ask for one.

Every chat on that folder starts with your agent reading the rules and the latest notes. So it already knows your name, your clients, your goals and what you did yesterday. You can read and browse the same notes in Baalda, or from your phone through your drive.

It comes as two skills (sets of instructions your agent follows): one builds the brain, one keeps it tidy. They're packaged as a Claude plugin, because Claude is what we use and recommend, but any agent that can work in a folder can follow them. See Other agents.

Related MCP server: big-brain

Yours to keep

• You own it. Your brain is a folder of plain text files in your own cloud drive. There's no account with us and nothing to export.

• Take it to any AI. Switch to another agent and open the same folder. The new one reads the same notes.

• It remembers you. What you tell your agent is saved as notes, so the next chat, or the next AI, starts where you left off.

• Free and open source. Anyone can check how it works. Your notes stay private, in your drive: Phygital Brain collects nothing, and your notes go only to the AI you choose.

Why it exists

A chat with an AI ends, and what you told it goes with it. Next time you explain your business, your clients and your project again. The notes you do keep sit in five apps, and none of them talk to your agent.

Phygital Brain gives the agent one place to read from and write to, with rules it follows every time:

How it works

The parts of a computer's operating system each have a match in your brain:

This is what happens when you tell your agent something:

sequenceDiagram
    actor You
    participant A as Your agent
    participant R as Rules (CLAUDE.md)
    participant N as Notes
    You->>A: "Had a call with Marta. The cover is due on the 15th."
    A->>R: Where does each part go?
    R-->>A: Date to the project, call to today, contact to the client
    A->>N: Search first, so nothing is made twice
    A->>N: Update Projects/Picture-Book, Relationships/Clients/Penguin Kids
    A->>N: One line in Daily/2026-10-20, linked to both
    A-->>You: "Saved the new date in Picture-Book and the call in today's note."

Small updates to notes that already exist happen right away, and your agent tells you in one line. New notes, moves, renames and deletes always wait for your yes. More in How it works.

What you get

• A brain built from your answers. People who sell get pages for their business, services and customers. People who don't sell get none of those. A morning brief appears only if you ask for one.

• Questions written for your work. The second form starts with three questions your agent writes for your job. An illustrator gets asked about publishers and how they charge; a developer gets asked about their projects and tools.

• Projects, people and days, linked. Every person, company and project is a [[link]], so one click in Baalda takes you from a project to the client to the day you talked.

• Decisions with the reason. Each decision note says what you chose, why, what you gave up, and the risk. Open decisions show up in your daily note until you close them.

• The Brain Keeper. Every work day it makes tomorrow's note, closes old ones, lists open decisions, fixes up to 5 small things and writes a report. A full check-up runs whenever you say "check up my brain".

• A morning brief, if you want one: your three most important things, what you're waiting on, and one decision to make.

• Meeting prep. Say "prep me for Marta" and get a short brief from your notes: when you last talked, what's going on, what was agreed, what to bring up.

• Thinking tools. "Challenge my idea" weighs it against your own notes. "What patterns do you see?" finds what keeps coming up. "Find contradictions" finds notes that disagree.

• Your apps, read only. Connect Gmail and Google Calendar (or Outlook, Nextcloud and others) and the Brain Keeper notes yesterday's emails with your people and tomorrow's meetings. It never sends or changes anything.

• Fully online, if you want. The Brain Keeper can run as a cloud routine, reading and writing your notes through your cloud drive, with your computer off.

• Backups and undo. Before a big change, your agent copies the files into a hidden .backups/ folder for 10 days. "Undo the last change" puts them back.

• Old notes, any time. "Bring in my old notes" imports from Notion, Google Docs, Apple Notes and others, with a plan you approve first.

• Teams. Share one brain through Baalda's cloud, with a Team section in the rules for each person's role.

• Your phone. Ask your brain things from your agent's phone app through your cloud drive, or send tasks to your computer (in Claude, with Dispatch).

• Your language. The forms, messages and notes are in the language you pick. File and folder names stay in English, so the rules work the same everywhere.

• Writing that sounds like you. Every brain comes with the no-ai-slop skill. Your agent writes in your voice, then checks for AI-sounding patterns before anyone else reads it.

• Careful work habits. The main rules include Andrej Karpathy's guidelines for AI assistants: ask when unsure, pick the simplest way, change only what's needed, check the work.

• Your own rules. When you correct your agent, it saves the correction as a new rule, in your words. Upgrades never change those rules.

How your agent works

The work habits are Andrej Karpathy's guidelines for AI assistants (andrej-karpathy-skills), built into every brain's main rules in our own words. The Writing Check uses the no-ai-slop skill, which every brain gets in Skills/no-ai-slop/. More in Main rules.

Inside your brain

My Brain/
├── CLAUDE.md          the main rules
├── .claudeignore      what your agent never reads unless you ask
├── About/             me.md, goals.md, business.md, services.md, brand.md ...
├── Daily/             2026-10-20.md, 2026-10-21.md ... and tasks.md
├── Projects/          Picture-Book/README.md, Portfolio-Website/README.md ...
├── Relationships/     Clients/, Collaborators/, Team/, Partners/
├── Memory/            decisions/, research/, finances/ (private), archive/
├── Library/           prompts, templates, checklists
└── Skills/            brain-keeper/, morning-brief/

Each folder has its own guide: what goes in it, what you can say, examples and its rules. Start at The folders in your brain.

Quick start

You need an AI agent that can work in a folder, a cloud drive your agent can connect to, and a computer. No code. We recommend Claude with Google Drive, the pair we tested most, so the steps below use them. The full steps, with other drives and agents, are in Getting started.

Install: click the button for your agent.

Or in a terminal, for any agent that uses skills (Claude Code, Codex, Cursor, Gemini CLI and others):

npx skills add Phygital-Brain/phygital-brain

It asks which of your agents to add it to. Claude desktop and Claude Code need nothing more. The other ways need Node.js, a free one-time install.

Every way, step by step: Install.

flowchart LR
    C[Checks: the folder] --> L[Language] --> W[Welcome]
    W --> CD[Cloud drive:<br>connect and check] --> F1[Form 1<br>About you] --> F2[Form 2<br>Your work] --> F3[Form 3<br>Days and people] --> F4[Form 4<br>Files]
    F4 --> B[Build: folders, rules,<br>notes, Brain Keeper]
    B --> D[One short message:<br>what was built, how to use it]

At the end, your agent welcomes you as your personal assistant, and offers Baalda to browse your notes like an app.

A week with your brain

Ana is an illustrator in Lisbon. She sells picture-book work to publishers and set up her brain on Monday.

• Monday, 10:00. She answers the four forms and drops in her CV and price list. Her agent builds About/me.md, goals.md, services.md, three projects and a note for her editor's publisher.

• Tuesday, 08:00. Her morning brief lists three things: send the sketches, reply to a bakery about a logo, and decide on her cover price.

• Tuesday, 15:00. After a call she says: "Marta wants the cover by the 15th." The project, the client note and the day are updated and linked.

• Wednesday, on the bus. In her agent's phone app she asks: "What did Marta and I agree on Tuesday?" It finds the note in her drive.

• Thursday. "I decided to raise my cover price to 400 from January." Her agent asks a little about why, then writes Memory/decisions/2026-10-23-raise-cover-price.md.

• Every work day, 07:00. The Brain Keeper makes the next day's note, closes old ones and fixes small things. Each morning it lists the cover-price decision as still open, until she closes it.

More people, from a bakery owner to a student, are in Use cases.

On your phone

Setup, what to say, and fixes for common problems: Your brain on your phone.

Languages

Phygital Brain is ready in 41 languages. Pick yours at the start of the setup, and the whole brain is built in it: the forms, the rules, the folder and note names, the Brain Keeper and every message.

See the full list of languages.

Your language isn't here? Pick Other and type it. Your agent translates the whole brain during the setup, folder names included, without asking you anything. To make a checked set that everyone who speaks your language can use, say:

Translate Phygital Brain into my language.

The add-language skill asks you three things (formal or informal "you", the main folder names, and the names for the Brain Keeper and the morning brief), translates everything, checks it, and shows you how to use it and share it. How it works, step by step: Languages.

Switching later: say "Switch my brain to Spanish". Your agent renames the folders and swaps the rules, with a backup first and your yes.

Works with your agent

The rule files are called CLAUDE.md. Agents that look for another name, like AGENTS.md in Codex, get a one-line file that points to CLAUDE.md, so there's only one set of rules. More in Other agents.

Privacy

Your notes are read by your AI agent and stored in your cloud drive. Phygital Brain itself has no server and collects nothing. More in What you share with your AI.

• Private details stay in one place. Tax IDs, bank details, card numbers, your full legal name and your birth date live only in the note that needs them. Your agent never copies them into other notes, and never repeats them in a reply.

• A "never read" list. .claudeignore covers password and key files and Memory/finances/. Your agent opens those only when you ask for an exact file. Your agent follows this as a rule, but nothing is locked.

• No secrets in notes. Passwords, keys and tokens belong in a password manager.

What it isn't

The full list is in Limits.

• No app. There's nothing to run. Your AI agent does the work, following the files in this repository.

• No lock yet. The rules work only because your agent follows them. Keep truly secret things outside the brain folder. Locked folders are on the roadmap.

• Not always on, unless you move it to the cloud. On your computer, the Brain Keeper and the morning brief run only while your agent's app is open. As a cloud routine, they run with the computer off.

• An early version. This is version 0.1.9, and the setup hasn't been tested with many people yet.

Roadmap

Planned, not built yet:

• Locked folders. You choose which folders to lock, like Memory/finances/. Their notes are encrypted in your drive, so no app or agent can read them without you. You unlock them with your password or fingerprint, from the agent you already use, and only for what you approve.

Ideas are welcome: open an issue on GitHub.

Updating and leaving

To update: update the plugin (in Claude Code, /plugin marketplace update phygital-brain), then say "Upgrade my second brain." Your agent shows what's new and asks first. Your notes and your own rules stay as they are.

To change your answers: say "Update my answers." The forms open again, and your About pages are refreshed.

To leave: uninstall the plugin. Your brain is a folder of plain text files in your own cloud drive. Any app that reads Markdown can open it.

FAQ

The most asked questions are below. The full list, with 92 answers grouped by topic, is in the FAQ.

No. You install a few apps, answer four forms and talk in plain words. The only lines that look like code are the two install lines for Claude Code, and you can paste them.

Any agent that can read, edit and create files in a folder on your computer. Claude is what we use and recommend: it's the only one that shows the setup as form windows, and it can schedule the Brain Keeper. Codex, Hermes Agent, OpenClaw and similar agents ask the same questions in chat. See Other agents.

Any drive that keeps a copy of the folder on your computer and that your agent can connect to, so it can read, edit and create files there: Google Drive, Nextcloud, Dropbox, OneDrive and others. Claude has a built-in Google Drive connector; other drives usually connect through an MCP server. See Cloud drives.

It saves small updates to notes that already exist and tells you in one line. It asks before it makes a new note, rewrites one, or moves, renames or deletes anything. The Brain Keeper never deletes your notes.

Phygital Brain is free and open source. You pay for your AI agent and, if you need more than the free space, your cloud drive.

All the guides

This repository

Help and contributing

Questions, bugs and ideas: open an issue on GitHub. To change something, read CONTRIBUTING.md and AGENTS.md. Report security or privacy problems privately, as SECURITY.md explains. To cite the project, use CITATION.cff.

Open source and credit

Free and open source under the Apache License 2.0. Keep the NOTICE file: it carries the line "Created by Phygital-Brain".

The licence doesn't cover the name and logo (see TRADEMARKS.md). You can say your work is "built on Phygital Brain", but you can't sell it under that name.

No warranty

Phygital Brain is provided as is, without warranty of any kind (see sections 7 and 8 of the licence). You're responsible for what you put in your brain and what you share with your AI provider.