mirror of
https://github.com/garrytan/gbrain.git
synced 2026-07-28 14:59:47 +00:00
17c3c43783
* feat: frontmatter inference — zero-friction ingest for files without YAML headers
The platonic ideal of agentic retrieval is: you throw stuff in and it
becomes knowledge. No manual schema, no frontmatter templates, no YAML
ceremony. This PR makes that real.
## The Problem
9,655 files in a real 81K-page brain have no YAML frontmatter. They import
fine (gray-matter is forgiving), but with minimal metadata:
- type defaults to 'concept' for everything
- title is the slugified filename ('2010 04 13 Apr 13 Founders Mtg')
- No date, no source, no tags, no folder-aware typing
These pages exist in the DB but are poorly classified, which degrades
search ranking, type-filtered queries, and entity resolution.
## The Fix
### 1. Directory-aware inference engine (src/core/frontmatter-inference.ts)
A rules table maps path patterns to rich metadata:
Apple Notes/* → type: apple-note, date from filename, source: apple-notes
Apple Notes/YC/* → adds tag: yc
Apple Notes/Politics/* → adds tag: politics
daily/calendar/* → type: calendar-index, source: calendar
people/* → type: person, title from # heading
personal/therapy/* → type: therapy-session, date from filename
personal/reflections/* → type: reflection, title from # heading
writing/essays/* → type: essay, date from filename
companies/* → type: company, title from # heading
events/* → type: event, date from filename
(catch-all) → type: note, title from # heading
Each rule specifies:
- type: page type for brain schema
- datePattern: 'filename' (YYYY-MM-DD prefix), 'dirname', or 'none'
- titleStrategy: 'filename' (strip date), 'heading' (first #), 'filename-full'
- source: optional source tag
- tags: optional additional tags
Title extraction cleans up filenames (strips date prefix, converts dashes
to spaces, preserves existing capitalization). Heading extraction looks at
the first 20 lines for a # heading.
Fully deterministic. No LLM calls. No network. Same file → same frontmatter.
### 2. Inline inference in import pipeline (src/core/import-file.ts)
importFromFile() now runs inference automatically when a file has no
frontmatter. The synthesized frontmatter is applied to the in-memory
content before parseMarkdown runs, so the downstream pipeline sees
well-formed YAML. The file on disk is NOT modified — inference is
DB-only unless you explicitly run `gbrain frontmatter generate --fix`.
### 3. CLI command: gbrain frontmatter generate (src/commands/frontmatter.ts)
gbrain frontmatter generate /path/to/brain # dry-run preview
gbrain frontmatter generate /path/to/brain --fix # write to files
gbrain frontmatter generate /path/to/brain --json # machine output
The dry-run output shows:
- Total scanned / already have frontmatter / would generate
- Breakdown by inferred type
- First 10 examples with inferred metadata and matched rule
### 4. Tests (test/frontmatter-inference.test.ts)
35 tests covering:
- Date extraction from various filename patterns
- Title extraction from filenames and headings
- Inference for every directory rule (Apple Notes, people, therapy, etc.)
- Serialization with YAML-safe quoting
- Integration: applyInference prepends frontmatter correctly
- Rules: ordering, catch-all, specificity
## What this enables
1. `gbrain sync` now imports bare markdown with rich metadata automatically
2. `gbrain frontmatter generate --fix` writes frontmatter to 9,655 files
3. Future: sync can optionally write-back inferred frontmatter to git
4. Future: rules table is extensible — new directory conventions = one rule
## Adding new directory conventions
Edit DIRECTORY_RULES in src/core/frontmatter-inference.ts:
{ pathPrefix: 'recipes/', type: 'recipe', titleStrategy: 'heading' }
Rules are matched first-to-last, most specific prefix wins. The catch-all
(empty prefix) is always last.
## Real-world test output
Scanned: 81,479 files
Already have frontmatter: 71,824
Would generate: 9,655
By type:
apple-note: 5,861
calendar-index: 3,201
person: 56
therapy-session: 60
reflection: 12
essay: 33
...
All 35 tests pass.
* fix: import basename in frontmatter generate dynamic path import
src/commands/frontmatter.ts:437 calls basename(rootPath) as a fallback
when relative(brainRoot, rootPath) returns the empty string, but the
dynamic import a few lines above only destructures { resolve, relative,
join } from 'path'. typecheck failed with TS2304: Cannot find name
'basename', and any user invocation of `gbrain frontmatter generate
<single-file>` would have crashed at runtime with a ReferenceError.
The unit tests cover frontmatter-inference module's pure functions; no
test exercises the CLI single-file branch, so the bug slipped through.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore: bump VERSION 0.22.8 → 0.22.15 + CHANGELOG entry
Slot v0.22.15 per the queue allocator (other PRs claim v0.22.9–v0.22.14).
CHANGELOG entry written above v0.22.8 per the never-touch-shipped-entries
rule. bun.lock and llms-full.txt are unchanged (CLAUDE.md untouched, the
inference module and CLI command come in via the feature commit).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Wintermute <wintermute@garrytan.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>