feat(brain): structured wing/hall taxonomy + obsidian-compatible layout
Adds a two-dimensional address (wing, hall) to brain notes. A wing is a
topic domain (e.g. jepa-fx, hyperguild); a hall is one of a closed
vocabulary of memory types (facts, decisions, failures, hypotheses,
sources). Notes route to brain/wiki/<wing>/<hall>/<slug>.md with
wing/hall/created_at YAML frontmatter, making the directory a valid
Obsidian vault.
Changes:
- new package ingestion/internal/brain (NotePath, ValidHalls, Sanitise,
BuildWingIndex, BuildAllWingIndexes)
- api.WriteNote refactored to WriteNoteOptions; wing+hall routes to
brain/wiki/, otherwise falls back to brain/knowledge/ (legacy)
- search.Query → QueryOptions with optional Wing/Hall filtering; Result
carries wing/hall extracted from frontmatter or path segments
- MCP tools brain_write and brain_query gain optional wing/hall params
(hall enum-validated); new brain_index tool regenerates _index.md MOC
- POST /index REST endpoint mirrors brain_index
- brain_write auto-rebuilds the wing's _index.md after a wing+hall write
- scripts/migrate-brain-halls.sh migrates flat brain/wiki/{concepts,entities}/
into the new layout (dry-run by default, --commit applies)
All existing tests pass; new tests cover wing/hall write routing, scope
filtering, invalid hall rejection, _index.md generation, and migration
script paths.
Closes hyperguild#1.
This commit is contained in:
161
ingestion/internal/brain/index.go
Normal file
161
ingestion/internal/brain/index.go
Normal file
@@ -0,0 +1,161 @@
|
||||
package brain
|
||||
|
||||
import (
|
||||
"bufio"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// noteEntry is one row in a Wing _index.md.
|
||||
type noteEntry struct {
|
||||
Hall string
|
||||
Slug string
|
||||
Title string
|
||||
Created string
|
||||
}
|
||||
|
||||
// BuildWingIndex regenerates brain/wiki/<wing>/_index.md as a Map of
|
||||
// Content listing every note in that wing with its Hall and creation
|
||||
// date. Returns nil if the wing directory does not exist.
|
||||
func BuildWingIndex(brainDir, wing string) error {
|
||||
w := Sanitise(wing)
|
||||
if w == "" {
|
||||
return fmt.Errorf("invalid wing %q", wing)
|
||||
}
|
||||
wingDir := filepath.Join(brainDir, "wiki", w)
|
||||
if _, err := os.Stat(wingDir); os.IsNotExist(err) {
|
||||
return nil
|
||||
} else if err != nil {
|
||||
return fmt.Errorf("stat wing: %w", err)
|
||||
}
|
||||
|
||||
entries, err := collectWingEntries(wingDir)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
sort.Slice(entries, func(i, j int) bool {
|
||||
if entries[i].Hall != entries[j].Hall {
|
||||
return entries[i].Hall < entries[j].Hall
|
||||
}
|
||||
return entries[i].Slug < entries[j].Slug
|
||||
})
|
||||
|
||||
var b strings.Builder
|
||||
fmt.Fprintf(&b, "# %s\n\n", w)
|
||||
b.WriteString("| Hall | Note | Created |\n")
|
||||
b.WriteString("|------|------|---------|\n")
|
||||
for _, e := range entries {
|
||||
fmt.Fprintf(&b, "| %s | [%s](%s/%s.md) | %s |\n", e.Hall, e.Title, e.Hall, e.Slug, e.Created)
|
||||
}
|
||||
|
||||
dest := filepath.Join(wingDir, "_index.md")
|
||||
return os.WriteFile(dest, []byte(b.String()), 0o644)
|
||||
}
|
||||
|
||||
// BuildAllWingIndexes regenerates _index.md for every wing under brain/wiki/.
|
||||
func BuildAllWingIndexes(brainDir string) error {
|
||||
wikiDir := filepath.Join(brainDir, "wiki")
|
||||
ents, err := os.ReadDir(wikiDir)
|
||||
if os.IsNotExist(err) {
|
||||
return nil
|
||||
}
|
||||
if err != nil {
|
||||
return fmt.Errorf("read wiki: %w", err)
|
||||
}
|
||||
for _, e := range ents {
|
||||
if !e.IsDir() {
|
||||
continue
|
||||
}
|
||||
if err := BuildWingIndex(brainDir, e.Name()); err != nil {
|
||||
return fmt.Errorf("index %s: %w", e.Name(), err)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func collectWingEntries(wingDir string) ([]noteEntry, error) {
|
||||
var out []noteEntry
|
||||
ents, err := os.ReadDir(wingDir)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("read wing: %w", err)
|
||||
}
|
||||
for _, hallEnt := range ents {
|
||||
if !hallEnt.IsDir() {
|
||||
continue
|
||||
}
|
||||
hall := hallEnt.Name()
|
||||
if !IsValidHall(hall) {
|
||||
continue
|
||||
}
|
||||
hallDir := filepath.Join(wingDir, hall)
|
||||
notes, err := os.ReadDir(hallDir)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("read hall %s: %w", hall, err)
|
||||
}
|
||||
for _, n := range notes {
|
||||
if n.IsDir() || !strings.HasSuffix(n.Name(), ".md") || n.Name() == "_index.md" {
|
||||
continue
|
||||
}
|
||||
slug := strings.TrimSuffix(n.Name(), ".md")
|
||||
full := filepath.Join(hallDir, n.Name())
|
||||
title, created := readTitleAndCreated(full, slug)
|
||||
out = append(out, noteEntry{Hall: hall, Slug: slug, Title: title, Created: created})
|
||||
}
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// readTitleAndCreated reads YAML frontmatter for title + created_at; falls
|
||||
// back to slug and file mtime when absent.
|
||||
func readTitleAndCreated(path, slug string) (string, string) {
|
||||
f, err := os.Open(path)
|
||||
if err != nil {
|
||||
return slug, ""
|
||||
}
|
||||
defer func() { _ = f.Close() }()
|
||||
|
||||
title, created := "", ""
|
||||
scanner := bufio.NewScanner(f)
|
||||
inFrontmatter := false
|
||||
for scanner.Scan() {
|
||||
line := scanner.Text()
|
||||
if strings.TrimSpace(line) == "---" {
|
||||
if !inFrontmatter {
|
||||
inFrontmatter = true
|
||||
continue
|
||||
}
|
||||
break
|
||||
}
|
||||
if !inFrontmatter {
|
||||
continue
|
||||
}
|
||||
key, val, ok := strings.Cut(line, ":")
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
v := strings.Trim(strings.TrimSpace(val), `"'`)
|
||||
switch strings.TrimSpace(key) {
|
||||
case "title":
|
||||
title = v
|
||||
case "created_at":
|
||||
if t, err := time.Parse(time.RFC3339, v); err == nil {
|
||||
created = t.UTC().Format("2006-01-02")
|
||||
} else {
|
||||
created = v
|
||||
}
|
||||
}
|
||||
}
|
||||
if title == "" {
|
||||
title = slug
|
||||
}
|
||||
if created == "" {
|
||||
if info, err := os.Stat(path); err == nil {
|
||||
created = info.ModTime().UTC().Format("2006-01-02")
|
||||
}
|
||||
}
|
||||
return title, created
|
||||
}
|
||||
Reference in New Issue
Block a user