Forem: pepk

Fixing Claude Code's SIGINT Problem: How I Built MCP Session Manager

pepk — Thu, 01 Jan 2026 18:32:17 +0000

Introduction

In my previous article, I implemented a WAL-mode SQLite backend for Memory MCP to solve database locking issues.

But that wasn't the end of the story.

[MCP Disconnected] memory
Connection to MCP server 'memory' was lost

Every time I opened a new Claude Code session, the existing session's MCPs would disconnect. The WAL mode solved database contention, but there was a completely different problem lurking underneath.

Root cause: Claude Code sends SIGINT to existing MCP processes when starting new sessions.

This article explains how I built mcp-session-manager to solve this problem.

The Problem: SIGINT vs Database Lock

Let me clarify the distinction between the two issues:

Problem	Cause	Solution
`database is locked`	Multiple processes accessing SQLite	WAL mode + busy_timeout
`MCP Disconnected`	New session sends SIGINT to existing MCPs	This article

Even with WAL mode enabled, if the MCP process itself dies, there's nothing to access the database. I needed to rethink the architecture fundamentally.

The Default Architecture (Problematic)

Here's how Claude Code handles MCPs by default:

Session A (Claude Code Window 1)     Session B (Claude Code Window 2)
           |                                    |
           v                                    v
   [MCP Process A-1]                    [MCP Process B-1]
   [MCP Process A-2]                    [MCP Process B-2]
   [MCP Process A-3]                    [MCP Process B-3]
           |                                    |
           +-------- RESOURCE CONFLICT ---------+
                            |
                   [SQLite DB File]
                   [File Watchers]
                   [In-memory State]

When Session B starts:

Claude Code spawns new MCP processes for Session B
Sends SIGINT to existing MCP processes (for some reason)
Session A's MCPs die
Session A shows "MCP Disconnected" error

You might think "just handle SIGINT with process.on('SIGINT', ...)", but that's not enough. Even if the process survives, resource conflicts (like FileWatcher) remain unsolved.

The Solution: 3-Layer Architecture

The solution is straightforward:

"Each session gets a lightweight proxy; actual processing happens in a shared daemon."

Session A                          Session B
    |                                  |
    v                                  v
[Proxy A] -------- HTTP -------- [MCP Daemon]
(stdio)            shared          (HTTP/SSE)
    |                                  |
[Claude A]                        [Claude B]

Design Principles

Singleton Daemons: Each MCP type runs as a single daemon process
Lightweight Proxies: Convert Claude's stdio to HTTP and forward to daemon
SIGINT Immunity: Proxies ignore SIGINT, protecting the shared daemon
Auto-start: Daemons start automatically on first request

Implementation Details

1. SIGINT Handler in Proxy

The most critical part. Set the handler at the very top of the file:

// proxy/index.ts - at the very top
process.on("SIGINT", () => {
  // Ignore SIGINT - let the session continue
  console.error("[Proxy] Received SIGINT - ignoring for multi-session stability");
});

// Imports come after
import { Command } from "commander";
// ...

Key points:

Set before any imports (as early as possible)
Log to stderr (stdout is for MCP protocol)
Do nothing - just ignore it

2. Transport Support

MCP uses different transport formats. I had to support all of them:

MCP	Port	Transport	Notes
memory	3100	streamable-http	Requires Accept header
code-index	3101	streamable-http	SSE response
ast-grep	3102	sse	Deprecated format

// proxy/client.ts
export async function sendRequest(
  client: DaemonClient,
  message: JsonRpcRequest
): Promise<JsonRpcResponse> {
  switch (client.transport) {
    case "sse":
      return sendRequestSSE(client, message);
    case "streamable-http":
      return sendRequestStreamableHttp(client, message);
    case "http":
    default:
      return sendRequestHttp(client, message);
  }
}

3. Streamable-HTTP Transport

Based on MCP 2025-03-26 specification:

async function sendRequestStreamableHttp(
  client: DaemonClient,
  message: JsonRpcRequest
): Promise<JsonRpcResponse> {
  const headers: Record<string, string> = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream"  // This is crucial
  };

  if (client.sessionId) {
    headers["Mcp-Session-Id"] = client.sessionId;
  }

  const response = await fetch(`${client.baseUrl}/mcp`, {
    method: "POST",
    headers,
    body: JSON.stringify(message),
    signal: AbortSignal.timeout(60000)
  });

  // Capture session ID
  const sessionId = response.headers.get("Mcp-Session-Id");
  if (sessionId) {
    client.sessionId = sessionId;
  }

  const contentType = response.headers.get("Content-Type") || "";

  // Handle SSE response
  if (contentType.includes("text/event-stream")) {
    return await handleSSEResponse(response, message.id);
  }

  // Handle JSON response
  return await response.json() as JsonRpcResponse;
}

4. SSE Transport (Deprecated Format)

The ast-grep-mcp uses FastMCP, which implements the deprecated SSE format:

async function sendRequestSSE(
  client: DaemonClient,
  message: JsonRpcRequest
): Promise<JsonRpcResponse> {
  // Initialize SSE session
  if (!client.sseSessionId || !client.sseReader) {
    const sessionResult = await initializeSSESession(client);
    if (!sessionResult.success) {
      return createErrorResponse(message.id, -32603, sessionResult.error);
    }
  }

  // Handle URL format (FastMCP gotcha!)
  let messagesUrl: string;
  if (client.sseSessionId!.startsWith("?")) {
    // Query parameter format: /messages?session_id=...
    messagesUrl = `${client.baseUrl}/messages${client.sseSessionId}`;
  } else {
    // Path format: /messages/<session_id>
    messagesUrl = `${client.baseUrl}/messages/${client.sseSessionId}`;
  }

  // Send request
  const response = await fetch(messagesUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(message)
  });

  // Response comes from SSE stream
  return await waitForSSEResponse(client, message.id);
}

FastMCP Gotcha:

FastMCP's /sse endpoint returns session ID like this:

event: endpoint
data: /messages/?session_id=abc123

Notice the /messages/?session_id=... format instead of the typical /messages/<session_id>. This cost me 2 hours of debugging.

5. stdin Close Handling

Another gotcha: if the proxy exits immediately when stdin closes, it might interrupt in-flight requests.

let pendingRequests = 0;
let stdinClosed = false;

const checkExit = async () => {
  // Only exit when stdin is closed AND all requests are complete
  if (stdinClosed && pendingRequests === 0) {
    log("All requests completed, cleaning up...");
    await closeSession(client);
    process.exit(0);
  }
};

rl.on("line", async (line) => {
  const message = JSON.parse(line) as JsonRpcRequest;

  if (message.id !== undefined) {
    pendingRequests++;
    try {
      const response = await sendRequest(client, message);
      process.stdout.write(JSON.stringify(response) + "\n");
    } finally {
      pendingRequests--;
      await checkExit();
    }
  }
});

rl.on("close", async () => {
  stdinClosed = true;
  await checkExit();
});

6. Auto-start Daemon

The proxy automatically starts the daemon if it's not running:

async function getDaemonInfo(name: string): Promise<{ port: number; transport: TransportType } | null> {
  const config = getDaemonConfig(name);
  if (!config) return null;

  // 1. Ping port to detect existing daemon
  const isAliveOnPort = await pingDaemon(config.port, config.transport);
  if (isAliveOnPort) {
    return { port: config.port, transport: config.transport };
  }

  // 2. Check lock file
  const lockData = readLockFile(name);
  if (lockData) {
    const isAlive = await pingDaemon(lockData.port, lockData.transport);
    if (isAlive) {
      return { port: lockData.port, transport: lockData.transport };
    }
  }

  // 3. Try via Manager API
  const managerResult = await ensureDaemonViaManager(name);
  if (managerResult) return managerResult;

  // 4. Fallback: start directly
  return startDaemonDirectly(name);
}

7. Per-Project Memory Database

After solving the SIGINT problem, I discovered another issue: memory was being shared across different projects.

Content memorized in Project A was visible in Project B. Not good.

Solution: Propagate Project Path via HTTP Header

// proxy/index.ts - detect and send project path
const projectPath = process.cwd();

const headers: Record<string, string> = {
  "Content-Type": "application/json",
  "Accept": "application/json, text/event-stream",
  "Mcp-Project-Path": projectPath  // Send project path
};

memory-mcp-sqlite Side

Using AsyncLocalStorage to manage per-request context:

import { AsyncLocalStorage } from "node:async_hooks";

interface RequestContext {
  projectPath?: string;
}

const asyncLocalStorage = new AsyncLocalStorage<RequestContext>();

// Set context in request handler
app.use((req, res, next) => {
  const projectPath = req.headers["mcp-project-path"] as string | undefined;
  asyncLocalStorage.run({ projectPath }, () => next());
});

// Get DB path from context
function getDbPath(): string {
  const context = asyncLocalStorage.getStore();
  if (context?.projectPath) {
    const projectDbPath = path.join(context.projectPath, ".claude", "memory.db");
    if (canWriteTo(projectDbPath)) {
      return projectDbPath;
    }
  }
  return path.join(os.homedir(), ".claude", "memory.db");
}

Store Caching

Efficiently manage DB connections for multiple projects:

const storeCache = new Map<string, KnowledgeGraphStore>();

function getStore(dbPath: string): KnowledgeGraphStore {
  if (!storeCache.has(dbPath)) {
    storeCache.set(dbPath, new KnowledgeGraphStore(dbPath));
  }
  return storeCache.get(dbPath)!;
}

DB Path Priority

Condition	DB Path
Project path exists & writable	`<project>/.claude/memory.db`
Otherwise	`~/.claude/memory.db`

Benefits:

Memory doesn't mix between projects
Backward compatible with existing global DB
Users automatically get project isolation

Usage

Install

npm install -g mcp-session-manager

Generate Config

mcp-manager generate-config

This creates ~/.claude/mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/mcp-session-manager/dist/proxy/index.js", "--target", "memory"]
    },
    "code-index": {
      "command": "node",
      "args": ["/path/to/mcp-session-manager/dist/proxy/index.js", "--target", "code-index"]
    },
    "ast-grep": {
      "command": "node",
      "args": ["/path/to/mcp-session-manager/dist/proxy/index.js", "--target", "ast-grep"]
    }
  }
}

Restart Claude Code

Restart to apply the new configuration.

Verify

Open multiple Claude Code sessions - they should all work simultaneously without disconnections.

Troubleshooting

Check daemon status

curl http://localhost:3199/status

View daemon logs


type %USERPROFILE%\.mcp-session-manager\memory.log

# macOS/Linux
cat ~/.mcp-session-manager/memory.log

Remove stale lock files

# Windows
del %USERPROFILE%\.mcp-session-manager\*.lock

# macOS/Linux
rm ~/.mcp-session-manager/*.lock

Summary

I built mcp-session-manager to solve Claude Code's SIGINT problem.

Key points:

Proxy layer that ignores SIGINT
Singleton daemon shared by all sessions
Multiple transport support (HTTP, Streamable-HTTP, SSE)
Auto-start with lock file exclusion
Per-project memory DB: AsyncLocalStorage for per-request DB switching

Combined with the previous WAL mode implementation, Claude Code's multi-session and multi-project operation is now fully stable.

Bonus: Auto-start Daemons on Terminal Launch (Windows)

Manually starting daemons every time is tedious. I added an auto-start script to my PowerShell profile.

Add to PowerShell Profile

Add to $PROFILE (usually ~/Documents/PowerShell/Microsoft.PowerShell_profile.ps1):

function Start-McpDaemonsIfNeeded {
    $mcpDir = "C:\path\to\mcp-session-manager"
    $lockFile = "$env:TEMP\mcp-daemons-starting.lock"
    $lockTimeout = 120  # seconds

    # Check if ports are already listening
    try {
        $port3101 = Get-NetTCPConnection -LocalPort 3101 -State Listen -ErrorAction SilentlyContinue
        $port3102 = Get-NetTCPConnection -LocalPort 3102 -State Listen -ErrorAction SilentlyContinue
    } catch {}

    # If both ports are listening, daemons are running
    if ($port3101 -and $port3102) {
        Write-Host "[MCP] Daemons already running" -ForegroundColor Green
        return
    }

    # Lock file prevents duplicate startup
    if (Test-Path $lockFile) {
        $elapsed = (Get-Date) - (Get-Item $lockFile).LastWriteTime
        if ($elapsed.TotalSeconds -lt $lockTimeout) {
            Write-Host "[MCP] Daemons starting..." -ForegroundColor Yellow
            return
        }
        Remove-Item $lockFile -Force -ErrorAction SilentlyContinue
    }

    # Create lock file and start in new terminal
    New-Item -ItemType File -Path $lockFile -Force | Out-Null
    Start-Process pwsh -ArgumentList "-NoExit", "-Command", "cd '$mcpDir'; .\start-daemons.ps1"
}

Start-McpDaemonsIfNeeded

Key Points

Port check: Skip if daemons are already running
Lock file: Prevents duplicate startup when opening multiple terminals simultaneously
Timeout: 120-second lock expiration for crash recovery
Separate terminal: Start-Process pwsh opens daemons in a new window

Now daemons start automatically when you open a terminal.

Resources

npm: mcp-session-manager
GitHub: Daichi-Kudo/mcp-session-manager
Previous article: Fixing Claude Code's Concurrent Session Problem
MCP Transports Spec: MCP Specification

Read on Other Platforms

Qiita (Japanese): Technical details in Japanese
Zenn (Japanese): Technical details in Japanese
note (Japanese): Development story in Japanese

I hope this helps anyone struggling with multi-session Claude Code operation. Issues and PRs welcome!

About the Author

Daichi Kudo

Cognisant LLC CEO - Building the future where humans and AI create together
M16 LLC CTO - AI, Creative, and Engineering

Fixing Claude Code's Concurrent Session Problem: Implementing Memory MCP with SQLite WAL Mode

pepk — Thu, 01 Jan 2026 08:55:47 +0000

The Problem

Have you ever seen this error while running multiple Claude Code sessions?

Error: database is locked

Yeah, that was my first reaction too: "Wait, seriously?"

Memory MCP is an incredibly powerful tool for sharing knowledge across Claude Code sessions, but the official implementation doesn't support concurrent access. So I built a version using SQLite's Write-Ahead Logging (WAL) mode to solve this problem once and for all.

Who This Is For

Developers using Claude Code in their daily workflow
Anyone interested in Model Context Protocol (MCP)
Teams wanting to run multiple AI sessions in parallel
Developers looking for practical SQLite implementation patterns

The Official Memory MCP's Limitations

The official Memory MCP (@modelcontextprotocol/server-memory) stores knowledge graphs in JSONL files. This approach has some serious limitations:

1. No Concurrent Access Support

// Simplified view of the official implementation
const data = await fs.readFile('memory.jsonl', 'utf-8');
// ... process data ...
await fs.writeFile('memory.jsonl', newData);

Without file locking mechanisms, concurrent writes from multiple sessions can corrupt your data. Not ideal.

2. Performance Degradation

The implementation reads all data into memory and performs linear searches. As your knowledge graph grows, queries get slower and slower.

3. No Transaction Support

If a partial update fails, there's no guarantee of data consistency. This is a dealbreaker for production use.

The Solution: SQLite + WAL Mode

I implemented a SQLite-based Memory MCP that solves all these issues.

What Is WAL (Write-Ahead Logging) Mode?

SQLite's WAL mode is genuinely game-changing:

Concurrent reads and writes: Multiple readers and one writer can access the database simultaneously
Crash recovery: Data integrity is guaranteed even if the process crashes mid-write
Faster writes: Log-based approach outperforms traditional rollback journals

It's one of those features that seems simple but changes everything.

Implementation Details

Database Initialization

import Database from 'better-sqlite3';
import path from 'path';
import fs from 'fs';

export class KnowledgeGraphStore {
  private db: Database.Database;

  constructor(dbPath: string) {
    // Create directory if it doesn't exist
    const dir = path.dirname(dbPath);
    if (dir && dir !== '.') {
      fs.mkdirSync(dir, { recursive: true });
    }

    this.db = new Database(dbPath);

    // Enable WAL mode for concurrent access
    this.db.pragma('journal_mode = WAL');

    // Set busy timeout to wait 5 seconds on lock contention
    this.db.pragma('busy_timeout = 5000');

    this.initSchema();
  }
}

Key points:

journal_mode = WAL: Enables concurrent read/write access
busy_timeout = 5000: Waits 5 seconds before throwing a lock error

Without the busy timeout, you'll get immediate lock errors. Trust me, set this.

Schema Design

I structured the knowledge graph using three tables for efficient management:

private initSchema(): void {
  this.db.exec(`
    -- Entities (concepts) management
    CREATE TABLE IF NOT EXISTS entities (
      name TEXT PRIMARY KEY,
      entity_type TEXT NOT NULL
    );

    -- Observations and facts about entities
    CREATE TABLE IF NOT EXISTS observations (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      entity_name TEXT NOT NULL,
      content TEXT NOT NULL,
      FOREIGN KEY (entity_name) REFERENCES entities(name) ON DELETE CASCADE,
      UNIQUE(entity_name, content)  -- Prevent duplicates
    );

    -- Relationships between entities
    CREATE TABLE IF NOT EXISTS relations (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      from_entity TEXT NOT NULL,
      to_entity TEXT NOT NULL,
      relation_type TEXT NOT NULL,
      FOREIGN KEY (from_entity) REFERENCES entities(name) ON DELETE CASCADE,
      FOREIGN KEY (to_entity) REFERENCES entities(name) ON DELETE CASCADE,
      UNIQUE(from_entity, to_entity, relation_type)  -- Prevent duplicates
    );

    -- Indexes for performance optimization
    CREATE INDEX IF NOT EXISTS idx_observations_entity ON observations(entity_name);
    CREATE INDEX IF NOT EXISTS idx_relations_from ON relations(from_entity);
    CREATE INDEX IF NOT EXISTS idx_relations_to ON relations(to_entity);
  `);
}

Design principles:

CASCADE: Automatically delete related data when an entity is removed (no orphaned records)
UNIQUE constraints: Prevent duplicate data
Indexes: Dramatically improve query performance

Those indexes are crucial. Without them, queries slow down fast.

Transaction-Based Updates

createEntities(entities: Entity[]): Entity[] {
  const insertEntity = this.db.prepare(
    'INSERT OR IGNORE INTO entities (name, entity_type) VALUES (?, ?)'
  );
  const insertObservation = this.db.prepare(
    'INSERT OR IGNORE INTO observations (entity_name, content) VALUES (?, ?)'
  );

  const created: Entity[] = [];

  // Process everything in a transaction
  const transaction = this.db.transaction((entities: Entity[]) => {
    for (const entity of entities) {
      insertEntity.run(entity.name, entity.entityType);
      for (const obs of entity.observations) {
        insertObservation.run(entity.name, obs);
      }
      created.push(entity);
    }
  });

  transaction(entities);
  return created;
}

Why transactions matter:

Atomicity: Failed operations don't leave partial changes
Consistency: Multi-table updates maintain referential integrity
Performance: Batch commits are significantly faster

Without transactions, you can end up with corrupted data on errors. I learned this the hard way.

Published as an npm Package

I published this as an npm package so anyone can use it easily.

Installation

npm install @pepk/mcp-memory-sqlite

Configuration for Claude Desktop / Claude Code

Add this to your ~/.claude.json (or global config):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["@pepk/mcp-memory-sqlite"],
      "env": {
        "MEMORY_DB_PATH": "./.claude/memory.db"
      }
    }
  }
}

Configuration tips:

MEMORY_DB_PATH: I recommend per-project databases like ./.claude/memory.db
Global sharing is possible: set to ~/memory.db or similar

Per-project databases are easier to manage in practice.

Comparison with Official Implementation

Feature	Official (JSONL)	This Implementation (SQLite + WAL)
Concurrent access	❌ Not supported	✅ Supported (WAL)
Transactions	❌ None	✅ ACID guarantees
Search speed	Slow (linear)	Fast (indexed)
Data integrity	Weak	Strong (foreign keys)
Crash recovery	❌ Manual repair	✅ Automatic (WAL)

The differences are pretty significant.

Troubleshooting

Error: `database is locked`

If you still get this with WAL mode enabled:

// Increase the busy timeout
this.db.pragma('busy_timeout = 10000'); // 10 seconds

If 5 seconds isn't enough, try 10.

WAL File Growing Too Large

# Run checkpoint to truncate WAL file
sqlite3 memory.db "PRAGMA wal_checkpoint(TRUNCATE);"

Running this periodically keeps the WAL file size under control.

Summary

I built a Memory MCP implementation using SQLite's WAL mode to solve concurrent session problems.

Key takeaways:

WAL mode enables concurrent read/write access
Transactions guarantee data consistency
Indexes provide fast search performance
Published as an npm package for easy use

The WAL mode's concurrent access support is the real game-changer here. Now you can safely run multiple sessions without worrying about data corruption.

Resources

npm package: @pepk/mcp-memory-sqlite
GitHub repository: Daichi-Kudo/mcp-memory-sqlite
SQLite WAL mode: SQLite Write-Ahead Logging

If this helps solve your Claude Code concurrent session problems, I'd love to hear about it! Issues and PRs are always welcome.

Read in Other Languages

Qiita (Japanese): 日本語で読む
Zenn (Japanese): Zennで読む
note (Japanese, Story): 開発ストーリー

About the Author

Daichi Kudo

CEO at Cognisant LLC - Building the future where humans and AI create together
CTO at M16 LLC - AI, Creative & Engineering