Reading the repo
Reading the repo
How to install on macOS
AI memory for Claude Code, Cursor, Codex, Windsurf, and every MCP agent: one shared, versioned memory in a local MCP server. Offline, no API key.
GitHub didn't answer, so this is the saved copy from 19 h ago
Will it work on my device?
CONTRIBUTING.mdThanks for helping with Make0 Brain. Bug reports, fixes, and new agent integrations for init are all welcome.
You need Node.js 22 or newer.
git clone https://github.com/make0-official/brain-oss.git
cd brain-oss
npm install
npm test
npm test is the fast suite: it uses a hashing embedder, so it downloads no models and needs no API key. Two slower suites run on demand:
npm run test:models # real local models (downloads about 50 MB once)
npm run test:e2e # build, then drive the stdio server
To try the viewer against a throwaway database:
npm run build:web
MAKE0_BRAIN_DB=/tmp/try.db npm run dev -- view --no-open
npm run dev:web # hot reload at http://localhost:5173, API proxied to :4173
To point an agent at your checkout, set its MCP server to npx tsx /path/to/brain-oss/src/cli.ts in place of npx -y @make0-ai/brain, with MAKE0_BRAIN_DB in its env block so it does not touch your real brain. (npm run dev prints npm's banner to stdout, which breaks the stdio transport.)
npm run typecheck && npm test before pushing. CI runs the same checks on Linux and macOS..env files, or API keys, including in test fixtures.Security problems go through SECURITY.md, not a public issue or pull request.
Set the new version in package.json, and twice in server.json (version and packages[0].version).
Rename Unreleased in CHANGELOG.md to [X.Y.Z] - YYYY-MM-DD, start a new empty Unreleased, and update the compare links at the bottom.
Commit as Release X.Y.Z: <summary>, push to main, then tag and push the tag:
git tag vX.Y.Z
git push origin vX.Y.Z
The Release workflow checks that the three versions and the changelog agree, runs the tests, publishes to npm with provenance, updates the MCP Registry, and creates the GitHub Release from the changelog section.
npm publishing uses trusted publishing, so no npm token is stored in the repository. It has to be set up once on npmjs.com: package settings → Trusted publisher → GitHub Actions, organization make0-official, repository brain-oss, workflow release.yml.
Then run bash setup.sh. It stops at the first error and is safe to run again. Servers and tests aren't started; it lists them at the end. Read it first.
Needs Git: xcode-select --install
git clone https://github.com/make0-official/brain-oss.git cd brain-oss
Node.js >=22
# needs nvm: brew install nvm (or https://github.com/nvm-sh/nvm) nvm install --lts
cp .env.example .env
npm ci
npm run dev
npm test
1. Connect your agents.
npx @make0-ai/brain init
init finds Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex CLI, Gemini CLI, Hermes Agent, and OpenClaw. When more than one is installed, it shows a checklist of them, all ticked; untick any you want to leave out. Pass --clients to choose up front, or --yes to configure every detected agent without asking. It then shows what it will change, asks once, keeps a .make0-backup of each config file, and adds Make0 Brain to each chosen app. It downloads the two local models (about 50 MB, once) with a progress bar, so your first question to an agent doesn't wait on a download. Restart the apps afterwards.
Connecting the server is not enough. The agent also needs a custom instruction so it searches Brain before answering and saves lasting facts there. init writes this into the global rules file for Claude Code (~/.claude/CLAUDE.md), Codex (~/.codex/AGENTS.md), Gemini (~/.gemini/GEMINI.md), and Windsurf. Cursor, Claude Desktop, VS Code, Hermes Agent, and OpenClaw keep rules in settings or a persona file, so init prints the same text for you to paste:
Make0 Brain is my source of truth for durable memory. Always search it before answering about me, my work, people, preferences, or past decisions. Save lasting facts and decisions to Brain. Never guess or invent memories. Use Brain exclusively for durable memory.
| App | Where it goes |
| -------------- | -------------------------------------------------------- |
| Claude Code | ~/.claude/CLAUDE.md, written by init |
| Codex CLI | ~/.codex/AGENTS.md, written by init |
| Gemini CLI | ~/.gemini/GEMINI.md, written by init |
| Windsurf | Global rules, written by init |
| Cursor | Settings → Rules → User Rules. Paste it. |
| Claude Desktop | Settings → Profile → personal preferences. Paste it. |
| VS Code | .github/copilot-instructions.md in the repo. Paste it. |
| Hermes Agent | ~/.hermes/SOUL.md. Paste it. |
| OpenClaw | ~/.openclaw/workspace/AGENTS.md. Paste it. |
Skip the rule with init --no-rules.
2. Bring in the context you already have.
npx @make0-ai/brain import --detect # CLAUDE.md, AGENTS.md, Cursor/Windsurf/Copilot rules
npx @make0-ai/brain import --sessions # past sessions from 41 coding agents, one digest each
npx @make0-ai/brain import ~/Documents/MyVault # an Obsidian vault or any Markdown folder
pbpaste | npx @make0-ai/brain import - # e.g. a memory dump copied from ChatGPT
import on its own asks what to import. The details are under Import and export.
3. Look at it.
npx @make0-ai/brain view
The viewer opens on 127.0.0.1 with every brain, how many memories each holds, and what your apps retrieved and added this week.
Models live in ~/.make0/models and data in ~/.make0/brain.db. If you skip init (or pass --no-models), the first save or search downloads the models instead.
Typed in a terminal, npx @make0-ai/brain opens a menu: connect agents, import sessions or notes, open the viewer, create a brain, choose which brains an app can use, export, restore an archived memory, or show stats. Any command run without its arguments asks for them the same way, one step at a time, with arrow keys, checkboxes, and a default on Enter. Ctrl+C cancels without changing anything.
Scripts and MCP clients are unaffected. Passing the arguments, adding --yes, or running without a terminal skips every question, and MCP clients, which start the server without a terminal, get the server as before. make0-brain serve starts the server even in a terminal.
Restart the apps you connected, then check that a memory written by one agent reaches another:
…
No reports for macOS yet.
Opens a chat with this manual already filled in, for macOS. It uses your own account; gitmanual sends nothing.