Gbrain Lite

GBrain Lite — Lightweight Personal Knowledge Base

> Organize books, people, concepts, and news items from conversations into a searchable, cross-referenced markdown knowledge base.

Workspace

• Knowledge base directory: brain/
• Subdirectories by type: books/ people/ meetings/ ideas/ articles/ projects/ news/
• One entry = one .md file
• News entries by date: news/YYYY-MM-DD/

Workflow

• Trigger check — Book/person/concept/news mentioned in conversation → proactively check brain
• Search — Full-text search in brain/ directory (ripgrep/grep)
• Decide
• Existing entry → reference it, update if needed
• No entry + important → create immediately
• No entry + uncertain → ask user
• Create — Write brain/{type}/{slug}.md
• Slug: lowercase/hyphenated
• Must include YAML frontmatter (title, type, date, tags, summary)
• Cross-reference — Update links field in related entries
• Sync — Keep key entry index in agent memory

Rules

• Don't dump long content directly into agent memory — prefer brain
• Don't create entries without title and date
• Don't skip the summary field — search and listing depend on it
• Don't manually write updated — it auto-updates on save
• News entries must use item_id as dedup key (format: github:owner/repo / hn:12345 / arxiv:url)
• Don't do full overwrite updates on existing entries — use targeted patches

Validation

• [ ] New entry has complete frontmatter (title, type, date, tags, summary)
• [ ] Full-text search finds the new entry
• [ ] News entries contain item_id + first_seen + star_history (GitHub entries)
• [ ] Agent memory usage below 90%, otherwise trigger distillation to brain

Pitfalls

Brain vs Memory confusion

• Symptom: Long-form content consumed all agent memory space
• Root cause: Everything dumped into memory instead of brain
• Fix: >500 chars → brain entry; memory only keeps index pointers. (Fixed: 2026-05-12)

Missing item_id on news entries

• Symptom: Duplicate news entries accumulate, dedup impossible
• Root cause: Agent skipped item_id field when creating news entries
• Fix: Always include item_id for news entries, validated in creation workflow

References

• references/garry-tan-gbrain-inspiration.md — GBrain system design reference