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

cd mcp-brain-manager
npm install
npm run build

Configuration

Add to your MCP settings:

{
  "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.

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.

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.

confirm_update({
  updateId: "uuid-here",
  modifications: { /* optional changes */ }
})

Project Management

switch_project

Switch to different project with context preservation.

switch_project({
  projectName: "new-project",
  createIfNotExists: true,
  template: "software"
})

return_to_previous

Pop previous project from stack.

return_to_previous()

generate_dashboard

Create Obsidian-compatible project dashboard.

generate_dashboard({
  projectName: "my-project",
  includeAnalytics: true
})

Intelligence Features

semantic_classify

Classify user intent with reasoning.

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.

analyze_patterns({
  timeframe: "week",
  focusArea: "productivity"
})

Usage Examples

Starting a Session

// 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

// 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

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:

   // 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

# 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:

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:

brain:state_list({ category: "project" })

Q: Update proposal expired? A: Proposals expire after 5 minutes. Create a new one.

License

MIT