Grug Brain.mcp
MCP server for persistent memory. grug remember thing so not forget.
Ask AI about Grug Brain.mcp
Powered by Claude · Grounded in docs
I know everything about Grug Brain.mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.
Architecture
Claude Code grug serve (background service)
| |
v SQLite FTS5
grug --stdio Git sync
| File indexing
+--- unix socket ---+ Background timers
Two modes in one binary:
grug serve-- background server (brew service). Owns the SQLite database, runs git sync timers, indexes files. Listens on~/.grug-brain/grug.sock.grug --stdio-- thin MCP client for Claude Code. Forwards every tool call to the running server over the Unix socket. Near-zero startup time (~1ms).
The server runs as a launchd agent (macOS) or systemd user service (Linux). Install it with:
grug serve --install-service
Brains
A brain is a directory of markdown files. You split them however you want.
[
{
"name": "self",
"dir": "~/.grug-brain/self",
"writable": true,
"primary": true
},
{
"name": "hive",
"dir": "~/.grug-brain/memories",
"git": "git@github.com:you/grug-memories.git",
"writable": true,
"syncInterval": 60
},
{
"name": "docs",
"dir": "~/repos/project-docs",
"flat": true
}
]
Config lives at ~/.grug-brain/brains.json. First run creates it for you.
| Field | Required | Default | Description |
|---|---|---|---|
name | yes | Unique identifier | |
dir | yes | Directory path. ~ works. | |
primary | no | false | Where writes land when you don't specify a brain. One brain only. |
writable | no | true (false if flat) | Controls grug-write and grug-delete access |
flat | no | false | No category subdirectories. The brain name becomes the category. |
git | no | null | Remote URL for sync |
syncInterval | no | 60 | Seconds between git push/pull |
source | no | null | Origin URL for /ingest refresh |
refreshInterval | no | null | Seconds between doc refresh. Read-only brains only. Minimum 3600. |
Tools
grug-write stores a memory. Goes to the primary brain unless you say otherwise.
grug-write category:"feedback" path:"no-mocks" content:"don't mock the database"
grug-write brain:"hive" category:"feedback" path:"no-mocks" content:"..."
grug-search hits every brain at once. Results carry a tag showing where they came from.
grug-search query:"sqlite"
> [hive] loopback/powersync-patch-vs-upsert.md
> [research] bun/runtime-sqlite.mdx
> [docs] connect-bun-sqlite.mdx
grug-read lets you drill into any brain.
grug-read # list all brains
grug-read brain:"docs" # categories
grug-read brain:"docs" category:"api" # files
grug-read brain:"hive" category:"feedback" path:"no-mocks" # content
grug-recall catches you up on a brain. Writes a full listing to recall.md and returns the highlights.
grug-recall # primary brain
grug-recall brain:"hive" # pick one
grug-delete removes a file. Writable brains only.
grug-delete brain:"self" category:"scratch" path:"old-note"
grug-config adds and removes brains without restarting the server.
grug-config action:"list"
grug-config action:"add" name:"tailwind" dir:"~/.grug-brain/tailwind" flat:true
grug-config action:"remove" name:"tailwind"
grug-sync triggers a git sync for one or all brains.
grug-sync # sync all brains with git remotes
grug-sync brain:"hive" # sync one brain
grug-dream does maintenance. Commits pending changes across writable brains, surfaces git conflicts, finds cross-links between memories, flags anything that's gone stale.
/dream
/loop 30m /dream
Conflicts
Two machines edit the same file between syncs. Grug saves your local version to conflicts/ in the primary brain with frontmatter recording the original path, brain, hostname, and date.
Dream tells you when conflicts exist. Three steps to fix one:
- Read the conflict file
- Write the correct version to the original path
- Delete the conflict entry
File Layout
~/.grug-brain/
brains.json
grug.db
grug.sock
grug.pid
launchd-stdout.log
launchd-stderr.log
self/
scratch/
i-am-alive.md
memories/
feedback/
loopback/
conflicts/
Service Management
macOS (launchd)
# Install / reinstall
grug serve --install-service
# Restart
launchctl kickstart -k gui/$(id -u)/com.grug-brain.server
# Stop
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.grug-brain.server.plist
# Logs
cat ~/.grug-brain/launchd-stderr.log
Linux (systemd)
# Install / reinstall
grug serve --install-service
# Restart
systemctl --user restart grug-brain.service
# Stop
systemctl --user stop grug-brain.service
# Logs
journalctl --user -u grug-brain.service
License
MIT
