A play on "brain" - Brian is your intelligent knowledge repository with vector-based similarity search, beautiful graph visualization, and seamless Goose integration. Because I cannot spell 9/10 times and I make this mistake all the time now you can too!
- 📚 Knowledge Items: Store links, notes, code snippets, and papers
- 🔍 Smart Search: Full-text search with FTS5 + TF-IDF vector similarity
- 🏷️ Tagging System: Organize items with tags for easy filtering
- 🔗 Link Previews: Automatic metadata extraction from URLs
- 📄 Google Docs Support: Seamless integration with Google Drive documents
- 🗂️ Multiple Projects: Organize knowledge into separate project spaces
- 🎨 Custom Project Icons: Choose from 25+ Lucide icons for each project
- 🌈 Project Colors: Color-code your knowledge bases
- 🌐 All Projects View: See everything across all knowledge bases at once
- 🕸️ Force-Directed Graph: Interactive D3.js visualization showing connections
- 🎨 Theme Highlighting: Hover over tags to see themed connections with colored drop shadows
- 🔍 Semantic Zoom: Smooth transitions between project, region, and item views
- 🌌 Knowledge Universe: Zoom out to see all projects as "galaxies" in a unified space
- 📍 Knowledge Regions: Group related items with visual boundaries
- 🔭 Multi-Scale View: Seamlessly zoom from individual items to entire knowledge universe
- 🪐 Project Hulls: Visual boundaries around project clusters when zoomed out
- ✨ Semantic Rendering: Labels, nodes, and links adapt based on zoom level
- 📊 Zoom Indicator: Real-time display of zoom level and current semantic view
- 🤖 Goose Integration: Use Brian directly from Goose AI assistant via MCP
- 🧭 Region Profiles: Configure AI behavior per knowledge region
- 💡 Smart Context: Get relevant knowledge context for any topic
- Python 3.8+ - Download
- Node.js 16+ - Download
- pnpm - Install (
npm install -g pnpm) - Goose (optional) - For AI assistant integration - https://github.com/block/goose
# Clone the repository
git clone https://github.com/yourusername/brian.git
cd brian
# Run the setup script
./setup.shThat's it! The setup script will:
- ✅ Install all Python dependencies
- ✅ Install all frontend dependencies
- ✅ Create the Brian data directory
- ✅ Configure the Goose extension automatically
- ✅ Create convenient start/stop scripts
./start.shThis starts both the backend (port 8080) and frontend (port 5173) servers.
Open your browser to: http://localhost:5173
./stop.shVia Web UI:
- Open http://localhost:5173
- Click the "+" button
- Choose item type (link, note, snippet, paper)
- Fill in the details and add tags
- Save!
Via Goose:
You: Add this link to Brian: https://example.com with tags "ai, research"
Goose: ✓ Added to your knowledge base!
Creating a Project:
- Click the Project Selector at the top center
- Click "New Project"
- Enter name, description, choose an icon and color
- Click Create
Switching Projects:
- Click the Project Selector and choose a project
- Select "All Projects" to view everything across all knowledge bases
Editing Projects:
- Hover over a project in the selector and click the edit (pencil) icon
- Change the name, description, icon, or color
The graph view shows connections between items based on content similarity:
- Node Colors: Blue (links), Green (notes), Amber (snippets), Purple (papers)
- Line Thickness: Indicates similarity strength
- Theme Highlighting: Hover over tags to see themed connections
- Node Details: Click any node to see full details in a bottom sheet
- Zoom & Pan: Scroll to zoom, drag to pan
- Drag Nodes: Reposition nodes by dragging
When viewing "All Projects", you can explore your entire knowledge universe:
- Zoom Out (scale < 0.3): See all projects as distinct clusters with hull boundaries
- Mid Zoom (scale 0.3-0.5): See knowledge regions within projects
- Zoom In (scale > 0.5): See individual items with full labels
The zoom indicator in the bottom-left shows your current zoom level and semantic view.
Regions help organize related items within a project:
- Click the Regions button in the toolbar
- Create a new region with a name and color
- Add items to regions by selecting them in the graph
- Regions appear as visual boundaries in the graph view
Via Web UI:
- Use the search bar at the top
- Results show both exact matches and similar items
- Filter by type, tags, or project
Via Goose:
You: Search Brian for "machine learning"
Goose: Found 5 items related to machine learning...
Create a .env file in the project root:
# Database location
BRIAN_DB_PATH=~/.brian/brian.db
# API server
BRIAN_HOST=127.0.0.1
BRIAN_PORT=8080
BRIAN_DEBUG=false
# Frontend (optional)
VITE_PORT=5173 # Frontend dev server port (auto-fallback if busy)
VITE_API_URL=http://127.0.0.1:8080 # Backend API URL for proxyDynamic Port Configuration:
- If
VITE_PORTis busy, the frontend will automatically use the next available port - Useful when running multiple instances or when ports are occupied
The setup script automatically configures Goose. The configuration is added to ~/.config/goose/config.yaml:
extensions:
brian:
provider: mcp
config:
command: "/path/to/brian/venv/bin/python"
args:
- "-m"
- "brian_mcp.server"
env:
BRIAN_DB_PATH: "~/.brian/brian.db"After setup, restart Goose to load the Brian extension.
If you prefer manual installation:
# Backend setup
python3 -m venv venv
source venv/bin/activate
pip install -e .
# Frontend setup
cd frontend
pnpm install
# Start backend
python -m brian.main
# Start frontend (in another terminal)
cd frontend
pnpm devbrian/
├── brian/ # Backend Python package
│ ├── api/ # FastAPI routes
│ ├── database/ # SQLite database layer
│ │ ├── migrations.py # Database migrations
│ │ ├── repository.py # Data access layer
│ │ └── schema.py # Database schema
│ ├── models/ # Data models
│ │ └── knowledge_item.py
│ └── services/ # Business logic
│ ├── similarity.py # Similarity calculations
│ └── clustering.py # Item clustering
├── brian_mcp/ # MCP server for Goose integration
├── frontend/ # React frontend
│ └── src/
│ ├── components/ # React components
│ │ ├── SimilarityGraph.jsx # Main graph visualization
│ │ ├── ProjectSelector.jsx # Project management UI
│ │ ├── ProjectPill.jsx # Project indicator component
│ │ ├── Timeline.jsx # Chronological view
│ │ ├── InfinitePinboard.jsx # Spatial canvas
│ │ ├── RegionEditDialog.jsx # Region management
│ │ └── Settings.jsx # App settings
│ ├── contexts/ # React contexts
│ │ └── SettingsContext.jsx
│ ├── store/ # State management
│ │ └── useStore.js # Zustand store
│ └── lib/ # Utilities
├── setup.sh # One-command installation
├── start.sh # Start both servers
└── stop.sh # Stop both servers
# Activate virtual environment
source venv/bin/activate
# Run Python tests
pytest
# Test MCP server
python test_mcp_simple.py
# Test search functionality
python test_search_fix.py- Large pill-shaped button at top center
- Shows current project with icon, name, and item count
- "All Projects" mode shows universe icon with total counts
- Dropdown with all projects, create new, and edit options
- 25+ Lucide icons to choose from
- Chronological display of all items
- Grouped by date
- Project pills showing item origin
- Theme lines connecting related items
- Smooth animations
- Force-directed layout with D3.js
- Real-time similarity calculations
- Interactive node selection
- Theme-based filtering with drop shadows
- Bottom sheet for detailed view with project pills
- Pulsing animation on selected nodes
- Hierarchical zoom with semantic rendering
- Project hulls when viewing all projects
- Zoom indicator showing current level
- Circular icon buttons matching modern UI patterns
- Smooth transitions between views
- Responsive design
- Keyboard shortcuts (coming soon)
When integrated with Goose, Brian provides these tools:
Add new items to your knowledge base.
Parameters:
- title: Item title
- content: Main content
- item_type: link, note, snippet, or paper
- url: Optional URL
- tags: Optional list of tags
- project_id: Optional project to add to
Search your knowledge base with full-text and similarity search.
Parameters:
- query: Search query
- limit: Max results (default: 10)
- project_id: Optional project filter
Find items similar to a given item.
Parameters:
- item_id: UUID of the reference item
- limit: Max results (default: 5)
Get full details of a specific item.
Parameters:
- item_id: UUID of the item
List all knowledge base projects.
Create a new knowledge base project.
Parameters:
- name: Project name
- description: Optional description
- icon: Optional emoji icon
- color: Optional hex color
Switch the default project for new items.
Parameters:
- project_id: UUID of the project
Get knowledge context from a specific project.
Parameters:
- project_id: Optional project ID
- query: Optional query to filter items
- limit: Max items (default: 20)
List all knowledge regions.
Create a new knowledge region.
Parameters:
- name: Region name
- description: Optional description
- color: Optional hex color
- item_ids: Optional items to include
Get knowledge context from a specific region.
Parameters:
- region_id: UUID of the region
- query: Optional query to filter items
Get relevant knowledge items for a topic.
Parameters:
- topic: Topic to get context for
- limit: Max items (default: 5)
Suggest relevant regions for a query.
Parameters:
- query: Query to find relevant regions
- limit: Max regions (default: 3)
Debug similarity connections for an item.
Parameters:
- item_id: UUID of the item to debug
Brian uses a hybrid approach for finding connections:
- TF-IDF Vectorization: Converts text to numerical vectors
- Cosine Similarity: Measures angle between vectors
- Threshold Filtering: Only shows connections above 0.15 similarity
- Global IDF Scores: Pre-computed for all documents
- Project-Aware: Can filter connections by project
This creates meaningful connections between related items without manual linking.
# Check if port 8080 is in use
lsof -i :8080
# Check logs
tail -f backend.log# Check if port 5173 is in use
lsof -i :5173
# Check logs
tail -f frontend.log
# Reinstall dependencies
cd frontend && pnpm install# Verify config
cat ~/.config/goose/config.yaml
# Check Python path is correct
which python # Should be inside brian/venv/bin/
# Restart Goose# Check database exists
ls -la ~/.brian/brian.db
# Reset database (WARNING: deletes all data)
rm ~/.brian/brian.db
# Restart backend to recreate- Ensure you're in "All Projects" mode (click Project Selector → All Projects)
- Zoom out significantly (scale < 0.4) to see project boundaries
- Check that you have items in multiple projects
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with FastAPI
- Frontend powered by React and Vite
- Graph visualization with D3.js
- UI components from shadcn/ui
- Icons from Lucide
- State management with Zustand
- Animations with Framer Motion
- Goose integration via MCP
- Quick Start Guide
- Commands Reference
- Google Drive Integration
- Graph Visualization Guide
- Theme Filtering
- ✅ Multi-project knowledge bases
- ✅ Project selector with custom icons
- ✅ Hierarchical zoom (Knowledge Universe)
- ✅ Project hulls and semantic zoom
- ✅ All Projects view
- ✅ Project pills in Timeline and Graph
- ✅ Dynamic port configuration (VITE_PORT, VITE_API_URL env vars)
- ✅ Automatic project assignment for new regions
- ✅ Fixed Universe Mode initial load issues
- ✅ Fixed region persistence across project views
- 🔜 Zoom slider control
- 🔜 Preset zoom buttons (All / Project / Items)
- 🔜 Breadcrumb navigation
- 🔜 Keyboard shortcuts for navigation
- 🔜 Image upload with LLM interpretation
- 🔜 Standardized card components
Made with 🧠 and ❤️
A play on "brain" - because your knowledge deserves a smart home.