# Gbrain Lite

> Lightweight personal knowledge base — markdown + YAML frontmatter structured notes with full-text search and cross-referencing for AI agents

- Skill: `gabrielmoreira/gbrain-lite` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/gbrain-lite`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/gbrain-lite/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/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

1. **Trigger check** — Book/person/concept/news mentioned in conversation → proactively check brain
2. **Search** — Full-text search in `brain/` directory (ripgrep/grep)
3. **Decide**
   - Existing entry → reference it, update if needed
   - No entry + important → create immediately
   - No entry + uncertain → ask user
4. **Create** — Write `brain/{type}/{slug}.md`
   - Slug: lowercase/hyphenated
   - Must include YAML frontmatter (title, type, date, tags, summary)
5. **Cross-reference** — Update `links` field in related entries
6. **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