Shared Consensus Brain

Local URL: http://127.0.0.1:8787/
Alternative: http://localhost:8787/
Scope: local-only dashboard for a Markdown/git brain. No public server, no remote API.

Also known as Cerebro Vivo.

A 100% local window over a Markdown/git "brain": a living graph you can search, read, edit and sync — with automatic backups, real metrics and machine stats. It is an admin and demonstration tool, not a replacement for your everyday editor.

Part of Dev's Foundation. The "brain" is the shared memory behind the multi-agent consensus method. This app is a viewer over that memory — it needs a brain (a folder of Markdown notes) to run.

---

Overview

A "brain" is just a folder of Markdown notes linked by [[wikilinks]]. Shared Consensus Brain turns that folder into:

• a living graph — every note is a node, every resolved link an edge;
• a search + reader + editor — find a note, favorite it, open it, fix it, save it (with a backup first), create new notes and delete mistakes safely;
• a live dashboard — real metrics measured from the brain you loaded, plus stats about the machine hosting it.

Everything runs on your own computer. Nothing is sent anywhere.

Security & privacy (read this first)

The app can read and write your entire vault, so it is treated as a sensitive surface:

• Local only. The server binds to 127.0.0.1 (loopback) — never 0.0.0.0, never a public port.
• Never exposed. Do not put this app on a VPS, a public domain, or any open web interface. If a public version is ever needed, it must be a static, read‑only, filtered export — never the live app.
• No private data in the code. No real machine paths, usernames, IPs, tokens, passwords or private folder names are hardcoded anywhere. The brain folder is chosen by the user at runtime.
• Portable. It is not built around one machine or one folder — point it at your own brain. After a brain loads, the UI simply reads BRAIN LOADED.

Requirements

• Node.js — no other mandatory dependencies.
• A folder of Markdown notes (optionally a git repository — that unlocks contributors and brain days).

Getting started

Windows (app‑window mode, recommended)

Double‑click abrir-cerebro-vivo.bat. It starts the local server and opens the app as a desktop‑style window (Edge / Chrome / Brave in --app mode).

Any OS (manual mode)

cd <workspace>/cerebro-vivo
node server.js

Then open http://127.0.0.1:8787 in your browser.

The port can be overridden with the PORT environment variable. The host is always 127.0.0.1.

Choosing the brain folder (first run)

The app starts with no brain loaded and asks for one:

1. Type or paste your Brain folder path in the top bar.
2. Click Load brain.
3. The choice is stored only in the browser's local storage on that machine — never committed, never sent.
4. To switch brains, change the path and load again.

Use generic example paths in any documentation, never real ones:

<workspace>/cerebro-vivo
/home/user/example-brain
C:\example\user\example-brain

When indexing, these folders are ignored: .git, .obsidian, node_modules, _BACKUPS, .trash, .cache.

Using the app

Graph

• Nodes are .md files; edges are resolved links ([[wikilinks]], [[file|alias]], and Markdown links to .md). Broken links are not drawn.
• Drag empty space to pan · scroll to zoom · drag a node to move it · double‑click to fit the whole graph.
• Show titles toggles labels · Motion and Node size sliders tune the look · Background / Nodes / Links set colors. None of this touches your files.
• Hide dashboard and Open reader give you a clean, full‑stage graph.
• Save graph exports a branded graph snapshot with the packaged Dev's Foundation logo, measured vault metrics and the GitHub link.
• See changes shows git status + git diff in the Logs window.
• Check brain runs a local health report: orphans, broken wikilinks, malformed frontmatter and duplicate note names.
• Open folder opens the loaded brain in the operating system file manager.
• Backups opens the full backup manager: list existing backups, create a full snapshot, open a backup folder or delete a backup with confirmation.
• A local monitor ("No new changes" / "N brain changes" + Reload) watches the folder and lets you re‑index when files change on disk.

Search

Type in Search to filter by title, folder and note content. Results are clickable and jump straight to the note.

Reader & editor

• Click a node (or Open reader) to open a note in the Read tab.
• Use the star in the reader to mark/unmark a note as a favorite. Favorites opens the same reader panel in a dedicated favorites tab. Favorites are local app state, not Markdown edits.
• New note creates a Markdown file in the selected folder, opens it immediately in Edit, and adds contextual wikilinks when there is enough local context. It blocks duplicate note names across the loaded brain to avoid ambiguous graph nodes.
• Switch to the Edit tab, make changes, and click Save.
• Use Delete to remove a note only after an automatic backup is created.
• Close reader returns you to the graph.
• Only .md files inside the loaded brain can be opened or written (path‑traversal is blocked).

Backups

Before every save or delete, the original file is copied first, then the write/delete happens. Backups live inside the brain folder:

_BACKUPS/cerebro-vivo/<YYYY-MM-DDTHH-MM-SS>/<flattened-path>.md

To revert an edit or accidental delete, copy the backup back over the note. _BACKUPS/ is ignored by the indexer and must be excluded when packaging.

The Backups panel also creates full local snapshots under:

_BACKUPS/cerebro-vivo-full/<timestamp>/

Full backups exclude .git, node_modules, _BACKUPS, .obsidian, .trash and .cache, so the app does not back up backups or local tooling. Backup delete is path-safe and only removes folders inside the backup root.

Logs

Local activity is appended to:

logs/events.jsonl

Events include graph indexing, file opened, file saved (with the backup path), favorites, validation reports, git diff, backup actions and manual sync start / done / failed. Logs include a best-effort actor (git config user.name first, then the local OS user) and local client origin when available. If no useful identity exists, no actor is written instead of inventing unknown. Open the Logs window to view them, and use Clear logs to reset. Logs are local; they must never contain secrets or absolute private paths that could be shared.

Favorites

Favorites are stored outside the brain, in local app data:

data/favorites.json

The file stores only relative Markdown paths, grouped by a hash of the loaded vault path. It does not alter notes and must be excluded from clean public packages.

Sync (Git)

The Sync button runs Git only when you press it, in the loaded brain folder:

1. git pull --rebase origin master
2. git status --porcelain
3. if there are changes → git add -A, git commit, git push origin master
4. the last commit and every step are shown in the Logs window

Use it only when the loaded folder is a valid git clone with the right remote. It never syncs silently, and it never hides errors.

Metrics

Every number is measured from the brain you loaded — nothing is hardcoded. A card shows n/a only when a value genuinely cannot be computed.

Card	Meaning	How it is measured
Files	Markdown notes	count of indexed .md files
Links	connections in the graph	resolved [[wikilinks]] / Markdown links
Folders	structure	folders that contain Markdown
Skills	reusable knowledge units	counted in real time: SKILL.md files under _CONHECIMENTO/skills, plus the external browse.sh total read from MASTER_SKILLS.md — so a brand‑new skill is picked up even before the index is regenerated
Contributors	who writes the brain	unique authors from git history (git log); n/a if the folder is not a git repo. This measures commit authors, not who pushed — never a fixed number
Orphans	isolated notes	nodes with degree 0 (no resolved link in or out)
Words	volume of knowledge	real sum of words across all notes (frontmatter and code blocks excluded)
Messages	mailbox activity	.md messages in a _CORREIO folder, if one exists; otherwise n/a
Brain days	how old the brain is	days since the first git commit; n/a if not a git repo

Brain Master Dashboard

A panel with stats about the machine hosting the brain (CPU model and cores, CPU load, RAM) plus Brain size and a brain growth estimate.

Brain size is the total weight of the loaded brain folder — the sum of the files inside that vault, measured recursively on the server and cached for ~60 s. It is not the disk space of the whole computer, and it shows n/a when no folder is loaded.

The brain growth figure is a rough estimate based on average note size — local and informational, not a promise of infinite storage. Persistent, expandable memory comes from disk and git, not from magic.

Packaging

To share the app without leaking anything:

1. Copy only the app files into a clean folder (server.js, public/, abrir-cerebro-vivo.bat, README.md). Keep public/assets/devs-foundation-logo.png in the package; branded graph exports depend on it.

2. Exclude logs/, data/, _BACKUPS/, node_modules/, any local config, and anything containing a real machine path.

3. Verify there are no private paths or secrets, e.g.:

   Select-String -Path <folder> -Pattern "C:\\Users|/home/<real-user>|token|password|secret" -Recurse

4. Zip it and list the contents to confirm.

Troubleshooting

• Port already in use — another instance is running, or set a different port: PORT=8788 node server.js.
• UI looks stale after an update — hard‑refresh the page; the HTML uses a cache‑busting version (?v=) that bumps when CSS/JS changes.
• Contributors / Brain days show n/a — the brain folder is not a git repository (expected).
• Messages show n/a — there is no _CORREIO folder in the brain (expected).
• Nothing is indexed — check the Brain folder path and that it contains .md files.
• Sync errors — open the Logs window; every git step and error is shown there, never hidden.

---

_{N models. N devices. One brain. · Built for Dev's Foundation · github.com/Devs-Foundation}