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

Related MCP server: Follow Plan MCP Server

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

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:

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

Health Endpoints

Analytics Endpoints (v2.0)

Task Board Endpoints (v2.0)

Project Endpoints (v2.0)

Routing Pattern Endpoints (v2.0)

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