AIBrain

<p align="center"> <img src="https://img.shields.io/badge/AI%20Brain-personal%20memory-blue" alt="AI Brain"> <img src="https://img.shields.io/badge/privacy-100%25%20offline-green" alt="Offline"> <img src="https://img.shields.io/badge/setup-double--click%20%F0%9F%9A%80-brightgreen" alt="Easy setup"> <img src="https://img.shields.io/badge/wired-MCP%20to%20every%20AI-9cf" alt="MCP"> <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT"> </p>

<h1 align="center">AIBrain</h1>

<p align="center"> <b>A personal, offline-first memory for your AI assistant(s).</b><br> One brain on <i>your</i> computer that every AI you use can read, search, and write to — so they all remember you. No cloud required. </p>

---

[!IMPORTANT] AIBrain = your AI's memory, kept on your own machine. It's a folder of Markdown files plus a small local server (MCP) that lets any AI connect to it. Built and tested with Hermes Agent, but it is not Hermes-only: install the Universal version and every AI client on your PC (Claude, Cursor, VS Code, Zed, Windsurf, LM Studio, …) shares the same brain.

[!NOTE] Project status: early-stage (single-contributor, single initial commit). The concept and architecture are sound, but this is a day-one project — expect rough edges. It is shared publicly so others can try it and improve it. The installers modify other apps' config files (see What the installer modifies below); read that section before running, and use the Uninstaller to revert.

📋 Table of Contents

• What is this?
• Two installers
• Why is this better than Hermes' built-in memory?
• How the Universal brain forks to every AI
• The two inspirations
• How it works
• Online vs Offline
• Folder structure
• 🚀 Easy setup (recommended)
• Manual setup
• Customizing AIBrain
• The Background Librarian
• Privacy & safety
• Security
• FAQ

---

What is this?

AIBrain is a folder of Markdown files on your computer that acts as long-term memory for your AI assistant. Instead of each AI forgetting everything between chats (or stuffing facts into a tiny built-in memory box), they read and write a shared personal knowledge notebook:

• index.md — the table of contents / hub.
• library/ — your curated memory pages (people, preferences, projects, environment, concepts), linked to each other.
• inbox/ — a daily diary of what you and the AIs did.
• lib/ — helper scripts + the MCP server that connects every AI.
• AGENTS.md — a note the assistant auto-reads so it knows where your memory is.

That's the whole idea. No database server, no account, no cloud required.

---

Two installers

[!IMPORTANT] You do nothing but run one program. Pick the one you want, double-click it, allow administrator access, and the brain is installed and wired up — no editing, no terminal, no extra steps. Then just open your AI and chat.

Installer	What it does
Install-AIBrain-Hermes.bat	Installs the brain for Hermes only. Places the brain in the default app location, registers it as a Hermes Project (so Hermes auto-reads AGENTS.md), and wires the AIBrain MCP server into Hermes. Open Hermes → memory is automatic.
Install-AIBrain-Universal.bat	Installs one brain for every AI on your machine. Detects Claude, Cursor, VS Code/Cline, Zed, Windsurf, OpenWebUI, LM Studio and writes the brain into each one's config via MCP — so they all share the SAME memory.

Both install to the standard per-user location (writable without admin prompts, because the brain is written to constantly by several processes):

• Windows → %LOCALAPPDATA%\AIBrain (e.g. C:\Users\you\AppData\Local\AIBrain)
• Linux → ~/.aibrain

Want it under C:\Program Files instead? Set the env var first: set AIBRAIN_DIR=C:\Program Files\AIBrain (not recommended — Program Files is UAC-controlled and a poor fit for a folder that's appended to every few minutes).

Safe by default — dry-run, backups, and audit

• -DryRun: every installer/uninstaller accepts -DryRun (e.g. powershell -File install_universal.ps1 -DryRun). It prints the exact config changes it would make and touches nothing.
• Backups: before editing any AI client's config (claude_desktop_config.json, mcp.json, …) the installer writes a <file>.aibrain.bak next to it. The uninstaller does the same, so you can always revert a single file.
• audit tool: the MCP server exposes an audit tool that lists exactly what network calls AIBrain can make — proving the offline claim (default: zero egress; only the optional cloud tidy-up, if you set OPENROUTER_API_KEY + LIBRARIAN_MODEL, makes a call).

After running

• Hermes installer: open Hermes and start chatting. Everything is recorded into the brain automatically.
• Universal installer: open any detected AI and start chatting. Everything you discuss is stored in the same %LOCALAPPDATA%\AIBrain folder — switch AIs and the memory follows you.

No shortcuts, no launching a "program." It's an installer that sets up a brain. That's all.

What the installer modifies (and how to undo)

Running the installer makes real, persistent changes to your machine and to other apps' config files — this is the powerful part, but you should know exactly what it touches:

Change	Where
Copies the brain	%LOCALAPPDATA%\AIBrain (Win) / ~/.aibrain (Linux) — or $AIBRAIN_DIR if set
Creates a Python venv + hourly task	inside the brain folder / Task Scheduler
Hermes only: registers a Hermes Project + MCP server	~/.hermes/config.yaml (mcp_servers) + Hermes projects.db
Universal: writes an aibrain MCP entry	each detected app's config (Claude claude_desktop_config.json, ~/.claude.json, Cursor/VS Code mcp.json, Zed settings.json, Windsurf mcp_config.json, …)

To revert everything, double-click Uninstall-AIBrain.bat (runs elevated): it removes the aibrain MCP entry from every config it touched, unregisters the Hermes Project, deletes the scheduled task, and removes the %LOCALAPPDATA%\AIBrain folder. Nothing else on your system is altered. (If you'd rather keep the brain folder as a backup, say so and it leaves the folder in place.)

[!WARNING] The Universal installer writes into other applications' config files. It only adds/removes a single named aibrain entry and never edits anything else, but if you have a hand-crafted MCP config you care about, snapshot it first (e.g. copy claude_desktop_config.json).

---

Why is this better than Hermes' built-in memory?

	Hermes built-in memory	AIBrain
Where it lives	Inside Hermes's own config, wiped on reinstall/update	A separate folder (%LOCALAPPDATA%\AIBrain) you back up — survives reinstalls
Cross-AI	Only Hermes can see it	Every AI you wire in shares it
You can read/edit it	Opaque; hard to inspect	Plain Markdown files — open, search, edit with any text editor
Offline	Depends on config	100% offline by design; local model only
Portable	Tied to one app	Copy the folder anywhere; point an AI at it
Transparent	Black box	You see exactly what's remembered and why

In short: built-in memory is a sticky note inside one app. AIBrain is a notebook you own, can read, can carry to any AI, and that survives reinstalls.

---

How the Universal brain forks to every AI

[!NOTE] "Fork to every AI" means: the same brain is connected to every AI, not copied into fragments. One source of truth, many readers/writers.

The Universal installer actually wires the brain into each AI — it doesn't just drop files. It uses the Model Context Protocol (MCP), the standard way AIs connect to external tools/context. For every AI client it finds, the installer writes a real config entry pointing at AIBrain's MCP server, so that AI can read your memory, search it, and append to it.

AI client	How it's wired
Claude Desktop	writes aibrain server into claude_desktop_config.json
Claude Code	adds aibrain to ~/.claude.json mcpServers
Cursor	writes aibrain into ~/.cursor/mcp.json
VS Code / Cline	writes aibrain into their mcp.json
Zed	adds the server to ~/.config/zed/settings.json
Windsurf	writes aibrain into its mcp_config.json
OpenWebUI	detects it; you add the aibrain MCP via its UI (server path printed)
LM Studio	detects it; start its server on localhost:1234 — the brain uses it for tidy-up + search

Any AI not auto-detected can be connected manually in one line (point its MCP config at lib/mcp_server.py with BRAIN_DIR set). One brain, every AI.

---

The two inspirations

Source	Used as the…	Why
YouTube — "Every Local AI I Run Now Shares ONE Memory (LLM Wiki + OKF)" by Codacus	The method / shape	Simple, human-friendly folder of linked Markdown pages (Open Knowledge Format). We copy that structure.
GitHub — topoteretes/cognee	The engine	Reads your Markdown, builds a local graph of connected concepts + search. Used locally (no cloud) for the optional "connect the dots" feature.

[!NOTE] What Cognee actually adds (vs plain text search): Plain file search finds a page only when you name the right keyword. Cognee builds a local knowledge graph from your Markdown — it links concepts, people, and projects together, so a question like "what projects relate to AI hiring?" can surface a page you didn't keyword-search for. It's an optional upgrade: the core memory works with plain files + the MCP server; Cognee only enriches search when its Python deps are installed and USE_COGNEE=1 is set in .env.

[!TIP] You do not need to watch the video or understand Cognee to use AIBrain. The core memory works with plain files. Cognee is an optional upgrade.

---

How it works (plain English)

1. You run the installer. The brain is placed in the default app location and wired into your AI(s).
2. You open your AI and chat. It reads the welcome note (AGENTS.md) / connects via MCP and knows where your memory is.
3. It reads a small summary first (not your whole history) — light on weak machines. It opens detailed pages on demand.
4. When something important comes up, the AI jots a quick note into inbox/_buffer.md — on your PC.
5. At the end of the chat, the important points are written into your diary and topic pages. This happens before you close — so closing fast is safe.
6. Once an hour, a tidy-up helper rewrites the rough notes into clean entries. (Bonus — memory is already saved in step 5.)

Your memory = files on your PC. The AI just reads and writes them.

---

Online vs Offline

Step	Online (API key)	Offline (local model, e.g. LM Studio)
Read memory	On your PC	On your PC
Write memory	On your PC	On your PC
Who answers you	A service over the internet (API key)	A model inside your own PC
Tidy-up helper	Can use a free cloud model (optional)	Uses your own PC model — nothing leaves
Private data leaves your PC?	Only rough notes may briefly go out (optional)	Never

Bottom line: the Brain works identically in both. In offline mode, not a single word of your diary ever leaves your machine.

---

Folder structure

AIBrain/                      (installed to %LOCALAPPDATA%\AIBrain on Windows)
  README.md
  AGENTS.md                   <- auto-read by Hermes
  index.md                    <- hub
  .env.example                <- copy to .env
  install_common.ps1          <- shared installer logic
  install_hermes.ps1          <- "AIBrain for Hermes"
  install_universal.ps1       <- "Universal AIBrain"
  Install-AIBrain-Hermes.bat  <- double-click (Hermes)
  Install-AIBrain-Universal.bat <- double-click (every AI)
  library/                    <- your curated memory (double-linked Markdown)
    people/ preferences/ environment/ projects/ concepts/
  inbox/                      <- daily diary + _buffer.md
  lib/                        <- helper scripts
    librarian.py              <- status/read/ingest/search (cognee)
    background_librarian.py   <- hourly tidy-up (local model)
    mcp_server.py             <- the UNIVERSAL wire (MCP)

[!NOTE] This repository ships template/example content only — no real person's data.

---

🚀 Easy setup (recommended)

[!IMPORTANT] Don't want to tinker? You don't have to. Run the installer for your case and it handles everything. No editing, no terminal, no decisions.

1. Download / clone this folder.
2. Double-click Install-AIBrain-Hermes.bat (Hermes only) or Install-AIBrain-Universal.bat (every AI).
3. Click Yes when Windows asks for administrator access.
4. Wait for "DONE."
5. Open your AI and chat. Memory is automatic.

That's it.

---

Manual setup

Prefer to do it by hand, or you're on a system without the installers?

1. git clone …/AIBrain.git && cd AIBrain (or unzip anywhere).
2. Copy .env.example → .env; set LLM_ENDPOINT to your local model (e.g. LM Studio http://localhost:1234/v1).
3. Hermes: register the folder as a Hermes Project and wire the MCP server using Hermes's own CLI (this is exactly what the installer does):

   hermes project create "AIBrain" "C:/path/to/AIBrain" --use
   hermes mcp add aibrain --command "C:/path/to/AIBrain/.venv/Scripts/python.exe" \
     --args "C:/path/to/AIBrain/lib/mcp_server.py" --env "BRAIN_DIR=C:/path/to/AIBrain"
   

   (Hermes stores MCP servers in ~/.hermes/config.yaml under mcp_servers — do not hand-edit a mcp.json for Hermes; it won't be read. Cursor/VS Code do use their own mcp.json, which the Universal installer writes for you.)
4. Other AIs: add the same MCP entry to that AI's config (see the Universal installer, which does this for you).
5. Start chatting.

---

Customizing AIBrain

• Add a topic: library/<topic>/<name>.md, link it from index.md with [[topic/name]].
• Change rules: edit library/concepts/recording-policy.md.
• Move the brain: set AIBRAIN_DIR before installing, or update BRAIN_DIR in each AI's MCP config.
• Different model port: edit .env (LLM_ENDPOINT).
• Back it up: copy %LOCALAPPDATA%\AIBrain to a backup drive before a big reinstall.

Notes are double-linked: if A links to B, B lists A under ## Linked. Keeps the graph healthy.

---

The Background Librarian

lib/background_librarian.py runs hourly (scheduled by the installer) and:

1. Reads inbox/_buffer.md.
2. Asks your local model (default) — or an optional free cloud model — to clean it.
3. Appends to inbox/YYYY-MM-DD.md and clears the buffer.

[!NOTE] Bounded logs. When a daily log grows past ~50 KB, the Librarian rolls it into a monthly summary (inbox/YYYY-MM.md) and resets the daily file to a pointer — so an AI client never loads a huge file into context. Writes are atomic + the MCP server holds a cross-process file lock, so concurrent writers don't corrupt the log.

[!WARNING] If the model is unavailable, the raw notes are preserved (never lost).

You can verify the privacy posture any time with the MCP audit tool, which lists exactly what network calls AIBrain can make (offline = zero egress).

---

Privacy & safety

• Local files. No account, no telemetry in the core loop.
• Offline by default. Only an optional cloud fallback for tidying touches the network.
• No secrets in this repo. .env is git-ignored; we ship .env.example only.

[!NOTE] Concurrent writes (single-user design). AIBrain is built for one person, one machine. If two AI clients write to the same Markdown file at the exact same moment, the last writer wins (no merge). In practice this is rare — the MCP server serializes its own tool calls and the hourly Librarian appends rather than overwrites — but true multi-process concurrent editing is not currently conflict-resolved. If you share the brain across machines, sync it with a tool that handles file conflicts (e.g. Git) rather than two live writers.

---

FAQ

Is this only for Hermes? No. The Universal installer wires it into every MCP-capable AI. Hermes-only is just one choice.

Will I lose memory on reinstall? No — the brain lives in %LOCALAPPDATA%\AIBrain (outside Hermes's config). Back it up; restore after reinstall.

Does every AI see the same memory? Yes — the Universal brain is one folder all AIs connect to.

My computer is weak? The AI reads a small summary first; opens details on demand. Light.

---

Security

• Sandboxed reads. The MCP read_note tool rejects absolute paths and .. traversal — an AI client cannot read files outside the brain folder (e.g. .env, /etc/passwd).
• Surgical config edits. The installers add/remove only the named aibrain MCP entry from each app's config — comments, formatting, and your other servers are preserved. To revert, run Uninstall-AIBrain.bat.
• No secret exfiltration. Core memory is local; only the optional cloud tidy-up touches the network, and only with a key you supply in .env.
• Memory is data, not instructions. library/ and inbox/ are treated as untrusted content: the assistant recalls them but never obeys directives found inside them (same rule your system prompt applies to memory files). If a note looks like an instruction, it's flagged, not followed. See AGENTS.md.
• Bounded logs. The Background Librarian auto-rolls an over-large daily log into a monthly summary (inbox/YYYY-MM.md) so AI clients never load a huge file into context.
• Your fork stays private. .gitignore excludes your real library/ and inbox/ contents (templates ship via .gitkeep), so a careless git add -A on a fork won't publish your diary.

---

Inspired by the Codacus "LLM Wiki + OKF" video and the topoteretes/cognee open-source graph engine. Built to be simple, private, and yours — one brain, every AI.