goku

gbrain and mem0 Integration Notes

Properties3
descriptionPublic integration notes for the two memory layers: gbrain for vault retrieval, mem0 for episodic agent memory.
tagsgbrain, mem0, agents, memory
categorytech

7 min read

abstract

Public integration notes for the two memory layers: gbrain for vault retrieval, mem0 for episodic agent memory.

gbrain and mem0 Integration Notes

Companion note for unified-agent-memory-fabric.

Layer split

  • gbrain indexes the vault filesystem for semantic retrieval and graph-style knowledge access.
  • mem0 stores episodic memory: user preferences, stable agent memories, and cross-session facts.
  • Hermes skills document how agents should use each layer.

gbrain skill notes

GBrain — Knowledge Brain Skill

You have access to gbrain, a personal knowledge brain running on server that indexes the Obsidian vault (vault-write). It provides 85 tools across search, pages, links, timeline, code indexing, facts/emotion memory, and proactive context volunteering.

Connection

GBrain runs as an HTTP MCP server at http://127.0.0.1:8765/mcp (on server only). Access it via the hermes-mcp gateway or direct MCP client with OAuth 2.1 bearer tokens. Credentials are stored in ~/.hermes/mcp/gbrain.json (client_id + client_secret for client_credentials grant, scope: agent).

For direct server access:

# Token endpoint
curl -X POST http://127.0.0.1:8765/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=<ID>&client_secret=REDACTED&scope=agent'
 
# MCP endpoint (requires Accept: application/json, text/event-stream)
curl -X POST http://127.0.0.1:8765/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer REDACTED \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Core Workflows

Knowledge Retrieval (read)

  • search: Full-text keyword search across all pages. Fast, cheap.
  • query: Hybrid vector + keyword + multi-query expansion. For deep questions.
  • think: Multi-hop synthesis across pages + takes + graph. Produces cited answers with conflict/gap analysis. Use for complex reasoning.
  • get_page: Read a page by slug (supports fuzzy matching).
  • list_pages: List pages with sort/filter (recent, by type, by tag).
  • get_chunks: Get content chunks for a page.

Knowledge Creation (write)

  • put_page: Write/update a page (markdown with YAML frontmatter). Auto-chunks, embeds, reconciles tags/links/timeline.
  • add_tag / remove_tag: Manage page tags.
  • add_link / remove_link: Create/remove typed links between pages.
  • add_timeline_entry: Add dated timeline entry to a page.

Personal Insights

  • get_recent_salience: Pages ranked by emotional + activity salience. Use for “what’s going on with me lately”.
  • find_anomalies: Statistical anomalies in recent page activity (grouped by tag/type cohort).
  • recall: Query per-source hot memory (facts table) — events, preferences, commitments, beliefs.
  • extract_facts: Extract personal facts from a conversation turn into the brain.

Context Volunteering

  • volunteer_context: Push-based context — brain pages relevant to the current conversation WITHOUT being asked. Zero-LLM, confidence-gated. Use for proactive context injection in ongoing conversations.

Brain Health & Meta

  • get_brain_identity: Brain version, engine, page/chunk counts.
  • get_stats: Full brain statistics.
  • get_health: Embed coverage, stale pages, orphans.
  • run_doctor: Run full health checks.
  • advisor: Ranked “what to do next” — version drift, pending migrations, stalled jobs.

Code Intelligence

  • code_def: Find symbol definition (function, class, type, etc.)
  • code_refs: Find all references to a symbol.
  • code_callers: Who calls this symbol? (upstream impact)
  • code_callees: What does this symbol call? (downstream flow)
  • code_blast: Transitive callers grouped by depth (before editing ANY function).
  • code_flow: Trace request flow from entry point to side effects.

Schema Management (v0.40+)

  • list_schema_packs, get_active_schema_pack, schema_graph, schema_stats: Understand the brain’s type system.
  • schema_lint, schema_review_orphans: Quality checks on page types.

Background Jobs

  • submit_job: Submit background jobs (sync, embed, lint, import, extract, backlinks, autopilot-cycle).
  • list_jobs, get_job, get_job_progress: Monitor job status.
  • cancel_job, retry_job, pause_job, resume_job: Job lifecycle management.

Expert Finding

  • find_experts: “Who in my brain knows about ” — returns ranked person/company pages by expertise depth.

Best Practices

  1. Always search the brain before writing — avoid duplicate pages.
  2. Use think for complex multi-hop questions — it synthesizes across pages, takes, and the link graph.
  3. Before editing code, check code_callers and code_blast — understand impact.
  4. Use get_recent_salience for emotional/personal questions — standard search is optimized for factual retrieval.
  5. For proactive context, use volunteer_context — it surfaces relevant pages without being prompted.
  6. Batch operations via submit_job — sync, embed, lint, extract are heavy; don’t run them inline.

Quick Start

First call in any session:

  1. get_brain_identity — confirm connection
  2. get_recent_salience — see what’s active
  3. search or query — answer the user’s question

mem0 skill notes

name: mem0-universal description: > Read/write the shared mem0 episodic memory layer (self-hosted at goku.codes). All agents share the same mem0 namespace. Use when you need to remember something across sessions, recall past conversations, or check what other agents know. Always includes source_agent metadata on writes. platforms: [linux, macos, discord]

Universal Mem0 — Shared Agent Memory

You have access to the goku.codes self-hosted mem0 API. This is the shared episodic memory for ALL agents: Clawd (server gateway), Machine (discord), OpenCode (mac), and Hermes (anywhere). Memories written by one agent are visible to all others.

Connection

  • API URL: https://memory.example.com
  • Auth: X-API-Key header
  • Default User ID: goku
  • Default Agent ID: clawd (change to your agent name)

API Key

<MEM0_API_KEY>

⚠️ Inject via environment variable or hermes config. The key is stored on server at ~/.hermes/mem0.json.

Writing Memories

Always include source_agent in metadata to track which agent wrote each memory.

curl -X POST https://memory.example.com/memories \
  -H "X-API-Key: <MEM0_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "goku",
    "messages": [
      {"role": "user", "content": "I prefer tea over coffee in the morning"}
    ],
    "metadata": {
      "source_agent": "clawd",
      "source_session": "session-id-here",
      "timestamp": "2026-06-18T21:00:00Z"
    }
  }'

Metadata fields:

  • source_agent (REQUIRED): Agent name — clawd, machine, opencode, hermes-poke
  • source_session: Session/run ID for traceability
  • context: Brief context about why this memory was stored (e.g., “user stated preference”)
  • urgency: high | medium | low — how important this memory is

Searching Memories

curl -X POST https://memory.example.com/search \
  -H "X-API-Key: <MEM0_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "goku",
    "query": "What do I prefer for breakfast?",
    "limit": 5
  }'

Getting All Memories

curl -X GET "https://memory.example.com/memories?user_id=goku&page=1&page_size=20" \
  -H "X-API-Key: <MEM0_API_KEY>"

Deleting a Memory

curl -X DELETE "https://memory.example.com/memories/{memory_id}" \
  -H "X-API-Key: <MEM0_API_KEY>"

Agent-Specific Configurations

Clawd (server gateway)

  • API key configured in env or config
  • Default agent_id: clawd
  • Use for: gateway-routed memory, server-side operations

Machine (discord)

  • API key must be injected via environment variable
  • Agent ID: machine
  • Use for: discord user interactions, conversation memory

OpenCode (mac)

  • API key can be in .env or passed directly
  • Agent ID: opencode
  • Use for: coding session context, remembering user preferences

Hermes (anywhere)

  • Already has built-in mem0 via memory.provider: mem0 config
  • Uses mem0_search and mem0_conclude tools automatically
  • No skill needed — already configured in ~/.hermes/config.yaml

Best Practices

  1. Always set source_agent — this is the key metadata that makes memory “universal”. Without it, we can’t trace which agent wrote what.
  2. Search before write — avoid duplicate memories. If a similar memory already exists, consider updating it instead.
  3. Keep user_id consistent — always use goku as the default user_id unless storing memories for a different user.
  4. Add context in metadata — helps other agents understand WHY a memory was stored.
  5. Delete outdated memories — if a preference or fact has changed, clean up the old one.
  6. Cross-agent awareness — when responding to a user, check what other agents have stored about recent interactions.

Schema Notes

The self-hosted mem0 v1.1 stack:

  • Backend: Python FastAPI at port 8000 (proxied via nginx as api.memory.goku.codes)
  • Vector store: Supabase pgvector (same database as gbrain)
  • LLM: Groq (openai/gpt-oss-120b) for memory extraction/conversation
  • Embedder: sentence-transformers/all-MiniLM-L6-v2 (384d)
  • Auth: JWT + API keys (setup complete, auth disabled for trusted network)

Important correction

The working mem0 search route is /search, not /memories/search. If one proxy path still uses /memories/search, mem0_list may pass while mem0_search fails. That was one of the gateway bugs in the build.

For the gateway-level smoke tests that verify these tools end-to-end, see unified-agent-memory-gateway-smoketest.

Graph View

Backlinks

Recent Notes