brainy/PHILOSOPHY.md

🧠 Brainy Philosophy & Design Principles

Core Philosophy

"Simple for beginners, powerful for experts"

Design Principles

1. Beginner-Friendly by Default

• If no arguments provided → Interactive mode with helpful prompts
• Clear, simple language (no jargon)
• Helpful examples shown automatically
• Smart defaults that "just work"

2. Clean, Simple Language

# Good - Clear and simple
brainy add "John works at Acme Corp"
brainy search "Who works at Acme?"
brainy augment neural-import data.csv

# Bad - Technical and confusing
brainy insert --vector-dimension=384 --graph-node="person" 
brainy query --similarity-threshold=0.8 --facet-filter='{"type":"person"}'

3. Progressive Disclosure

• Start simple, reveal complexity only when needed
• Basic usage requires no configuration
• Advanced features available but not required

4. Interactive When Uncertain

$ brainy add
? What would you like to add? › John Smith is a developer
? Add any tags or categories? (optional) › person, developer
✅ Added successfully!

$ brainy search
? What are you looking for? › developers
? How many results? (10) › 5
🔍 Found 5 matches...

5. Consistent Brain Metaphor

• Brainy = The brain (whole system)
• Cortex = Orchestrator (coordinates everything)
• Neural Import = Understanding data (neural processing)
• Augmentations = Brain capabilities (vision, hearing, memory, etc.)

6. One Way to Do Things

• Single clear path for common tasks
• No duplicate commands or confusing aliases
• If there are options, make the best one the default

7. Helpful Error Messages

# Good
❌ Can't find data.csv
💡 Did you mean data.json? Or try: brainy import --help

# Bad
Error: ENOENT no such file or directory

8. Smart Defaults

• Auto-detect file types
• Infer intent from context
• Use Neural Import by default for understanding data
• Automatic augmentation discovery

CLI Command Philosophy

Core Commands (Simple Verbs)

brainy init        # Start here
brainy add         # Add data
brainy search      # Find data
brainy chat        # Talk to your data

Augmentation Commands (Clear Actions)

brainy augment                    # List/manage augmentations
brainy augment add neural-import  # Add an augmentation
brainy augment remove notion-sync # Remove an augmentation

Interactive Examples

# No arguments = Interactive mode
$ brainy add
? What would you like to add? › [waiting for input]

# With arguments = Direct mode
$ brainy add "Sarah is a designer at StartupXYZ"
✅ Added!

# Help is conversational
$ brainy help add
📝 Add data to your brain

Examples:
  brainy add "John works at Acme"
  brainy add data.csv
  brainy add --interactive

Just run 'brainy add' for interactive mode!

Code Philosophy

Function Names

// Good - Clear and simple
brain.add(data)
brain.search(query)
cortex.process(augmentation)

// Bad - Technical and verbose
brain.insertVectorWithGraphRelationships(data)
brain.executeMultiDimensionalQuery(query)
cortex.executeAugmentationPipeline(augmentation)

API Design

// Good - Progressive enhancement
brain.add("simple text")                    // Works
brain.add("text", { category: "person" })   // More control
brain.add("text", metadata, options)        // Full control

// Bad - All or nothing
brain.add(text, vector, metadata, options, callback)

Documentation Philosophy

README Structure

1. What it is (one sentence)
2. Quick start (3 commands max)
3. Simple examples (real-world use)
4. Going deeper (advanced features)

Example First

Always show the example before explaining:

# Add a person
brainy add "Alice is a product manager"

# Find them later
brainy search "product manager"

Testing Philosophy

• Test the beginner path first
• Interactive mode must always work
• Examples in docs must be runnable
• Error messages must be helpful

Remember

• If it's not simple, it's not ready
• The best interface is no interface (smart defaults)
• Show, don't tell (examples > explanations)
• Beginner's mind (always ask: would a newcomer understand this?)