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

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. ``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

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

Environment Variables - Keep API keys in environment variables
External Config - Use separate config files (not tracked in git)
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

True Semantic Routing - Call Claude for classification instead of patterns
Context Compression - Automatic summarization for large projects
Collaboration Mode - Share contexts between users
Voice Integration - Natural language project updates
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

mcp-brain-manager