Obsidian Tool — a project brain that keeps itself current

Point it at the folders where your code lives. It builds an Obsidian vault that indexes every project, then refreshes itself on a schedule so the vault is never out of date.

Notes only. Your code is read, never written to, never moved.

What you get

• A note per project with the facts pulled straight off disk: git branch, commit count, last commit, uncommitted files, missing remote, detected stack, file counts, size, what changed most recently.
• A dashboard listing what needs attention — projects whose path has vanished, repos with no remote, uncommitted work, folders that exist on disk but are not in the index yet.
• Hub notes for every language, framework, platform, domain and status, each linking back to the projects that use it. That is what turns the graph from a gray blob into something you can read.
• Copies of each project's own docs (README.md, CLAUDE.md, docs/*.md), refreshed every run.
• Your Claude Code memories, mirrored out of ~/.claude and cross-linked to the projects they are about — so what the assistant remembers is visible next to the work itself. Optional, see Claude memory mirroring.
• A coloured graph. Colour groups are generated from your own categories, so they always match your setup.

Everything you write by hand is kept. Each note has a block like this, and the sync never touches what is inside it:

<!-- BRAIN:NOTES:START — your own writing, never overwritten -->
Whatever you want to say about this project.
<!-- BRAIN:NOTES:END -->

Requirements

• Windows 10/11, PowerShell 5.1 (built in) or later
• Obsidian to look at the vault
• git on PATH — optional, but without it you lose commit/branch/dirty facts

Install

git clone https://github.com/mslaughter1205/Obsidian-Tool.git
cd Obsidian-Tool
.\Install-Brain.ps1

It asks where the vault should live and which folders hold your projects, scans them, writes the config, registers a scheduled task, and runs the first sync.

Non-interactive:

.\Install-Brain.ps1 -VaultPath "D:\Notes\Brain" -ScanRoot "D:\code","D:\work" -VaultName "Brain" -IntervalMinutes 15

Flag	Meaning
-VaultPath	Where the vault folder goes
-ScanRoot	One or more parent folders, each holding a subfolder per project
-VaultName	Title of the dashboard note
-GithubUser	Shown on the dashboard, optional
-IntervalMinutes	How often the task runs, default 15
-TaskName	Scheduled task name, default BrainSync-<VaultName>
-NoTask	Skip the scheduled task, sync by hand
-NoMemoryMirror	Do not mirror Claude Code memories
-Force	Overwrite an existing projects.json

Then open the vault folder in Obsidian (Open folder as vault).

If PowerShell refuses to run the script, either right-click it and unblock it, or run:

powershell -NoProfile -ExecutionPolicy Bypass -File .\Install-Brain.ps1

Run a sync yourself

powershell -NoProfile -ExecutionPolicy Bypass -File "<vault>\_meta\brain-sync.ps1"

Add -WhatIfOnly to see what it would change without writing anything, -Quiet to silence it.

Configuration

Everything lives in <vault>\_meta\projects.json.

{
  "vaultName": "Brain",              // title on the dashboard
  "homeNote": "Brain",               // filename of the dashboard note
  "taskName": "BrainSync-Brain",     // shown on the dashboard
  "githubUser": "you",               // optional
  "mirrorClaudeMemory": true,        // mirror ~/.claude memories into the vault
  "claudeHome": "",                  // blank = %USERPROFILE%\.claude
  "scanRoots": ["D:\\code"],         // used to flag folders missing from the index
  "ignoreDirs": ["node_modules", "dist"],
  "categories": [
    { "folder": "01-Projects", "note": "Projects", "tag": "cat/projects", "blurb": "..." }
  ],
  "projects": [
    {
      "slug": "my-app",              // folder name inside the category folder
      "note": "My App",              // note filename and graph label
      "category": "01-Projects",     // must match a category folder above
      "path": "D:\\code\\my-app",    // where the real code lives
      "altPaths": [],                // fallbacks if the main path is gone
      "repo": "https://github.com/you/my-app",
      "status": "active",            // live | ready | active | wip | complete | spec | research | reference
      "client": "Internal",
      "blurb": "One line under the title.",
      "topics": ["Local Business"],  // your own domain hubs
      "aliases": ["myapp"]           // extra nicknames for memory matching
    }
  ]
}

Adding a project means adding an entry here. Anything under a scan root that is not listed shows up in the dashboard's Unfiled folders table, so nothing goes missing.

Categories are yours to define. Each one gets a folder, a hub note and its own colour in the graph; the colour groups are regenerated from this list on every sync.

Vault layout

<vault>\
  Brain.md                  <- dashboard (name comes from homeNote)
  01-Projects\
    Projects.md             <- category hub
    my-app\
      My App.md             <- the project note
      source-docs\          <- copies of that project's own markdown
  Topics\                   <- language / framework / platform / domain hubs
  Status\                   <- one hub per status
  Claude Memory\            <- mirrored memories (optional)
  _archive\                 <- your own dead-end notes, left alone
  _meta\
    brain-sync.ps1
    projects.json
    graph.template.json
    Sync Log.md
    last-run.txt

Claude memory mirroring

If you use Claude Code, the sync reads %USERPROFILE%\.claude\projects\*\memory\*.md plus your global CLAUDE.md, and writes a read-only copy of each into Claude Memory\. Each copy is tagged by kind (user, feedback, project, reference), linked to the projects it mentions, and listed on a hub note. Links between memories keep working, so the graph shows how your instructions relate to each other.

The copies are one-way. To change a memory, change it in .claude — the next sync overwrites the copy.

Turn it off with "mirrorClaudeMemory": false, or -NoMemoryMirror at install time.

Your vault holds copies of private notes — project details, client names, whatever you have told the assistant to remember. Keep it out of public repos.

Graph colours

The generated graph.json colours nodes by what they are: dashboard, category hubs, status hubs, one colour per category, one per topic kind (language / framework / platform / domain), memories by kind, source docs, archive.

Obsidian owns .obsidian\graph.json while it is running, so if it ever overwrites the file, the next sync puts the colour groups back — but only if the colour list came back empty, so your own tweaks survive.

Obsidian's core graph draws all links in one colour; per-link colours are not something the core graph supports.

Costs of a run

A sync walks every registered project (skipping node_modules, .git, build output), and writes a file only when its content actually changed. A 21-project vault takes about six seconds and writes nothing on an idle run, which keeps OneDrive, Dropbox and Obsidian Sync quiet.

Uninstall

.\Uninstall-Brain.ps1 -TaskName BrainSync-Brain

Removes the scheduled task and leaves your notes. Add -RemoveVault to delete the vault too; it asks you to type the folder name first.

Licence

MIT. See LICENSE.