Content
# MCP Brain Manager
An intelligent context management layer for the Brain Knowledge Management System, implementing semantic routing and human-in-the-loop workflows.
## Overview
The MCP Brain Manager provides:
- **Enhanced Session Management** - Automatic context loading and mode selection
- **Semantic Routing** - Intelligent classification of user intent
- **Human-in-the-Loop Updates** - Proposed changes require confirmation
- **Project Stack** - Seamless switching between multiple projects
- **Project Templates** - Structured starting points for different project types
- **Analytics & Insights** - Pattern analysis and productivity metrics
## Installation
```bash
cd mcp-brain-manager
npm install
npm run build
```
## Configuration
Add to your MCP settings:
```json
{
"mcpServers": {
"brain-manager": {
"command": "node",
"args": ["/path/to/mcp-brain-manager/dist/index.js"],
"description": "Intelligent Brain system management"
}
}
}
```
## Available Tools
### Core Management
#### `manager_init`
Initialize enhanced brain session with context loading.
```typescript
manager_init({ message: "Let's continue working on the API" })
// Returns: mode, confidence, last session info, current project
```
#### `propose_update`
Create a reviewable update proposal.
```typescript
propose_update({
updateType: "progress",
updates: {
completedTasks: ["Setup auth"],
newTasks: ["Add tests"],
currentFocus: "Testing"
}
})
// Returns: proposal ID, confirmation prompt, proposed changes
```
#### `confirm_update`
Apply a proposed update after review.
```typescript
confirm_update({
updateId: "uuid-here",
modifications: { /* optional changes */ }
})
```
### Project Management
#### `switch_project`
Switch to different project with context preservation.
```typescript
switch_project({
projectName: "new-project",
createIfNotExists: true,
template: "software"
})
```
#### `return_to_previous`
Pop previous project from stack.
```typescript
return_to_previous()
```
#### `generate_dashboard`
Create Obsidian-compatible project dashboard.
```typescript
generate_dashboard({
projectName: "my-project",
includeAnalytics: true
})
```
### Intelligence Features
#### `semantic_classify`
Classify user intent with reasoning.
```typescript
semantic_classify({
message: "I want to analyze the performance metrics",
context: { lastProject: "api-project" }
})
// Returns: mode, confidence, reasoning
```
#### `analyze_patterns`
Analyze work patterns for insights.
```typescript
analyze_patterns({
timeframe: "week",
focusArea: "productivity"
})
```
## Usage Examples
### Starting a Session
```javascript
// First message of the day
await manager_init({
message: "Let's continue with the chat app"
})
// Response:
{
"mode": "project_continuation",
"confidence": 0.85,
"reasoning": "Continuation signal detected with active project",
"lastSession": {
"project": "chat-app",
"lastActivity": "Implemented websocket server"
}
}
```
### Recording Progress
```javascript
// Propose an update
const proposal = await propose_update({
updateType: "progress",
updates: {
completedTasks: ["Implement websockets"],
newTasks: ["Add reconnection logic"],
currentFocus: "Connection stability"
}
})
// Review and confirm
await confirm_update({ updateId: proposal.id })
```
### Making Decisions
```javascript
await propose_update({
updateType: "decision",
updates: {
decision: "Use Socket.IO instead of raw WebSockets",
rationale: "Better browser compatibility and reconnection",
impact: "Need to refactor existing code"
}
})
```
## Project Templates
Available templates:
- `software` - Software development projects
- `research` - Research and investigation
- `ml` - Machine learning projects
- `writing` - Writing and documentation
- `custom` - Blank slate
## Security Guidelines
### Data Storage Restrictions
**NEVER store the following in the state table:**
- API keys (OpenAI, Anthropic, etc.)
- Passwords or authentication tokens
- OAuth tokens or refresh tokens
- Private SSH keys or certificates
- Database connection strings with credentials
- Any form of authentication credentials
- Personal identification information (SSN, credit cards, etc.)
### Sensitive Data Handling
If you need to work with sensitive data:
1. **Environment Variables** - Keep API keys in environment variables
2. **External Config** - Use separate config files (not tracked in git)
3. **Monitex Integration** - For future encrypted storage needs:
```javascript
// Future implementation
await manager_init({
message: "Start work",
encrypted: true // Triggers Monitex password prompt
})
```
### Validation Rules
The brain-manager includes automatic validation to prevent accidental storage of sensitive data:
- Detects common API key patterns (sk-, pk-, api-, key-, token-)
- Blocks storage of strings matching credential patterns
- Warns when attempting to store potential sensitive data
### Safe Data for State Table
✅ **Safe to store:**
- Project metadata and descriptions
- Task lists and progress tracking
- Decision records and rationales
- File paths and project structure
- Timestamps and activity logs
- Non-sensitive configuration options
- Public URLs and documentation links
❌ **Never store:**
- Any form of credentials or secrets
- Private/sensitive project data
- Customer data or PII
- Proprietary algorithms or trade secrets
## Architecture
```
mcp-brain-manager/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── brain-manager.ts # Core management logic
│ ├── semantic-router.ts # Intent classification
│ └── template-manager.ts # Project templates
├── dist/ # Compiled output
└── package.json
```
## Integration with Brain Tools
This manager coordinates with existing brain tools:
- Uses `brain:brain_init` for initialization
- Stores contexts with `brain:state_set/get`
- Saves narratives with `brain:brain_remember/recall`
- Creates dashboards with `brain:obsidian_note`
## Development
```bash
# Watch mode
npm run watch
# Run tests
npm test
# Build for production
npm run build
```
## Future Enhancements
1. **True Semantic Routing** - Call Claude for classification instead of patterns
2. **Context Compression** - Automatic summarization for large projects
3. **Collaboration Mode** - Share contexts between users
4. **Voice Integration** - Natural language project updates
5. **Auto-categorization** - Intelligent task and decision grouping
## Troubleshooting
**Q: Semantic classification seems wrong?**
A: You can provide feedback to improve:
```javascript
await semantic_classify({
message: "your message",
context: { /* ... */ }
})
// If wrong, explicitly state: "switch to research mode"
```
**Q: How to see all projects?**
A: Use the brain tools directly:
```javascript
brain:state_list({ category: "project" })
```
**Q: Update proposal expired?**
A: Proposals expire after 5 minutes. Create a new one.
## License
MIT
