Skip to main content
gbrain is a personal knowledge system that gives your agent persistent memory backed by Postgres with vector search. When installed on a managed agent, it’s wired as an MCP server — the agent gets 34 tools for storing, searching, and organizing knowledge.

​
Install

oc agent install my-agent gbrain
This runs through five phases:
PhaseWhat happens
AllocateCreates a managed Postgres database (with pgvector and pg_trgm extensions) for this agent
ProvisionClones gbrain from GitHub into the sandbox and installs dependencies
InitializeRuns gbrain init against the managed database to create the schema
WireAdds gbrain as an MCP server in the core’s config and restarts the gateway
VerifyRuns gbrain doctor to confirm the installation
Install is idempotent — re-running it after a partial failure is safe. The allocate phase skips if the database exists, provision skips if gbrain is already cloned, and so on.

​
What the agent gets

After install, the agent has these tool groups available:
GroupToolsWhat they do
Pagesput_page, get_page, delete_page, list_pagesStore and retrieve knowledge pages with Markdown content
Searchquery (vector + keyword hybrid), search (full-text)Find pages by meaning or keywords
Versionsget_versions, revert_versionPage version history
Graphadd_link, remove_link, get_links, get_backlinks, traverse_graphLink pages into a knowledge graph
Tagsadd_tag, remove_tag, get_tagsCategorize pages
Timelineadd_timeline_entry, get_timelineChronological event log
Filesfile_upload, file_list, file_urlAttach files to the knowledge base
Systemget_stats, get_health, sync_brainHealth checks and maintenance

​
Test it

After installing, message your agent on Telegram: 
You:   What new tools do you have?
Agent: I now have gbrain tools — search, put_page, timeline...

You:   Use gbrain to remember that our deployment target is Kubernetes on GCP
Agent: Saved to knowledge base.

You:   Use gbrain to search for deployment
Agent: You deploy to Kubernetes on GCP.

​
Managed database

The database that backs gbrain is managed by OpenComputer — you don’t need to provision or configure Postgres yourself. The database:
  • Lives outside the sandbox on a shared Postgres cluster
  • Survives instance restarts and sandbox recreation
  • Is preserved when you uninstall gbrain (your data isn’t deleted)
  • Is restored when you reinstall gbrain on the same agent
The connection URL is passed to gbrain via the MCP server’s environment config, not as a sandbox-level secret.

​
Uninstall

oc agent uninstall my-agent gbrain
This removes the MCP wiring from the core’s config and restarts the gateway. The agent loses access to gbrain tools, but the database is preserved. Reinstalling gbrain on the same agent reconnects to the existing data.

​
Debugging

Shell into the sandbox to inspect the installation: 
oc shell my-agent

# Check if gbrain is cloned
ls ~/.gbrain/src/cli.ts

# Check the MCP config (Hermes)
cat ~/.hermes/config.yaml

# Check the MCP config (OpenClaw)
cat ~/.openclaw/openclaw.json

# Check gateway logs for MCP connection status
tail -20 ~/.hermes/logs/gateway.log

# Run gbrain directly
~/.bun/bin/bun run ~/.gbrain/src/cli.ts doctor
Common issues:
  • “missing executable ‘bun’” in gateway logs — the MCP config needs absolute paths (e.g., /home/sandbox/.bun/bin/bun), not bare bun
  • Embedding failures — gbrain uses OpenAI for vector embeddings. If OPENAI_API_KEY is missing from the MCP env config, pages are stored but semantic search won’t work
  • Gateway didn’t pick up MCP — check if the gateway restarted after the wire phase. Run hermes gateway run --replace from the shell to force a restart