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:
70
ingestion/internal/brain/path.go
Normal file
70
ingestion/internal/brain/path.go
Normal file
@@ -0,0 +1,70 @@
|
||||
// Package brain provides the wing/hall path taxonomy used by the brain
|
||||
// wiki layout. A note's canonical location is
|
||||
// brain/wiki/<wing>/<hall>/<slug>.md, where Wing is a free-form topic
|
||||
// domain and Hall is one of a closed vocabulary of memory types.
|
||||
package brain
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// ValidHalls is the closed vocabulary of hall names. A hall captures the
|
||||
// memory type of a note within any wing.
|
||||
var ValidHalls = map[string]bool{
|
||||
"facts": true,
|
||||
"decisions": true,
|
||||
"failures": true,
|
||||
"hypotheses": true,
|
||||
"sources": true,
|
||||
}
|
||||
|
||||
// IsValidHall reports whether h is in the closed Hall vocabulary.
|
||||
func IsValidHall(h string) bool {
|
||||
return ValidHalls[h]
|
||||
}
|
||||
|
||||
// NotePath resolves the canonical filesystem path for a note given a
|
||||
// wing, hall, and slug. Returns an error if hall is not in ValidHalls
|
||||
// or if wing/slug sanitise to empty strings.
|
||||
//
|
||||
// The returned path is brain/wiki/<wing>/<hall>/<slug>.md with all
|
||||
// segments sanitised: lowercased, alphanumerics and hyphens only.
|
||||
func NotePath(brainDir, wing, hall, slug string) (string, error) {
|
||||
if !IsValidHall(hall) {
|
||||
return "", fmt.Errorf("invalid hall %q: must be one of facts/decisions/failures/hypotheses/sources", hall)
|
||||
}
|
||||
w := Sanitise(wing)
|
||||
if w == "" {
|
||||
return "", fmt.Errorf("invalid wing %q: must contain at least one alphanumeric character", wing)
|
||||
}
|
||||
s := Sanitise(strings.TrimSuffix(slug, ".md"))
|
||||
if s == "" {
|
||||
return "", fmt.Errorf("invalid slug %q: must contain at least one alphanumeric character", slug)
|
||||
}
|
||||
return filepath.Join(brainDir, "wiki", w, hall, s+".md"), nil
|
||||
}
|
||||
|
||||
// Sanitise lowercases s and keeps only [a-z0-9-], collapsing any other
|
||||
// character (including path separators) to a hyphen. Leading/trailing
|
||||
// hyphens and runs of hyphens are collapsed.
|
||||
func Sanitise(s string) string {
|
||||
s = strings.ToLower(strings.TrimSpace(s))
|
||||
var b strings.Builder
|
||||
prevHyphen := true
|
||||
for _, r := range s {
|
||||
switch {
|
||||
case r >= 'a' && r <= 'z', r >= '0' && r <= '9':
|
||||
b.WriteRune(r)
|
||||
prevHyphen = false
|
||||
case r == '-' || r == '_' || r == ' ' || r == '/' || r == '\\' || r == '.':
|
||||
if !prevHyphen {
|
||||
b.WriteByte('-')
|
||||
prevHyphen = true
|
||||
}
|
||||
}
|
||||
}
|
||||
out := b.String()
|
||||
return strings.Trim(out, "-")
|
||||
}
|
||||
Reference in New Issue
Block a user