How to use the GBrain Memory Setup agent skill

What the skill makes the agent do

The skill walks the agent through setting up a memory layer for an agent you already use. It is written to preserve the agent's identity, its native memory, its existing instructions and any unrelated configuration. The default path is local storage with keyword retrieval and no API keys.

The skill asks you to choose a search mode from a printed cost matrix before it continues. It then saves a test memory and reads it back to confirm the write worked. At the end it reports three things separately: whether the software installed, whether the agent's instructions were activated, and whether memory works across conversations.

• Installs GBrain from the garrytan/gbrain GitHub repository, after installing the Bun runtime if it is missing.
• Initialises a local PGLite database with no embeddings, using the keyless path.
• Checks existing installations and repairs partial or conflicting setups without reinitialising memory.
• Connects to an existing hosted brain instead, if you already have one.

Install the skill in Claude Code or the Claude apps

Download the skill ZIP from this page and unzip it. For a personal install, place the unzipped folder in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder instead.

In the Claude apps, you can upload the ZIP under Settings, then Capabilities, then Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings, Capabilities, Skills, then upload the ZIP

How to trigger the skill with natural requests

You do not need a special command. Ask the agent in plain words. The skill is matched to requests such as the ones listed in its trigger phrases. Give the agent the context it needs, such as which brain or which agent you mean, because the skill asks only for information it truly needs to choose a safe target.

• 'Set up GBrain for this agent.'
• 'Add gbrain to my agent.'
• 'Install gbrain into this agent workspace.'
• 'Initialize brain.'
• 'Connect my agent to my existing hosted GBrain.'

What happens during setup

For a new local install, the skill runs a Bun global install of GBrain from the GitHub repository and then a keyless initialisation. Before it changes anything, it inspects the current engine and configuration. If an installation already exists, it reuses it when it is healthy and reports problems rather than overwriting data.

When initialisation offers a search mode, the agent must show you the printed matrix and wait for your decision. The matrix shows model API costs separately from any harness subscription. Choosing a mode does not turn on paid APIs or automatic capture.

• Check status with gbrain engine status --json and gbrain engine status --probe.
• Install with bun install -g github:garrytan/gbrain#latest-stable.
• Initialise with gbrain init --pglite --no-embedding.
• Save a randomised test memory and read it back to confirm.

Safety notes: scripts, network and existing data

This skill runs shell commands and uses the network, including to fetch GBrain from GitHub. It is not a zero-knowledge, one-click install. Read the commands the agent proposes before you approve them, and do not approve a database choice you do not understand.

The skill warns against reinitialising memory and treats an existing database as something not to adopt by accident. It still says routing mistakes could affect existing data, so keep a backup of anything you cannot lose before you run it. Automatic capture, imports, connectors, schedules and paid enrichment are off unless you explicitly opt in.

• Requires the Bun runtime; the skill installs it first if it is missing.
• Optional Postgres or Supabase connection string if you choose Postgres. Keep it private.
• Optional Tailscale for remote MCP access; optional OAuth or private handoff for hosted access.
• Does not use an unrelated npm package named gbrain or bun add in your current project.

Tips for a smooth install

Decide before you start whether you want a local brain or a hosted one. The local path is simpler and needs no account. The hosted path skips local database setup but needs an owner to grant access and a private transfer of credentials.

If you use Postgres, expect a classic mode on a source with a checkout: the checkout is the source of truth, and agents save pages as committed files followed by gbrain sync. Direct saves need managed mode.

• Let the agent report software install, instruction activation and cross-conversation recall as three separate results; a pass on one does not imply the others.
• If the agent reports a partial or conflicting state, ask it to diagnose rather than reinitialise.
• Keep credentials out of file configuration; use the environment or private files instead.