Content
# BrainKB - Local Second Brain System
A local knowledge base system based on the MCP protocol, supporting note management, vector retrieval, and knowledge graph visualization.
## Quick Start
### 1. Environment Preparation
```powershell
cd <project-root>
# Configure pip to install to D drive (to avoid C drive space issues)
pip config set global.cache-dir "<pip-cache>"
pip config set global.target "<project-root>\libs"
# Install dependencies (install to D drive libs directory)
pip install -r requirements.txt
# Configure environment variables
copy .env.example .env
# Modify .env as needed to update VAULT_PATH
```
### 2. Install Ollama and Pull Models
Download and install [Ollama](https://ollama.com/download), then:
```powershell
ollama pull nomic-embed-text
```
### 3. Configure Environment Variables
Already completed in step 1 (.env file).
### 4. Initialize Vault
```powershell
python -m src.scripts.init_vault
```
### 5. Configure MCP (in Trae/Claude Desktop)
Add to MCP configuration file:
```json
{
"mcpServers": {
"brain-kb": {
"command": "python",
"args": ["<project-root>/run.py"],
"cwd": "<project-root>"
}
}
}
```
### 6. Open Knowledge Base with Obsidian
Install [Obsidian](https://obsidian.md/download) and open the `<vault-path>` directory.
## Directory Structure
```
brain-kb/
├── src/
│ ├── server.py # MCP Server entry
│ ├── config.py # Configuration
│ ├── models.py # Data models
│ ├── services/
│ │ ├── note_service.py # Note CRUD
│ │ ├── vector_service.py # Vector retrieval (numpy implementation)
│ │ ├── graph_service.py # Knowledge graph
│ │ └── tree_service.py # Directory tree
│ └── utils/
│ ├── markdown_parser.py # Markdown parser
│ └── ollama_client.py # Ollama client
├── docs/
│ ├── DESIGN.md # Design document
│ └── TEST.md # Test document
├── tests/
│ └── test_all.py # Comprehensive test script
├── libs/ # Python dependencies (D drive)
├── run.py # Startup script
├── .env # Environment configuration
└── requirements.txt # Dependency list
```
## Core MCP Tools
| Tool | Function |
|------|----------|
| `write_note` | Write new note and auto-index |
| `search_knowledge` | Semantic search historical knowledge |
| `read_note` | Read note content |
| `append_note` | Append content to note |
| `list_notes` | List notes |
| `get_links` | View bidirectional links |
| `suggest_links` | Recommend related notes |
| `get_graph_overview` | Get knowledge graph |
| `get_tree` | Get directory tree |
| `append_daily` | Record to daily note |
| `reindex_all` | Rebuild full index |
| `index_status` | View index status |
## Documentation
- [Design Document](docs/DESIGN.md)
- [Test Document](docs/TEST.md)
