ai, agents, deep dive,

Deep Dive: How garrytan/gbrain Turns Agent Memory into Seven Frozen Verbs

Cui Cui Follow Nov 15, 2026 · 7 mins read
Deep Dive: How garrytan/gbrain Turns Agent Memory into Seven Frozen Verbs
Share this

Companion to the hands-on tutorial: Give your coding agents a shared memory with garrytan/gbrain on Cui.Guru. The tutorial shows how to use it. This post explains why it is built this way.

garrytan/gbrain (about 33k stars per the GitHub API on 2026-11-15, MIT, TypeScript on Bun) is described in the README as “one brain for you and your company, read by every agent you use”. The source is large (src/core/engine.ts alone is about 2,900 lines), so this post follows one thread: how a single remember call becomes a fact that another agent can recall tomorrow, and what keeps the whole thing consistent.

The workflow in motion

Animated workflow: agent calls remember over MCP, dispatch runs the operation, the engine stores the fact, hybrid search recalls it next session, and the dream cycle keeps the index fresh

Architecture

The top of src/core/operations.ts says it is the “single source of truth for CLI, MCP, and tools-json”. Operation clusters live in src/core/ops/ (pages, search, takes, tags, links, timeline, facts and more) and are spliced into one ordered operations array. src/mcp/dispatch.ts is the “shared MCP tool-call dispatch” for both stdio and HTTP transports; its header explains it exists because drift between transports once caused reversed-args bugs.

The core design idea

Make the memory interface a protocol, then freeze it. src/core/verbs.ts declares seven verbs and a frozen version number:

// src/core/verbs.ts
export const MEMORY_VERBS_VERSION = 1;
export const VERB_NAMES = ['recall', 'remember', 'entity', 'synthesize', 'forget', 'context_pack', 'delta'] as const;

docs/protocol/MEMORY_VERBS_v1.md states the policy: every field name and its semantics in v1 are frozen forever; new optional params and response fields may be added; protocol_version rides every response; adding a verb is additive, not a version bump. The doc also says gbrain protocol --json emits input schemas from the live operation definitions, so doc and code cannot drift, and that any other memory server can certify against it with gbrain protocol conformance --target <endpoint>.

Verbs are ordinary operations

A verb is not a special code path. It is an Operation with verb: true, which means it inherits scope checks, source isolation and fail-closed remote behaviour. Here is forget, trimmed:

// src/core/verbs.ts
const forget: Operation = {
  name: 'forget',
  idempotent: true,
  description: 'Expire a remembered fact by its fact_id (never a page slug). Idempotent; the audit trail is kept.',
  params: { id: { type: 'string', required: true, description: 'fact_id from remember or recall.' }, /* ... */ },
  mutating: true,
  scope: 'write',
  verb: true,
  annotations: { title: 'forget (expire a fact)', destructiveHint: true, idempotentHint: true },

Note the design choices: forgetting expires a fact rather than deleting it (the audit trail stays), it is idempotent, and a bad id returns an error whose suggestion tells the agent to pass the id from remember or recall. The header of verbs.ts says errors carry enumerated codes plus a populated suggestion “agents read it and self-correct”.

Provenance is part of the write contract

remember takes fact, entity and provenance. Its callShape string is returned to a caller that sends a wrong parameter:

// src/core/verbs.ts
const REMEMBER_CALL_SHAPE = 'A valid call: {"fact": "<one claim>", "entity": "<subject-slug>", "provenance": "<where you learned it, with the date>"}; several: items: [{fact, entity, provenance}, ...]. provenance (where the fact came from) is required.';

The input kind enum is frozen at five values: event, preference, commitment, belief, fact. Responses may also return idea, kept as a separate constant so the input freeze cannot drift.

One catalog, three surfaces

An agent with a small tool budget should not face the whole catalog; the source calls this the “85-tool wall” complaint. src/mcp/surface.ts defines three modes: verbs (exactly the seven frozen verbs), starter (a curated daily-driver set: the seven verbs plus common page, search and job operations) and full (everything, the default). The header describes two-layer, fail-closed enforcement: the tool list is filtered, and dispatch receives the same allowed set so a hidden op stays uncallable even if a client guesses its name. On the HTTP transport the server surface is a ceiling, and each client gets the narrower of that and its own setting.

Search: two arms fused by rank

src/core/search/hybrid.ts opens with its pipeline: keyword and vector search, then reciprocal rank fusion, normalize, boost, cosine re-score, dedup.

// src/core/search/hybrid.ts
// RRF score = sum(1 / (60 + rank_in_list))
// Compiled truth boost: 2.0x for compiled_truth chunks after RRF normalization
export const RRF_K = 60;
const COMPILED_TRUTH_BOOST = 2.0;

rrf-page-fusion.ts explains a subtle choice: votes are per page (source_id, slug), not per chunk, so a page that two arms agree on is not split across several fusion entries. Keyword search works with no API key, which is why the keyless start is real; vectors arrive when you configure embeddings.

Two engines behind one interface

BrainEngine in src/core/engine.ts carries readonly kind: 'postgres' | 'pglite'. pglite-engine.ts and postgres-engine.ts implement it, which is how the same brain runs as an in-process local database for a first install and as Postgres for a shared deployment. The cost, per the tutorial, is that PGLite allows one process at a time.

An overnight maintenance cycle

src/core/cycle.ts centralizes maintenance in runCycle(), shared by gbrain dream, the gbrain autopilot daemon and a queue handler. Its introductory comment sketches the original nine-stage pipeline (lint, backlinks, sync, synthesize, extract, patterns, emotional weight, embed, orphans); the current ALL_PHASES list has additional stages, and phase selection and configuration decide which run. The ordering principle holds: file fixes come first so the database sync picks them up. Coordination uses a database lock row with a 30-minute TTL on Postgres, and a file lock on PGLite.

Takeaways

  • Freeze the interface, not the implementation. Seven verbs and a version number let any harness depend on memory without caring how search improves.
  • One definition, many transports. The shared Operation catalog reduces schema and handler drift across the CLI, stdio and HTTP.
  • Make errors teach. Enumerated codes with a suggestion let agents fix their own calls.
  • Separate discovery from access. Surface modes advertise a compact tool list while fail-closed dispatch governs what is callable; a bare serve still defaults to full.
  • Keyless is a feature. Keyword retrieval first, with vectors and synthesis as opt-in layers.

Want a memory layer like this wired into your own agents? Get in touch.

Join Newsletter
Get the latest news right in your inbox. We never spam!
Cui
Written by Cui Follow
Hi, I am Z, the coder for cuizhanming.com!

Click to load Disqus comments