MCP Session Memory Server

This README still contains some historical material from earlier revisions. For the current runtime, treat src/index.ts, src/database.ts, and src/runtime-paths.ts as the source of truth. See docs/PORTABILITY-RFC.md for the current portability plan across Pi, OpenCode, and other MCP harnesses.

A Model Context Protocol (MCP) server for persistent session context, user preferences, project conventions, and related indexed state.

Version 2.0.0 - Enhanced with analytics, search, batch operations, and cross-workflow learning.

Features

Core Features

• Session Context Management: Store and retrieve workflow state across conversations
• User Preferences: Learn and adapt to user coding styles with confidence scoring
• Project Conventions: Track and apply project-specific patterns per language
• Interaction History: Complete conversation and decision audit trail
• Task Management: Track workflow tasks with state transitions and priorities
• Web Dashboard: Modern, responsive UI for viewing and managing all data
• SQLite Storage: Efficient, reliable, single-file database (~60KB initial size)

New in v2.0.0

• Full-Text Search: FTS5 with BM25 ranking for fast memory search
• Semantic Search: Optional vector similarity search (requires @xenova/transformers)
• Pattern Detection: Detect recurring patterns in memory content
• Temporal Analysis: Analyze memory patterns over time periods
• Conflict Detection: Identify conflicting conventions or preferences
• Memory Visualization: Generate memory map data for visualization
• Project Profiles: Multi-project support with stack detection
• Routing Patterns: Cross-workflow learning with confidence scoring
• Batch Operations: 40-60% faster bulk inserts via transactions
• Export/Import: JSON and Markdown export with import support
• Enhanced Tasks: Phases, progress tracking, and velocity metrics

Quick Start

Installation (Portable Setup)

The MCP servers are built automatically when you run the dotfiles bootstrap.sh. For manual setup:

# Run the setup script from the mcp-servers directory
~/.config/opencode/mcp-servers/setup.sh

# Or check if already built
~/.config/opencode/mcp-servers/setup.sh --check

# Force rebuild (e.g., after Node.js update)
~/.config/opencode/mcp-servers/setup.sh --clean

What the setup script does:

1. Checks for prerequisites (Node.js >= 18, build tools)
2. Installs npm dependencies
3. Compiles TypeScript to JavaScript
4. Verifies the server can load

Runtime note: the main MCP server uses sql.js for portable storage. Some optional helper paths and tests still use better-sqlite3; that dependency is not required for the core stdio server.

Client Configuration

OpenCode (pre-configured in opencode.json):

{
  "mcp": {
    "session-memory": {
      "command": ["node", "~/.config/opencode/mcp-servers/session-memory/dist/index.js"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "session-memory": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/.config/opencode/mcp-servers/session-memory/dist/index.js"]
    }
  }
}

Raycast AI (use "Install Server" command):

• Command: node
• Args: ["/Users/YOUR_USERNAME/.config/opencode/mcp-servers/session-memory/dist/index.js"]
• SESSION_DB: /Users/YOUR_USERNAME/.agents/memory/session.db

Get your paths: echo "$HOME/.config/opencode/mcp-servers/session-memory/dist/index.js"

Note: Raycast and Claude Desktop require absolute paths (no ~ expansion). OpenCode expands ~ automatically.

See MCP-SERVER-INTEGRATION-GUIDE.md for detailed setup instructions.

Using the Web Dashboard

The dashboard provides a visual interface to view and manage all session data:

# Start dashboard (background mode)
npm run dashboard:start

# Check dashboard status
npm run dashboard:status

# View dashboard logs
npm run dashboard:logs

# Stop dashboard
npm run dashboard:stop

# Restart dashboard
npm run dashboard:restart

# Check dashboard health
npm run dashboard:health

Dashboard will be available at: http://localhost:3001

Web Dashboard

Features

• Session Contexts: View and search all stored session contexts
• User Preferences: Browse learned preferences with confidence scores
• Project Conventions: Explore project-specific patterns by language
• Interaction History: Review conversation history with metadata
• Tasks: Monitor workflow tasks with state transitions
• Real-time Updates: Live refresh and filtering
• Dark Mode: Toggle between light and dark themes
• Responsive Design: Works on desktop, tablet, and mobile
• Accessibility: WCAG 2.1 AA compliant

Configuration

Configuration is done via environment variables. Copy .env.example to .env and customize:

cp .env.example .env

Environment Variables

Variable	Default	Description
DASHBOARD_PORT	3001	Server port
DASHBOARD_HOST	localhost	Server host (use 0.0.0.0 for all interfaces)
SESSION_DB_PATH	~/.agents/memory/session.db	Database file path
MCP_DASHBOARD_TOKEN	(none)	Bearer token for API authentication
ENABLE_CORS	true	Enable Cross-Origin Resource Sharing
LOG_LEVEL	info	Log level (error, warn, info, debug, trace)
OPEN_BROWSER	false	Auto-open browser on startup

Example Production Configuration

DASHBOARD_PORT=8080
DASHBOARD_HOST=0.0.0.0
MCP_DASHBOARD_TOKEN=your-secure-token-here
ENABLE_CORS=false
LOG_LEVEL=warn

Authentication

The dashboard supports optional bearer token authentication:

1. Generate a secure token:

   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
   

2. Set the token in .env:

   MCP_DASHBOARD_TOKEN=your-generated-token
   

3. Use the token in API requests:

   curl -H "Authorization: Bearer your-generated-token" \
     http://localhost:3001/api/contexts
   

Note: Leave MCP_DASHBOARD_TOKEN empty to disable authentication (not recommended for production).

Health Check Endpoints

The dashboard provides health check endpoints for monitoring:

Endpoint	Purpose	Response
/api/health	Full health status	Server stats, database info, uptime
/api/health/ready	Readiness check	Database schema version
/api/health/live	Liveness check	Simple ping response

Example:

# Full health check
curl http://localhost:3001/api/health

# Readiness check (for Kubernetes)
curl http://localhost:3001/api/health/ready

# Liveness check (for load balancers)
curl http://localhost:3001/api/health/live

Management Scripts

The scripts/dashboard script provides comprehensive management:

# Start dashboard in background
./scripts/dashboard start

# Stop dashboard gracefully
./scripts/dashboard stop

# Restart dashboard
./scripts/dashboard restart

# Check status with health info
./scripts/dashboard status

# View logs (last 50 lines)
./scripts/dashboard logs

# Follow logs in real-time
./scripts/dashboard logs -f

# Open dashboard in browser
./scripts/dashboard open

# Perform health check
./scripts/dashboard health

# Show help
./scripts/dashboard help

Features:

• PID file tracking (.dashboard.pid)
• Log file (.dashboard.log)
• Background daemon mode
• Graceful shutdown with timeout
• Force kill if needed
• Health check integration
• Auto-build if needed
• Platform-specific browser opening (macOS, Linux, Windows)
• Colored output for better visibility
• .env file support

MCP Server Integration

This server integrates with Claude Desktop, Raycast AI, and OpenCode via the Model Context Protocol.

Claude Desktop Setup

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "session-memory": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/.config/opencode/mcp-servers/session-memory/dist/index.js"],
      "env": {
        "SESSION_DB": "/Users/YOUR_USERNAME/.agents/memory/session.db"
      }
    }
  }
}

Get your actual paths:

echo "Server: $HOME/.config/opencode/mcp-servers/session-memory/dist/index.js"
echo "Database: $HOME/.agents/memory/session.db"

Note: Claude Desktop requires absolute paths. Replace YOUR_USERNAME with your username.

MCP Tools

Context Management (3 tools)

• store_session_context - Store workflow state, decisions, active tasks
• retrieve_session_context - Resume from previous session with full context
• store_contexts_batch - Store multiple context rows efficiently

User Preferences (2 tools)

• track_user_preference - Learn user preferences with confidence scoring
• get_user_preferences - Get learned preferences for better personalization

Project Conventions (2 tools)

• learn_project_convention - Learn project-specific patterns by language
• get_project_conventions - Apply learned conventions consistently

Interaction History (2 tools)

• store_interaction - Track conversation history with metadata
• get_interaction_history - Access conversation context and decisions

Task Management (4 tools)

• create_task - Create workflow tasks with state, priority, and metadata
• get_tasks - Retrieve tasks with filtering by session, state, or priority
• update_task - Update task state, priority, or metadata
• delete_task - Remove completed or cancelled tasks

Memory and Task Tools

• query_memory - Search stored memory records by keyword
• assemble_active_context - Build an active context bundle from memory
• stale_work_scan - Find work that should be resurfaced
• daily_briefing - Generate a proactive daily briefing
• weekly_review - Generate a weekly review summary
• task_board - Visual task board grouped by phase/state/priority

Routing Pattern Tools (3 tools) - NEW in v2.0

• get_routing_patterns - Get learned patterns with confidence scores
• store_routing_pattern - Store successful routing patterns
• find_similar_routing_patterns - Find patterns similar to a description

Batch Operations (3 tools) - NEW in v2.0

• store_contexts_batch - Store multiple contexts in single transaction (40-60% faster)
• track_preferences_batch - Track multiple preferences in single transaction
• store_conventions_batch - Store multiple conventions in single transaction

API Management (8 tools)

• store_api_spec - Store OpenAPI/Swagger specs with hash-based change detection
• list_api_specs - List all stored API specs with version and endpoint counts
• delete_api_spec - Delete API spec and all related endpoints/schemas
• get_api_endpoints - Query endpoints by spec, path pattern, method, or tag
• get_api_endpoint_detail - Get full endpoint details including request/response schemas
• search_api_endpoints - Full-text search across endpoint summaries and descriptions
• get_api_schema - Retrieve specific schema definition from an API spec
• ensureApiDocsTables - Initialize API docs tables when needed

Maintenance (3 tools)

• cleanup_old_sessions - Remove sessions older than N days (default: 30)
• server_stats - Get database statistics
• server_health - Run MCP health checks

Usage Examples

Storing Session Context

await store_session_context({
  session_id: "auth-feature-2024",
  context_key: "workflow:summary",
  context_value: "Implementing OAuth2 authentication with JWT tokens",
  metadata: JSON.stringify({ workflow: "authentication", phase: "implementation" })
});

Tracking User Preferences

await track_user_preference({
  user_id: "default",
  preference_key: "string_quotes",
  preference_value: "double",
  confidence: 0.9
});

Learning Project Conventions

await learn_project_convention({
  project_id: "opencode",
  language: "typescript",
  convention_type: "error_handling",
  convention_key: "result_types",
  convention_value: "Result<T, E> types instead of exceptions"
});

Search and Analytics (v2.0)

// Full-text search across stored memory
await query_memory({
  query: "authentication jwt",
  limit: 10
});

// Build active context bundle
await assemble_active_context({
  query: "authentication jwt",
  limit: 8
});

Batch Operations (v2.0)

// Store multiple contexts in one transaction (40-60% faster)
await store_contexts_batch({
  session_id: "feature-123",
  contexts: [
    { context_type: "workflow", context_key: "step1", context_value: "planning" },
    { context_type: "workflow", context_key: "step2", context_value: "implementation" },
    { context_type: "workflow", context_key: "step3", context_value: "testing" }
  ]
});

// Track multiple preferences at once
await track_preferences_batch({
  user_id: "default",
  preferences: [
    { category: "code_style", preference_key: "quotes", preference_value: "double", confidence: 0.9 },
    { category: "code_style", preference_key: "semicolons", preference_value: "always", confidence: 0.85 }
  ]
});

Routing Patterns for Cross-Workflow Learning (v2.0)

// Store a successful routing pattern
await mcp.callTool("store_routing_pattern", {
  pattern_key: "add-authentication-fastapi",
  agent_name: "python-coder",
  confidence: 0.5,
  file_count: 3,
  loc_estimate: 150
});

// Find similar patterns for a new task
await mcp.callTool("find_similar_routing_patterns", {
  description: "implement user login with OAuth",
  min_confidence: 0.7,
  limit: 5
});

Task and Project Views

await task_board({ include_done: false });

await get_project_conventions({
  project_id: "my-app",
  language: "typescript"
});

Development

Building

# Build TypeScript + minify CSS
npm run build

# Watch mode (development)
npm run dev

# Build CSS only
npm run build:css

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Test accessibility
npm run test:a11y

Scripts

Additional helper scripts in scripts/:

• backup-cron.sh - Database backup automation
• health-check-db.sh - Database health checks
• health-check-server.sh - Server health checks
• monitor-production.sh - Production monitoring
• restore-backup.sh - Restore from backup
• rollback-database.sh - Database rollback
• diagnose-workflow-issue.sh - Workflow debugging
• dashboard - Dashboard management (start/stop/status/logs)

Database

The SQLite database is stored at ~/.agents/memory/session.db by default (legacy fallback: ~/.opencode/sessions/session.db).

Schema Version

Current schema version: 8

Tables

• session_contexts - Session state and workflow context
• user_preferences - Learned user preferences with confidence scores
• project_conventions - Project-specific patterns by language
• interactions - Conversation history and decisions
• tasks - Workflow tasks with state transitions
• task_phases - Task phase definitions with ordering (v6+)
• project_profiles - Multi-project support with stack info (v7+)
• routing_patterns - Cross-workflow pattern learning (v7+)
• memory_analytics - Analytics cache for search optimization (v8+)
• memory_tags - Tag system for memory entries (v8+)
• schema_version - Database schema version tracking

Inspection

# View stored conventions
sqlite3 ~/.agents/memory/session.db \
  "SELECT * FROM project_conventions LIMIT 5;"

# View learned preferences
sqlite3 ~/.agents/memory/session.db \
  "SELECT * FROM user_preferences LIMIT 5;"

# View session history
sqlite3 ~/.agents/memory/session.db \
  "SELECT * FROM session_contexts ORDER BY updated_at DESC LIMIT 10;"

# View routing patterns (v2.0)
sqlite3 ~/.agents/memory/session.db \
  "SELECT pattern_key, agent_name, confidence, success_count FROM routing_patterns ORDER BY confidence DESC LIMIT 10;"

# View project profiles (v2.0)
sqlite3 ~/.agents/memory/session.db \
  "SELECT id, name, primary_language, memory_count FROM project_profiles ORDER BY last_accessed DESC LIMIT 5;"

REST API Endpoints

The web dashboard exposes REST API endpoints for integration:

Core Endpoints

Endpoint	Method	Description
/api/stats	GET	Database statistics
/api/contexts	GET	List session contexts
/api/preferences	GET	List user preferences
/api/conventions	GET	List project conventions
/api/interactions	GET	List interactions
/api/tasks	GET	List tasks
/api/tasks/:id	PUT	Update task
/api/tasks/:id	DELETE	Delete task
/api/contexts/:id	DELETE	Delete context

Health Endpoints

Endpoint	Method	Description
/api/health	GET	Full health status
/api/health/ready	GET	Readiness check
/api/health/live	GET	Liveness check

Analytics Endpoints (v2.0)

Endpoint	Method	Description
/api/search	GET	Full-text search
/api/patterns	GET	Detect patterns
/api/temporal	GET	Temporal analysis
/api/conflicts	GET	Detect conflicts
/api/memory-map	GET	Memory visualization
/api/export	GET	Export memories
/api/compact	POST	Optimize database

Task Board Endpoints (v2.0)

Endpoint	Method	Description
/api/task-board	GET	Visual task board
/api/task-insights	GET	Task analytics

Project Endpoints (v2.0)

Endpoint	Method	Description
/api/projects	GET	List projects
/api/projects/:id	GET	Get project
/api/projects	POST	Create project

Routing Pattern Endpoints (v2.0)

Endpoint	Method	Description
/api/routing-patterns	GET	List patterns
/api/routing-patterns	POST	Store pattern
/api/routing-patterns/similar	GET	Find similar patterns

Deployment

Docker

Create a Dockerfile:

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY dist ./dist
COPY public ./public

ENV DASHBOARD_HOST=0.0.0.0
ENV DASHBOARD_PORT=3001
ENV SESSION_DB_PATH=/data/session.db

EXPOSE 3001
VOLUME /data

CMD ["node", "dist/index.js"]

Run with Docker:

docker build -t mcp-session-memory .
docker run -p 3001:3001 \
  -v ~/.agents/memory:/data \
  -e MCP_DASHBOARD_TOKEN=your-token \
  mcp-session-memory

Systemd Service (Linux)

Create /etc/systemd/system/mcp-dashboard.service:

[Unit]
Description=MCP Session Memory Dashboard
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/session-memory
EnvironmentFile=/etc/mcp-session-memory/.env
ExecStart=/usr/bin/node /path/to/session-memory/start-dashboard.js
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable mcp-dashboard
sudo systemctl start mcp-dashboard
sudo systemctl status mcp-dashboard

Troubleshooting

Dashboard won't start

1. Database initialization error or optional helper mismatch:

   The core server does not require better-sqlite3, but some optional helper paths and legacy tests do. If a helper complains about NODE_MODULE_VERSION mismatch, rebuild the optional native dependency:

   npm rebuild better-sqlite3
   

   Typical reasons:

   • Switch Node.js versions (for example via nvm or volta)
   • Upgrade Node.js
   • Copy node_modules from another machine

2. Check if port is in use:

   lsof -i :3001
   

3. Check logs:

   npm run dashboard:logs
   

4. Verify database exists:

   ls -la ~/.agents/memory/session.db
   

Authentication failures

1. Verify token is set correctly:

   echo $MCP_DASHBOARD_TOKEN
   

2. Test without authentication:

   unset MCP_DASHBOARD_TOKEN
   npm run dashboard:start
   

Database errors

1. Check database health:

   ./scripts/health-check-db.sh
   

2. Restore from backup:

   ./scripts/restore-backup.sh
   

Contributing

Contributions are welcome! Please ensure:

1. TypeScript compiles without errors: npm run build
2. Tests pass: npm test
3. Accessibility tests pass: npm run test:a11y
4. CSS is minified: npm run build:css

License

MIT License - see LICENSE file for details

Author

Repository maintainer

Related Documentation

• MCP Server Integration Guide
• OpenCode Agents Reference
• Examples