grug-brain
Persistent memory for LLMs. Point it at any number of directories, and grug indexes every markdown file into one FTS5 search index. Git sync keeps brains in lockstep across machines. Conflicts get caught, not lost.
Install
claude plugin add grug-brain
/install
/install builds from source, installs the background service, configures your brains, and verifies everything works. Run it again after plugin updates to pick up the new version.
Web Viewer
Once the server is running, open http://localhost:7777 (or check ~/.grug-brain/serve.port if the default port was taken).
Read mode
Brain switcher, category tree, memory list with live search, DOMPurify-sanitized markdown preview, and a global similarity graph (sigma.js + Fruchterman-Reingold layout). Live-reloads via SSE when any file changes on disk. Theme follows OS preference and can be toggled manually.
Edit mode (Plan 2)
Every memory opens in edit mode by default:
- Frontmatter form — name (required), description, tags (comma-separated).
- CodeMirror 6 editor — markdown body with
[[wikilink]] and #tag syntax highlighting.
- Wikilink + tag autocomplete — type
[[ to complete from memory titles; type # to complete from the tag index.
- Cmd-S / Save button — saves via
PUT /api/memory/{path} with ETag concurrency control.
- Conflict modal — stale-ETag 409 opens a 3-pane diff (yours / theirs / merged preview via jsdiff).
- Read/edit toggle — preserves scroll position and unsaved buffer.
- Unsaved-changes guard — blocks navigation with a confirm modal; fires
beforeunload for browser-tab close.
- Read-only brain banner — replaces the editor on non-writable brains.
Create / Delete / Rename (Plan 2)
- Create — click
+ next to any category, or use Cmd-K "New memory". First save prompts for a filename.
- Delete — toolbar button opens a confirm modal; type the memory name to enable the Delete button.
- Rename — toolbar button opens a rename modal;
rewrite_links=true by default rewrites every [[wikilink]] across the brain atomically.
Navigation panels (Plan 2)
- Backlinks panel — memories that wikilink to the current memory.
- Outline panel — heading tree parsed from the current buffer; click to scroll.
- Tag pane — all tags with counts; click to filter the memory list.
- Local N-hop graph — sigma.js graph of the N-hop neighborhood around the current memory.
Cmd-K palette (Plan 2)
Fuzzy quick-switcher over memories, categories, and commands:
| Command | Action |
|---|
| Toggle theme | Cycle light / dark / system |
| New memory | Open a blank draft editor |
| Rename | Open rename modal for current memory |
| Delete | Open delete confirm modal for current memory |
| Jump to category | Navigate to the first category |
Keyboard shortcuts
| Shortcut | Surface | Action |
|---|
| Cmd-S / Ctrl-S | Anywhere | Save current memory |
| Cmd-K / Ctrl-K | Anywhere | Open / close Cmd-K palette |
| Escape | Any open modal or palette | Close / dismiss |
| Enter / Space | Memory list item | Open memory |
| Arrow Up / Down | Palette list | Navigate results |
| Enter | Palette | Dispatch selected item |
| Tab / Shift-Tab | Any modal | Cycle focus within modal (trapped) |
All modals restore focus to the element that was active when the modal opened.
VoiceOver smoke-test checklist
Manual screen-reader verification — expected announcements with VoiceOver on macOS (Safari):
Edit save flow:
- Open a memory. VoiceOver should announce: "Memory body editor" when focus lands on the CodeMirror editor.
- Edit text and press Cmd-S. VoiceOver should announce the success toast: "Saved" (role=status, aria-live=polite).
- If there is a conflict, VoiceOver should announce "Conflict — file changed on disk" (dialog announced on open, focus moves to Cancel button).
Conflict modal:
- On modal open, VoiceOver announces dialog label "Conflict — file changed on disk".
- Tab cycles through Cancel, Reload theirs, Overwrite buttons.
- Press Escape — dialog closes, VoiceOver returns to the element that opened the modal.
Palette navigate:
- Press Cmd-K. VoiceOver announces: "Command palette, dialog" and focus moves to the search input ("Palette search, combobox").
- Typing filters the list; each selection change announces the item via aria-activedescendant.
- Press Escape — dialog closes, focus returns to opener.
Delete confirm modal:
- VoiceOver announces "Delete memory, dialog" on open.
- The confirm input has aria-describedby pointing to the target memory name.
- Typing the name enables the Delete button; VoiceOver announces the button state change.
Bundle audit (Plan 2)
Total web/vendor/ size: 1,035,743 bytes (1.01 MB)
