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
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
servestill defaults tofull. - 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.
Click to load Disqus comments