brainy/docs/conversation/MCP_INTEGRATION.md

MCP Integration - Claude Code Setup

One command. Infinite memory. This guide shows you how to give Claude Code infinite context and conversation history using Brainy's Model Control Protocol (MCP) integration.

Quick Setup

One-Time Configuration

# Install Brainy globally (if not already installed)
npm install -g @soulcraft/brainy

# Set up MCP server for Claude Code
brainy conversation setup

That's it! Claude Code now has infinite memory.

What This Does

The setup command:

1. Creates ~/.brainy-memory/ directory
2. Initializes Brainy database with filesystem storage
3. Creates MCP server script
4. Registers server with Claude Code
5. Ready to use - no configuration needed

How It Works

Automatic Integration

Once set up, Claude Code automatically:

On Every Message:

• Saves your message with semantic embeddings
• Saves Claude's response with metadata
• Links code artifacts to conversations
• Tracks problem-solving phase and confidence
• Indexes everything for instant retrieval

On Conversation Start:

• Retrieves relevant past context
• Finds similar previous conversations
• Loads linked code artifacts
• Presents context to Claude seamlessly

Result: Claude never loses context or momentum, even across completely separate conversations.

User Experience

Before:

You: "How do I implement JWT auth?"
Claude: [Implements authentication]

[Days later, new conversation]
You: "Can you fix the JWT token validation?"
Claude: "I don't have context about your JWT implementation..."

After:

You: "How do I implement JWT auth?"
Claude: [Implements authentication, saves to Brainy]

[Days later, new conversation]
You: "Can you fix the JWT token validation?"
Claude: "I found 3 related past conversations about JWT...
         Here's the implementation from /auth/middleware.ts..."
         [Full context automatically retrieved]

MCP Tools

The MCP server exposes 6 conversation tools that Claude Code uses automatically:

1. conversation_save_message

Saves a message to conversation history.

Used by: Claude Code automatically after each message Parameters:

• content: Message text
• role: 'user' | 'assistant' | 'system' | 'tool'
• conversationId: Conversation identifier
• phase: Problem-solving phase
• confidence: Confidence score
• artifacts: Array of artifact IDs
• toolsUsed: Tools used in this message

2. conversation_get_context

Retrieves relevant past context.

Used by: Claude Code at conversation start or when context is needed Parameters:

• query: What to retrieve context for
• limit: Max messages (default: 10)
• maxTokens: Token budget (default: 50000)
• relevanceThreshold: Min similarity (default: 0.7)
• includeArtifacts: Include code/files
• includeSimilarConversations: Include similar past conversations

Returns:

• Ranked messages with relevance scores
• Linked artifacts
• Similar past conversations
• Metadata (query time, tokens, etc.)

3. conversation_search

Searches all conversations semantically.

Used by: When Claude needs to find specific past information Parameters:

• query: Search query
• role: Filter by role
• conversationId: Filter by conversation
• timeRange: Time range filter

4. conversation_get_thread

Gets complete conversation thread.

Used by: When Claude needs full conversation history Parameters:

• conversationId: Conversation ID
• includeArtifacts: Include linked artifacts

5. conversation_save_artifact

Saves code/file artifacts.

Used by: When Claude creates files Parameters:

• path: File path
• content: File content
• conversationId: Conversation ID
• messageId: Message that created it
• type: 'code' | 'config' | 'data' | 'document'
• language: Programming language

6. conversation_find_similar

Finds similar past conversations.

Used by: For discovering related work Parameters:

• conversationId: Conversation to find similar to
• limit: Max results
• threshold: Similarity threshold

MCP Server Architecture

Server Location

~/.brainy-memory/
├── mcp-server.js         # MCP server script
└── data/                 # Brainy database
    ├── nouns/           # Messages
    ├── verbs/           # Relationships
    └── index/           # Search indexes

Server Script

The generated server script (~/.brainy-memory/mcp-server.js):

import { Brainy } from '@soulcraft/brainy'
import { BrainyMCPService } from '@soulcraft/brainy'
import { MCPConversationToolset } from '@soulcraft/brainy'

// Initialize Brainy
const brain = new Brainy({
  storage: {
    type: 'filesystem',
    path: '~/.brainy-memory/data'
  },
  silent: true
})
await brain.init()

// Create MCP service
const mcpService = new BrainyMCPService(brain)
const conversationTools = new MCPConversationToolset(brain)

// Handle MCP requests via stdio
process.stdin.on('data', async (data) => {
  const request = JSON.parse(data.toString())

  let response
  if (request.toolName?.startsWith('conversation_')) {
    response = await conversationTools.handleRequest(request)
  } else {
    response = await mcpService.handleRequest(request)
  }

  process.stdout.write(JSON.stringify(response) + '\\n')
})

Claude Code Configuration

Located at ~/.config/claude-code/mcp-servers.json:

{
  "brainy-memory": {
    "command": "node",
    "args": ["~/.brainy-memory/mcp-server.js"],
    "env": {
      "NODE_ENV": "production"
    }
  }
}

Advanced Configuration

Custom Storage Location

Edit ~/.brainy-memory/mcp-server.js:

const brain = new Brainy({
  storage: {
    type: 'filesystem',
    path: '/path/to/custom/location'
  }
})

Cloud Storage (Multi-Device Sync)

Use S3-compatible storage for sync across machines:

const brain = new Brainy({
  storage: {
    type: 's3',
    bucket: 'my-brainy-memory',
    region: 'us-east-1'
  }
})

Requirements: Set AWS credentials in environment:

export AWS_ACCESS_KEY_ID=xxx
export AWS_SECRET_ACCESS_KEY=yyy

Memory Storage (Testing)

For testing or temporary use:

const brain = new Brainy({
  storage: { type: 'memory' }
})

Note: Memory storage is lost on server restart.

Context Retrieval Options

Customize context retrieval behavior:

const context = await conversationManager.getRelevantContext(query, {
  limit: 15,                  // More messages
  maxTokens: 80000,          // Larger context window
  relevanceThreshold: 0.6,   // Lower threshold = more results
  weights: {
    semantic: 0.7,           // Adjust relevance weights
    temporal: 0.6,
    graph: 0.4
  }
})

Troubleshooting

Server Not Starting

Check logs:

# Server writes to stderr
tail -f ~/.brainy-memory/server.log

Common issues:

1. Node version: Requires Node.js 22 LTS
2. Permissions: Ensure ~/.brainy-memory is writable
3. Port conflicts: MCP uses stdio, no ports needed

Claude Code Not Using Memory

Verify setup:

# Check MCP server is registered
cat ~/.config/claude-code/mcp-servers.json

# Test server manually
echo '{"type":"system_info","infoType":"version","requestId":"test","version":"1.0.0"}' | node ~/.brainy-memory/mcp-server.js

Expected output:

{"success":true,"requestId":"test","version":"1.0.0","data":{"version":"1.0.0"}}

Memory Not Persisting

Check storage:

# Verify data directory exists
ls -la ~/.brainy-memory/data/

# Check database files
du -sh ~/.brainy-memory/data/

If empty: Server may be using memory storage. Check mcp-server.js configuration.

Performance Issues

Optimize database:

# Rebuild indexes
brainy conversation stats  # This triggers index optimization

Check size:

# Show storage usage
du -sh ~/.brainy-memory/

If too large: Consider cloud storage or compaction strategies.

CLI Commands

Manage conversations via CLI:

View Statistics

brainy conversation stats

Output:

📊 Conversation Statistics

Overall:
  Conversations: 42
  Messages: 1,337
  Total Tokens: 567,890
  Avg Messages/Conversation: 31.8
  Avg Tokens/Message: 425.1

By Role:
  user: 650
  assistant: 687

By Phase:
  implementation: 423
  planning: 201
  testing: 98

Search Messages

brainy conversation search -q "authentication" -l 10

Get Context

brainy conversation context -q "JWT token validation" -l 15

View Thread

brainy conversation thread -c conv_abc123

Export Conversation

brainy conversation export -c conv_abc123 -o backup.json

Import Conversation

brainy conversation import -o backup.json

Security & Privacy

Local-First by Default

• All data stored locally in ~/.brainy-memory/
• No external services or APIs
• Complete privacy and control

Data Encryption

For sensitive conversations, use encrypted filesystem:

# Create encrypted volume
hdiutil create -size 1g -encryption AES-256 -volname BrainyMemory ~/brainy-secure.dmg

# Mount and use
hdiutil attach ~/brainy-secure.dmg
brainy conversation setup --path /Volumes/BrainyMemory

Access Control

MCP server runs with your user permissions. No additional authentication needed for local use.

Next Steps

• API Reference - Complete API documentation
• Examples - Usage examples and patterns
• Advanced Features - Advanced configuration and optimization

Support

Issues or questions:

• GitHub: soulcraftlabs/brainy/issues
• Documentation: docs.brainy.ai