mirror of
https://github.com/garrytan/gbrain.git
synced 2026-07-27 22:15:33 +00:00
docs(designs): add COMMUNITY_IDEAS ledger from open-PR backlog triage (#1969)
Curated, high-bar diary of the valuable ideas surfaced by the community-PR wave, grouped into 10 themes with contributor credit and OPEN/CLOSED/HELD status, so good thinking survives PR closure. Captured during a full triage + hygiene pass over the open-PR backlog. Pure docs; no code impact. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
b31de6613e
commit
7cf46230e5
@@ -0,0 +1,367 @@
|
||||
# Community Ideas Ledger
|
||||
|
||||
> A diary of the **valuable ideas** surfaced by the community-PR wave, kept so that
|
||||
> good thinking survives even when the PR that carried it is closed. gbrain moves
|
||||
> fast and the maintainer's "cathedral" rewrites supersede most individual PRs —
|
||||
> but the *idea* behind a closed PR is often still worth something.
|
||||
>
|
||||
> **Bar for this file:** an idea only earns a line if it is (a) still live on
|
||||
> master and (b) genuinely valuable to gbrain users. **Graduating an idea to
|
||||
> `TODOS.md` is a higher bar still** — it must serve the North Star (next-Postgres-
|
||||
> for-memory: widest coverage, best-for-the-most-at-the-least) and be worth a
|
||||
> maintainer-owned implementation. Most lines here will never graduate. That's fine.
|
||||
>
|
||||
> Status legend: **OPEN** = PR still open as a real merge candidate · **CLOSED** =
|
||||
> PR closed, idea captured here · **HELD** = strategic, awaiting maintainer call.
|
||||
> Provenance is credited to the contributor; scrub real private-network names per
|
||||
> the repo privacy rule when anything here graduates to a public artifact.
|
||||
|
||||
_Generated from a full triage of the open-PR backlog (436 community PRs), 2026-06-07._
|
||||
|
||||
---
|
||||
|
||||
## 1. Internationalization — non-English brains are second-class
|
||||
|
||||
The single biggest coverage gap for "serve a billion people." Several independent
|
||||
contributors hit the same walls.
|
||||
|
||||
- **Configurable FTS language** (#580/#581/#582, @rafaelreis-r) — **OPEN, high.**
|
||||
Every `to_tsvector`/`tsquery` is hardcoded `'english'` (query side, trigger side,
|
||||
and no reindex path), so non-English brains run every search through the English
|
||||
stemmer. A coherent 3-PR set: `GBRAIN_FTS_LANGUAGE` config → migration recreating
|
||||
triggers with the chosen language → `gbrain reindex-search-vector` to change it
|
||||
post-install. **Strongest i18n candidate to graduate.**
|
||||
- **Full-Unicode slugs** (#782, @tamagodo-fu; #514 zh, @JimmyJiang67) — **HELD, high.**
|
||||
CJK slugs already work (`CJK_SLUG_CHARS`); generalize to all scripts (Cyrillic,
|
||||
Devanagari, Hangul, …) and widen the remaining ASCII-only validators so non-ASCII
|
||||
slugs flow end-to-end instead of being generated then rejected. #514 also carries a
|
||||
corpus-driven `relationships-zh.json` verb dictionary for `inferLinkType` — a
|
||||
reusable artifact for Chinese relationship typing.
|
||||
- **CJK entity extraction** (#1637, @alkalide) — **OPEN, high.** Mention extraction is
|
||||
ASCII-only (`TOKEN_RE`, `MIN_NAME_LENGTH=4`), so 2–3 char Chinese/Japanese/Korean
|
||||
names are invisible to the gazetteer (there's an in-code TODO acknowledging it).
|
||||
CJK detection + lower min-length + single-token pure-CJK titles + substring pass.
|
||||
|
||||
## 2. Reliability — the daily-driver failure modes
|
||||
|
||||
Recurring, production-observed failures. Many are tiny fixes with outsized impact;
|
||||
these are the densest source of real bugs in the whole backlog.
|
||||
|
||||
- **Embedding egress waste** (#347/#460, @notjbg) — **OPEN, high.** `getChunks` does
|
||||
`SELECT cc.*`, shipping the ~6KB pgvector embedding that `rowToChunk` immediately
|
||||
discards — ~19–22 GB/day egress on a busy Supabase brain. Enumerate the columns;
|
||||
add a CI guard. (#460 dup of #347.)
|
||||
- **Body-keyed embedding reuse** (#1424, @defenestrate2) — **OPEN, high.** Markdown
|
||||
import re-embeds byte-identical chunks that merely shifted position, turning a
|
||||
cosmetic edit into ~99K wasted re-embeds. Reuse by chunk-text hash like the code
|
||||
path already does; add `--force` + a no-hash sentinel.
|
||||
- **`embed --stale` full re-pull** (#775, @kyledeanjackson) — **CLOSED (partial on
|
||||
master), high.** Re-pulled all chunks every cycle (~3TB/mo egress); steady-state
|
||||
brains should do near-zero work. Master added a `countStaleChunks` early-exit;
|
||||
verify it fully closes this.
|
||||
- **Config round-trip storm** (#1694, @Omerbahari) — **OPEN, high.** A single query
|
||||
fires ~85 serial single-key config `SELECT`s — invisible on PGLite, ~85 network
|
||||
RTTs on a remote pooler. Batch + cache `getConfig` (`getConfigMany`).
|
||||
- **cgroup-aware worker sizing** (#1244, @tyler3k1) — **OPEN, high.** `defaultWorkers()`
|
||||
sizes from `os.totalmem()` (host RAM), so containerized installs (Railway/Fly/Render/
|
||||
Cloud Run/ECS) oversize the pool and get OOM-killed mid-import. Use
|
||||
`process.constrainedMemory()`.
|
||||
- **Linux memory-pressure throttle** (#556, @chengzehsu) — **OPEN, high.** `os.freemem()`
|
||||
is `MemFree` (excludes reclaimable cache), so healthy containers reject every batch
|
||||
job. Read `MemAvailable` from `/proc/meminfo`.
|
||||
- **propose_takes never caches empties** (#1218 @AdityaRajeshGadgil / #1760 @notjbg) —
|
||||
**OPEN, high.** A valid `[]` extractor result writes no cache row, so unchanged pages
|
||||
re-spend extractor tokens every ~5min cycle (57,885 calls/11 days observed). Sentinel
|
||||
row keyed on `(source_id, page_slug, content_hash, prompt_version)`.
|
||||
- **Prompt-cache opt-in on hot paths** (#1761, @notjbg) — **OPEN, high.** Only ~4.9% of
|
||||
input tokens hit the Anthropic prompt cache because the highest-volume cycle/extraction
|
||||
call sites don't set `cacheSystem:true` despite gateway support. One-line opt-ins.
|
||||
- **Autopilot reliability cluster** (#232 @ianderse, #464/#465 @notjbg, #289 @RyanAlberts,
|
||||
#477 @vinsew, #1935/#1936 @mdcruz88, #1906/#1891 @rayers/@jalagrange) — **OPEN, high.**
|
||||
A family of distinct live bugs: argless `engine.connect()` wipes saved config and
|
||||
crash-loops under launchd; `cwd=/` wrappers miss `brain/.env`; mtime-only lock probing
|
||||
blocks respawn for 10min after OOM; no backoff on the 5-failure suicide cap;
|
||||
disconnect-before-connect `reconnect()` bricks the engine on a transient blip; config
|
||||
accessors lack the retry wrapper. **Pick the best fix per layer and land as a wave.**
|
||||
- **lint `--fix` corrupts mid-doc fences** (#1417 @trinh-macbook, #1597 @chungty) —
|
||||
**OPEN, high.** Detector/fixer regex disagree, so `lint --fix` strips the closing fence
|
||||
of mid-document ```` ```markdown ```` blocks and autopilot re-corrupts the page every
|
||||
cycle. Only unwrap whole-page fences.
|
||||
- **backlinks worker defaults to `fix`** (#1853 @choomz; #1027 @sliday; #495 @23salus) —
|
||||
**OPEN, high.** Empty-payload backlinks jobs default to `action='fix'`, silently
|
||||
rewriting tracked markdown ("Referenced in" bullets) on every sync→embed→backlinks
|
||||
chain (129 files/day in the wild). Default to `check`; require explicit opt-in. Also
|
||||
fixes a duplicate-line accumulation bug.
|
||||
- **`DATABASE_URL` hijack** (#1884, @awilkinson) — **OPEN, high.** A co-located app's
|
||||
generic `DATABASE_URL` silently overrides the configured brain (wrong DB, or
|
||||
auto-migrates it). Fix precedence: `GBRAIN_DATABASE_URL` > config.json > `DATABASE_URL`.
|
||||
- **Engine-switch strips config** (#1088, @samchaudhary) — **OPEN, high.** `migrate --to`
|
||||
rewrites config to just `{engine,url}`, dropping `embedding_model`/`dimensions`/keys;
|
||||
migration "succeeds" but new embeds break.
|
||||
- **Re-init silently corrupts the brain** (#1060, @vincedk-alt) — **OPEN, high.** Flag-less
|
||||
re-init ignores persisted `embedding_model`/`dimensions` and writes a wrong-shape
|
||||
OpenAI-1536 brain before the dim-check catches it.
|
||||
- **IPv6-only direct URL** (#1006, @diazMelgarejo) — **OPEN, high.** `deriveDirectUrl`
|
||||
turns a Session-Pooler URL into an IPv6-only host, ECONNREFUSED on IPv4-only networks
|
||||
(the majority). Return null for pooler URLs.
|
||||
- **HOME-isolation in tests** (#205/#517/#534 @orendi84, #434 @lloydarmbrust) — **OPEN,
|
||||
high.** The E2E suite spawns `gbrain init/import` against the developer's real
|
||||
`~/.gbrain/config.json`, clobbering their live DB URL+keys. Isolate HOME to a tmpdir.
|
||||
*(A footgun that bites contributors of this very repo.)*
|
||||
- **dim-aware embed write target** (#1263, @DmitryBMsk) — **OPEN, high.** `upsertChunks`
|
||||
always writes the legacy `embedding vector(1536)` column, so brains on an alternate
|
||||
column (`embedding_ze halfvec(2560)`) fail with dim-mismatch on every write.
|
||||
- **Oversized chunks silently unembedded** (#1675, @lubos-buracinsky) — **OPEN, high.**
|
||||
The code chunker emits giant literals/template strings whole; the embedder rejects
|
||||
them and they vanish from semantic search. Cap chunk size so they stay embeddable.
|
||||
- **Token-vs-char truncation** (#557 @chengzehsu, #990 @mgunnin, #1180 @kkroo,
|
||||
#1281 @mmekkaoui, #1947 @100menotu001) — **OPEN, high.** The embed path truncates by
|
||||
chars (`MAX_CHARS`) not tokens, so dense pages still exceed the 8192/300K-token ceiling
|
||||
and loop forever on HTTP 400 with `embedded_at` never cleared; `isTokenLimitError`
|
||||
misses OpenAI's real error string; llama-server's 32-input limit isn't capped; and
|
||||
`--catch-up`'s unbounded budget overflows the 32-bit `setTimeout` and aborts after one
|
||||
batch. A "make embedding backfills never silently wedge" cluster.
|
||||
|
||||
## 3. Search & retrieval quality
|
||||
|
||||
- **Keyword search ignores page titles** (#1646, @jeades) — **OPEN, high.** `searchKeyword`
|
||||
ranks only chunk `search_vector`, never `pages.search_vector` (weight-A titles), so an
|
||||
exact-title `gbrain search` returns nothing while `query` finds it. High-impact, tiny.
|
||||
- **`code-def` misses most OO symbols** (#1628, @rayers) — **OPEN, high.** `DEF_TYPES`
|
||||
omits method/constructor/field/struct/protocol, so `code-def` returns 0 for most
|
||||
object-oriented code. Root-cause fix in `normalizeSymbolType` + `DEF_TYPES`.
|
||||
(Prefer over #1701's fallback-only approach.)
|
||||
- **doc-comment column is wired but dead** (#520, @Evode-Manirahari) — **OPEN, high.** FTS
|
||||
weights `content_chunks.doc_comment` above chunk text but the column is never populated.
|
||||
Extract JSDoc/docstrings per symbol via AST and thread through import.
|
||||
- **autocut weak-top collapse** (#1863, @rayers) — **OPEN, high.** The fresh autocut
|
||||
feature (#1682) normalizes the rerank gap by the top score, so a weak top (0.317→1.0)
|
||||
looks like a confident cliff and rare cross-source queries collapse to 1 result. Add a
|
||||
`minTopScore` floor.
|
||||
- **Graph-hop wikilink rerank** (#717, @gwanghoon91) — **HELD, high.** Zero-token
|
||||
score-shapers (graph-hop wikilink rerank + query-token disambiguation) claimed
|
||||
+2.6/+2.8pt P@5/R@5 on BrainBench. Worth re-evaluating against the new retrieval
|
||||
cathedral's ranker rather than merging the old diff.
|
||||
- **Effective-date time filters** (#1706, @mvanhorn) — **OPEN, med.** `since`/`until`
|
||||
filter on `updated_at`, so content dated to the past but edited recently is mis-filtered;
|
||||
filter on `COALESCE(effective_date, updated_at, created_at)`.
|
||||
|
||||
## 4. Extraction & the knowledge graph
|
||||
|
||||
- **Obsidian wikilink → typed graph edges** (#87 @franmaranchello; alias/title/basename
|
||||
fallback #1188 @rwbaker) — **OPEN/HELD, high.** `[[wikilinks]]`/`![[embeds]]` are
|
||||
invisible to the graph. Materialize them as typed edges with alias (frontmatter
|
||||
`aliases:`), first-H1-title, and basename fallback resolution (path-equality-only gives
|
||||
~5.5% edge recall on real vaults). Master shipped global-basename (#1388); the alias/
|
||||
title fallbacks are the still-novel part.
|
||||
- **Schema-pack-aware link extraction** (#1547, @billy-armstrong) — **OPEN, high.** The
|
||||
link extractor's `DIR_PATTERN` is a frozen 16-prefix const that ignores pack-declared
|
||||
`path_prefixes`, so default-pack installs silently lose wikilinks to `person/`,
|
||||
`writing/`, `wiki/*`. Resolve prefixes from the active pack.
|
||||
- **DB-source extraction** (#1539, @afshaker) — **OPEN, high.** The cycle's extract phase
|
||||
only walks the filesystem, so DB-resident pages (imported transcripts, remote-DB brains)
|
||||
never get links/timeline and `brain_score` is capped. Thread `source:'db'`.
|
||||
- **source_id threaded through fs-walk extract** (#1719, @seungsu-kr) — **OPEN, high.**
|
||||
fs-walk extractors omit `source_id`, defaulting to `'default'`, so the `pages` INNER JOIN
|
||||
drops every row on non-default-source brains — silent 0 inserted.
|
||||
- **extract `--stale` permanent-lag loop** (#1791, @Nazim22) — **OPEN, high.** Pages last
|
||||
edited before the link-extractor version bump get stamped below the version threshold and
|
||||
re-flag every run (~97% pages permanently "stale"). Stamp `GREATEST(updated_at, versionTs)`.
|
||||
- **Plain-text NER for auto-link** (#1565, @donogeme) — **HELD, med.** Plain mentions of
|
||||
people (no `[[wikilink]]`) never become edges. The opt-in idea is right; the shipped
|
||||
implementation (capitalized-bigram regex, Western-names-only) is too crude — needs a
|
||||
real NER pass to clear the graph-integrity bar.
|
||||
|
||||
## 5. Providers & the gateway
|
||||
|
||||
The AI-gateway + recipes + `user_provided_models` system already absorbed ~40
|
||||
per-vendor embedding PRs (Ollama, Gemini, Azure, DashScope, DeepSeek, Zhipu, E5,
|
||||
bge-m3, Copilot, Composio, Kimi, LM Studio, Mistral, Hunyuan, MiniMax…). The
|
||||
*residue* worth keeping:
|
||||
|
||||
- **litellm proxy unusable for chat** (#1953 @miroslavb, #1938 @BKF-Gitty) — **OPEN, high.**
|
||||
The `litellm-proxy` recipe declares only an embedding touchpoint (no chat), so
|
||||
`chat_model=litellm:*` fails validation and `think` degrades to a misleading "set
|
||||
ANTHROPIC_API_KEY"; and `build-gateway-config` never folds `litellm/openrouter/together`
|
||||
keys, so configured proxy auth goes out unauthenticated. Plus user-provided custom-dim
|
||||
embeddings are double-false-rejected in preflight. **The general-OpenAI-compat-proxy
|
||||
story.**
|
||||
- **Matryoshka dims threading** (#1072 @mgandal, #1240 @mike7seven) — **OPEN, high.**
|
||||
Qwen3-Embedding returns its native dim (2560/4096) not the requested one because
|
||||
`dimensions:N` isn't threaded for the openai-compat path, hard-failing a 1536-dim brain.
|
||||
- **"Freeze provider at init, clear vectors on dim change"** (#100/#172, @niallobrien/
|
||||
@nbzy1995) — **CLOSED, med.** A safety insight worth keeping even though the provider
|
||||
PRs are superseded: persist+freeze the brain's provider/dim at init so a later env change
|
||||
can't silently corrupt the vector space; clear stale embeddings on an intentional change.
|
||||
- **China-region provider coverage** (#59 @Magicray1217, #1071 @AzeWZ) — **CLOSED, med.**
|
||||
Make DashScope/DeepSeek/Zhipu first-class recipes that honor `provider_base_urls` (the
|
||||
China-region endpoints) and provider batch limits — on-mission for global coverage.
|
||||
- **Amazon Bedrock native** (#1826, @naterchrdsn) / **Jina asymmetric retrieval**
|
||||
(#1930, @Whamp) — **HELD, high/med.** The maintainer pattern prefers the universal
|
||||
litellm-proxy over per-vendor native recipes, but Bedrock (AWS IAM credential chain) and
|
||||
Jina's asymmetric `input_type=document|query` are distinct enough to warrant a call.
|
||||
- **Local-first chat parity** (#1854/#1855/#1858 @starm2010, #1423 @pabloglzg,
|
||||
#1618 @punksterlabs) — **OPEN, high.** `FREE_LOCAL_CHAT_PROVIDERS` doesn't exist (only
|
||||
embed), brainstorm/cycle/takes hardcode `anthropic:claude-sonnet-4-6`, and the
|
||||
openai-compat `generateObject` path silently fails on providers that reject
|
||||
`json_schema`. The "run gbrain fully local" cluster.
|
||||
- **OpenRouter config key** (#1714 @tmchow), **OAuth bearer for AI providers**
|
||||
(#1312 @pabloglzg), **API-key files** (#570 @shawnduggan) — **OPEN, med.** Credential
|
||||
ergonomics: config-file key (not just env), externally-minted bearer tokens, and
|
||||
`OPENAI_API_KEY_FILE` so OAuth harnesses don't inherit a raw key in `process.env`.
|
||||
|
||||
## 6. Auth, federation & access control (security-adjacent)
|
||||
|
||||
These cluster into a real theme: **runtime access control for remote/multi-tenant MCP
|
||||
beyond prompt discipline.** Several are live security gaps (see the security list in the
|
||||
triage report) and should be treated as a coordinated design, not piecemeal merges.
|
||||
|
||||
- **Clamp remote source overrides** (#1372, @jlfetter1) — **OPEN, high, SECURITY.** A
|
||||
remote MCP caller can pass `source_id` (or `__all__`) to `query`/`get_page` to read
|
||||
sources outside their OAuth `allowedSources` — the param bypasses `sourceScopeOpts`
|
||||
(CWE-285). Clamp to token claims, fail-closed. **#1394 (get_page source_id) must land
|
||||
*with* this clamp, not before it.**
|
||||
- **Read-side prefix/federation enforcement** (#1860 @choomz, #1790 @colin-atlas,
|
||||
#470 @AdityaRajeshGadgil, #1508 @tim404x) — **OPEN, high.** `bound_slug_prefixes` is
|
||||
enforced on write but not read; exact `get_page` uses scalar `ctx.sourceId` while fuzzy
|
||||
uses the federation ladder; unqualified search can scan isolated `--no-federated` sources.
|
||||
Unify on one fail-closed visibility predicate across every read surface.
|
||||
- **Per-OIDC-user access tiers** (#789, @0x471) — **HELD, high, SECURITY.** Map verified
|
||||
OIDC end-users to `oauth_clients.access_tier` dispatch gates + shape filters — real
|
||||
runtime access control. Pairs with multi-agent MCP hardening (#1316, @chipoto69, HELD).
|
||||
- **Federated-read management CLI + admin UI** (#1592/#1601 @bitak1, #1558 @flamerged) —
|
||||
**OPEN, high.** No CLI/UI to inspect or change a client's `federated_read` scope (raw
|
||||
SQL only today). Atomic `array_append`/`array_remove` SQL to avoid read-modify-write
|
||||
races, plus an admin Sources tab.
|
||||
- **Pre-registration flow flags** (#894, @panda850819) — **OPEN, high, SECURITY.**
|
||||
`register-client` hardcodes `redirect_uris=[]`, making the SECURITY.md-recommended
|
||||
pre-registration (DCR-off) flow unusable for Claude.ai/ChatGPT connectors.
|
||||
- **RFC 9728 `resource_metadata`** (#1410, @rayers) — **OPEN, high.** HTTP MCP 401s omit
|
||||
the `resource_metadata` param the MCP auth spec + RFC 9728 require, so claude.ai/Cursor
|
||||
can't discover the auth server and never start OAuth.
|
||||
- **Server-enforced memory groups** (#1497, @oldmate99) — **HELD, med.** Audience-based
|
||||
read/write via `memory_groups` + client-to-group assignment — strategic for hosted
|
||||
multi-tenant, but overlaps the existing source-isolation model; a design call.
|
||||
|
||||
## 7. Security hardening (must not be lost)
|
||||
|
||||
- **Command injection in transcription** (#245, @aliceagent) — **OPEN, high, SECURITY.**
|
||||
`transcription.ts` shell-interpolates an agent-controlled `audioPath` into `execSync`
|
||||
ffprobe/ffmpeg/`rm -rf`. **Confirmed still present on master.** Switch to
|
||||
`execFileSync` arg arrays + `fs.rmSync`.
|
||||
- **Dotfile / skills-dir confinement** (#418/#419, @garagon) — **OPEN, high, SECURITY.**
|
||||
`.gbrain-source` walk-up trusts any ancestor dotfile (source hijack on shared hosts);
|
||||
`resolveWorkspaceSkillsDir` never canonicalizes (symlink escape). `lstat` ownership/
|
||||
symlink/world-writable checks + realpath containment.
|
||||
- **Destructive reclone gate** (#1705, @mvanhorn) — **OPEN, high, SECURITY.**
|
||||
`recloneIfMissing` does `rm`+rename over `src.local_path` without verifying it's
|
||||
gbrain-managed, so a re-pointed source can wipe a user's working tree. Gate behind
|
||||
`isManagedRecloneTarget()` + reject `..`. *(The maintainer's own #1960 is the canonical
|
||||
landing for this class — cross-check.)*
|
||||
- **CORS preflight asymmetry** (#983, @yashkot007) — **OPEN, high, SECURITY.** Preflight
|
||||
returns the full method/header surface unconditionally while the actual-request path
|
||||
gates on the allowlist — leaks allowed surface to non-allowlisted origins.
|
||||
- **jsonb double-encode corruption** (#1584 @warkcod, #597 @vinsew) — **OPEN, high,
|
||||
SECURITY/integrity.** Source-config and subagent writers `JSON.stringify` into a
|
||||
`::jsonb` cast — the exact postgres.js trap CLAUDE.md forbids; corrupts source config
|
||||
(freshness/autopilot) and breaks dream synthesize slug-collection on real Postgres.
|
||||
|
||||
## 8. Developer experience & platform reach
|
||||
|
||||
- **Windows / CRLF portability** (#1294 @xwang4-svg, #1149 @samporter-31, #1554 @Sanjays2402,
|
||||
#1396 @xuezhaolan) — **OPEN, high.** CRLF breaks frontmatter + skill-trigger parsing
|
||||
(CI is Ubuntu-only so it never surfaces), `/dev/stdin` doesn't exist, a POSIX postinstall
|
||||
one-liner hard-fails `bun install`, backslash bundle keys. A coordinated "first-class
|
||||
Windows" pass. *(A working Windows binary + CI target #180/#181 is the prerequisite for
|
||||
the full story.)*
|
||||
- **`.gbrainignore` / per-repo exclusion** (#1483 @eepaul; repo-local code filters
|
||||
#1011 @AndrewLauder; `--respect-gitignore` #1159 @jetsetterfl) — **OPEN, high.** Sync
|
||||
indexes every file with no ignore mechanism (`data/`, `*.parquet`, fixtures, vendored
|
||||
trees), bloating DB + embedding cost. gitignore-parity `.gbrainignore` + per-source
|
||||
`excludePatterns`. *(See also the maintainer's walker-prune work; #1942 prunes
|
||||
vendor/dist/build.)*
|
||||
- **Monorepo sub-path sources** (#774, @jeremyknows) — **HELD, high.** `--src-subpath`
|
||||
(split repo into git-root + logical-source axes) + `--exclude` so one repo can hold N
|
||||
sources at subdirs.
|
||||
- **MCP tool filtering** (#747, @joelwp) — **OPEN, high.** MCP advertises all ~51 ops to
|
||||
every consumer (~10K tokens of schemas, tool confusion); `GBRAIN_EXPOSED_TOOLS` filters
|
||||
the advertised surface.
|
||||
- **Install-method detection for upgrade** (#538, @brucek) — **OPEN, high.** The README's
|
||||
own recommended git-clone+bun-link install detects as `unknown`, so `gbrain upgrade`
|
||||
offers three dead ends including a wrong npm package.
|
||||
- **Runtime subagent defs** (#1282, @dcarolan1) — **OPEN, high.** The plugin loader
|
||||
validates `SubagentDefinition[]` at startup but the handler never reads
|
||||
`data.subagent_def`, so the persisted field is dead at runtime — callers must re-embed
|
||||
the full system body in every job.
|
||||
- **macOS Tahoe PGLite workaround** (#1671, @roysaurav) — **HELD, med.** PGLite's WASM
|
||||
engine crashes on macOS 26 (Apple Silicon); document the native Homebrew Postgres+pgvector
|
||||
fallback. Reader-valuable until the WASM crash is fixed upstream.
|
||||
|
||||
## 9. Capabilities & integrations (strategic — maintainer call)
|
||||
|
||||
These are net-new surfaces held for a product decision, not auto-closed.
|
||||
|
||||
- **Alternative engines** — SQLite/`bun:sqlite`+FTS5 single-file backend (#291, @mvanhorn)
|
||||
and Neo4j GraphBrain REST backend (#594, @pkyanam). Both conflict with the two-engine
|
||||
lockstep invariant and the Postgres-for-memory North Star, but the *zero-WASM single-file*
|
||||
install story (SQLite) is strategically interesting. **HELD.**
|
||||
- **Page versioning / soft-delete / read audit** (#573, @cropsgg) — **HELD, high.** Snapshots
|
||||
with provenance, soft-delete tombstones + hard purge, read-path audit treating edits as
|
||||
derivative works. Ambitious cathedral-scope; maintainer-owned territory.
|
||||
- **Configurable embedding dimension** (#1051, @vincedk-alt) — **HELD, high.** `schema.sql`
|
||||
hardcodes `vector(1536)`; read `embedding_dimensions` from config (default 1536). The
|
||||
canonical fix that dozens of local-provider PRs hack around. *(Pairs with #1263.)*
|
||||
- **Transcribe skill** (#1449, @RyanAlberts) — **OPEN, high.** Implements the empty
|
||||
video/audio branch of `media-ingest` (YouTube captions fast path + yt-dlp/whisper
|
||||
fallback), $0 by default. A genuine capability gap.
|
||||
- **iPhone backup importer** (#1733, @H4RR1SON) — **HELD, med.** Local-CLI-only importer
|
||||
for decrypted iPhone backups (contacts→person pages, iMessage→conversation pages); zero
|
||||
network, thin-client refused.
|
||||
- **Compounding dream phase** (#509, @durang) — **HELD, high.** An LLM "7th phase" that
|
||||
*creates* structure (orphan-mention people, knowledge gaps, concept-dup at cosine>0.92,
|
||||
decay, incomplete pages) vs the deterministic phases. Overlaps `enrich --thin`.
|
||||
- **Codex-OAuth for dream** (#977, @barronlroth) / **dream gateway + `migrate-embedding-dim`**
|
||||
(#1013, @cxbitz) — **HELD, high.** OAuth-backed chat for synthesis; a command to resize
|
||||
the vector schema + clear incompatible embeddings.
|
||||
- **Voice-extraction skill** (#300, @harjclaw) — **CLOSED, med.** Mine the user's outbound-
|
||||
email corpus already in the brain to build a queryable writing-voice profile so agents
|
||||
draft in the user's voice. Overlaps soul-audit.
|
||||
- **MCP put_page parity + DB→markdown reconciliation** (#438, @rayzhux) — **HELD, high.**
|
||||
A frontmatter-only safe auto-link mode for remote callers + `GBRAIN_BRAIN_ROOT` to render
|
||||
remote writes back to markdown so MCP writes reach the git source-of-truth. Touches the
|
||||
remote trust boundary — a design proposal, not a merge.
|
||||
- **Recipe discovery convention** (#1279, @ialmeida-jera) — **OPEN, med.** `~/.gbrain/recipes/`
|
||||
auto-discovery + `--external-dir`, loaded untrusted to keep the command-spawn boundary.
|
||||
- **Destructive-op audit trail + audit-factory** (#1069/#1070, @vincedk-alt) — **HELD, med.**
|
||||
Rotating JSONL forensic trail for hard-deletes + a shared `createAuditLogger` factory.
|
||||
|
||||
## 10. Doctor & brain-health observability
|
||||
|
||||
- **Queue dead-job visibility** (#1185, @ethanbeard) — **OPEN, high.** A collector can
|
||||
heartbeat green while all its jobs die in the worker (3561 dead in the wild) and doctor
|
||||
has zero view into the minions queue. Add a cross-cutting `[queue]` dead-jobs check.
|
||||
- **Orphan-metric alignment** (#1107 @colin477, #915 @xaviroblessarries, #1202 @rwbaker) —
|
||||
**OPEN, high.** `get_health` counts ingestion-by-design (`daily/`, briefings), soft-deleted,
|
||||
and hub pages as orphans, distorting `brain_score`; CLI `find_orphans` uses a *different*
|
||||
predicate than `getHealth`. Unify on one islanded predicate with sensible exclusions.
|
||||
- **doctor check-name registry drift** (#1839, @mvanhorn) — **OPEN, med.** Several emitted
|
||||
checks aren't registered in `doctor-categories`, printing `unknown check name` every run;
|
||||
the drift guard only scanned `doctor.ts`, missing `onboard/checks.ts` emitters.
|
||||
- **Honest stale-lock hint** (#1553, @Sanjays2402) — **OPEN, med.** doctor always says
|
||||
`gbrain sync --break-lock`, which silently no-ops on `gbrain-cycle` locks.
|
||||
|
||||
---
|
||||
|
||||
## Cross-cutting observations for the maintainer
|
||||
|
||||
- **The same bug was filed many times.** `extract_facts.entity_hints` missing an `items`
|
||||
schema came in ≥5 times (#812/#832/#847/#863/…, already fixed); the Postgres-singleton
|
||||
disconnect class a dozen+ times; sync no-op freshness, slug-casing, and the embedding-
|
||||
preflight false-reject each 5–15 times. A short "already fixed / known" note in the
|
||||
release notes or a CONTRIBUTING "before you file" list would cut the re-file rate.
|
||||
- **The recipe system is working as a pressure valve** — it correctly absorbed ~40 vendor
|
||||
PRs into config rather than code. The remaining provider asks are about *capabilities*
|
||||
the recipe schema doesn't yet express (asymmetric `input_type`, Matryoshka dims, per-item
|
||||
RPM caps, alternative credential groups), not new vendors.
|
||||
- **i18n (§1) and local-first chat (§5) are the two biggest "serve a billion" coverage
|
||||
gaps** the community is repeatedly hitting and the best candidates to graduate to TODOs.
|
||||
Reference in New Issue
Block a user