DEV Community: pepk

Keeping up with the AI: how one person runs nine Claude Code sessions in parallel

pepk — Fri, 04 Sep 2026 10:16:56 +0000

Give each project its own session and Claude Code writes in six of them, or nine, at the same time. The writing is no longer the constraint. The constraint is me, one person, taking in that output and issuing the next instruction.

So what I spend the most time on now is not deciding what to have the AI do. It is the work of keeping up with it. That splits in two.

Perception. Make what just happened, and whether the output is correct, readable by a human.
Instruction. Hand over what I want changed and what I want enforced, without explaining it at length in prose.

Neither is built once and left alone. Fixing skills, tidying CLAUDE.md and memory, keeping the single source of truth honest, maintaining an index: it continues as daily upkeep. This article is a record of where that stands.

A note on the division of labor. The implementation, the git operations, the scripts, and the pane described below were all written by Claude sessions, not by me. What I do is verify the deliverables and maintain the instructions the sessions work under, which live in CLAUDE.md, in skills, and in memory.

I run LLM system development at Cognisant LLC, on contract. I do the engineering myself and I handle all customer communication myself. On a normal weekday six or more sessions run in parallel, and nine is not unusual.

Claude Code is a product of Anthropic. Nothing here is official guidance; it is one practitioner's operating procedure.

1. Perception: put state and output in a readable form

Verify behavior and documents, not code

I moved what I verify off the code. Instead of reading the code myself, I do two things: run it and watch the actual behavior, and have Claude write the overall picture up as a document, then read that. The reason is not only speed. At the current model level, I find this catches more errors than reviewing the code myself, and drift in quality and direction shows up earlier.

The same documents, screenshots and video go straight to customers and teammates. When one person holds the whole engagement, it helps that what I make in order to verify is the same thing I make in order to explain.

Have documents produced in readable archetypes

If the overall picture arrives as a document, the document itself has to be readable. So the archetypes sit as templates inside a skill, and nothing gets built from a blank page.

What I want to see	Archetype	Where it fits
Who does what at which step	Current-state flow, swimlane	Process improvement. Shows where load and risk concentrate
How one document moves through approvals	Approval flow	Sign-off, applications, acceptance
A user's sequence of actions and their results	Use-case flow	App mockups, manuals, proposals
Something to project and argue over	Slide deck	Proposals and kickoffs, with an annotation layer and presenter view
Something to read and decide on alone	A4 handout	Specs, reports, anything distributed

With archetypes, naming one gets the same skeleton back every time, and I can read it knowing the same information sits in the same place. Before anything is built, the session writes a six-line reader-journey brief: who reads it, where they open it from, what they decide on the first screen, where the decision happens, what they do next, and what makes it obsolete.

Excel output works the same way. It is finished so it reads in one pass, with column widths, wrapping, row heights and zoom all set, then exported to PDF and checked on screen for clipping and overlap before it reaches me.

A window for what just changed

With six or nine running at once, a new file appears somewhere every few minutes. Walk the terminals asking each session what it wrote, and finding takes longer than checking.

What I wanted was one screen showing where things just moved, opening on click, outside the terminal. I have used Sublime Text for years, so the pane lives there: Recent Activity. Claude Code designed and implemented it; what I decided was where it sits and what it shows. It is open source (sublime-claude-code, MIT), and it is an unofficial community plugin, not affiliated with or endorsed by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic, PBC.

24h  ·  docs & media
▼ data-platform  5 ●2
  ● dataplat-tiles
  * 14:52 STATUS.md
    14:51 …/status_archive/2026-09.md
  ○ dataplat-seo
    14:50 …/snapshots/state.json  ⟨.wt-x⟩  ×3
▶ manufacturing-client  12

Files changed in the last 24 hours, grouped project, then session, then file, newest first, opening on click. Documents and media by default (md, txt, html, pdf, xlsx, docx, pptx, csv, images, video); c adds code files. A project is the directory claude was launched in, and a tool call that changes into a subdirectory does not split it. Projects I do not need to watch are hidden with h.

Underneath, a filesystem watcher supplies what changed and a Claude Code hook supplies which session wrote it, and the two are joined. Scanning modification times across the whole tree was dropped after it took 99 seconds on a project holding 1.58 million files. One weakness remains: when two sessions in the same project run shell commands at the same time, a file cannot be attributed to either.

There is a window in the other direction too. Sessions have a small command-line tool that opens a file in Sublime themselves, and CLAUDE.md tells them to use it whenever they produce something I should look at. Rather than going to find deliverables, I have them brought to me.

2. Instruction: stop explaining fixes in prose

Perception alone does not keep up. Explaining every correction in sentences is its own bottleneck, so the channel changes by domain.

Domain	How instruction is delivered	What that means
Frontend	Tweak	Select elements in the browser and adjust type size, spacing, position and wording by hand, then hand the diff over as JSON. The session converts it into Tailwind classes or design tokens, applies it to the source, and verifies with before and after screenshots
Documents and slides	Annotation	Click anywhere on the document to attach a note, export the notes as JSON, and that is the correction request. No writing out "the top right of the figure on slide 3"
Backend	Engineering judgment	No tool removes this one. Design, boundaries and contracts get settled first, tests get written first, and fixes go one layer and one variable at a time with before and after differences measured across every category. The judgment stays on the human side
Infrastructure	Monitoring and logs	Behavior is only visible through monitoring and logs. Log design, failure-rate visibility, and a cost checkpoint go into operations: requests divided by human page views above 100 means the structure is wrong

Frontend and documents move toward not explaining in words at all. Backend and infrastructure move toward applying human judgment and observation. The word "instruction" covers both, but the instrument that works differs by domain.

Confirmations are multiple choice

When a session is unsure, it does not send back an open question. It forms a hypothesis, offers options with the recommended one first, and where the answer could branch, answers both branches in advance. The point is to get my reply down to one tap.

Rules live where they will actually be read

Where a rule sits determines whether it works.

Cross-cutting rules go in CLAUDE.md, which applies to every project
Rules tied to an action go in that action's skill self-check, read immediately before creating a pull request or sending something outside the company
Memory is for handover between sessions, not for rules. A rule there is not consulted at the moment of action
Project design decisions stay in that project's design docs, decision records and status file, and are not promoted to global

That split was decided after the same defect recurred three times in one day: screenshot links in pull requests lost their ?raw=true and rendered as broken images. The rule existed. It was in memory, and memory was not consulted at the moment the pull request was created.

Instructions get written down the moment they are given

When I say "from now on", "always" or "never" in conversation, the session does not treat having said it as the record. Within the same turn it decides where the rule belongs, writes it, and ends its reply with the path it wrote to. At the end of a session, a script cross-checks the instruction words in the conversation log against the files that were actually updated. It stops instructions from evaporating into chat.

3. The parallel foundation

Adding sessions produces defects in three places: identity, git, and shared machine state. These are fixed as instructions, and six or nine sessions now run without trouble.

Naming. Launch with claude --name <project>-<task>, and never run parallel on auto-generated names. The name is also the address for messages between sessions.
Isolate git with worktrees. In any project where parallel sessions can run, git worktree add first, then edit and commit inside the worktree. Since isolation became the default, defects on the git side have essentially stopped. It is the single most effective rule in the whole setup. Commits are chained to a branch check inside the same command, and git add takes explicit paths only.
Switch shared machine state inside one command. Write it as gh auth switch --user … && gh pr create …. Split across two commands, another session may switch the account in the gap, and the pull request opens under the wrong identity. Nothing raises an error.
Let sessions talk to each other. Claude Code sessions can message each other directly. I use it for declaring intent before touching a shared worktree, announcing what landed on main, and getting a single notification when another session goes idle.

One example of that last channel. The session that drafted this article took over open-source work from another session. My part was one sentence telling it to request the handoff. The handoff itself went between the sessions: the repository HEAD, whether anything was uncommitted, prioritized next actions, and the task-tracker ID.

4. Daily maintenance

None of this is a fixed installation. It gets repaired on roughly this cadence.

Skill and CLAUDE.md audit. Twice a year, against a written rubric, across every skill and agent definition. Is any canonical location now duplicated? Does each front-matter description still match what the skill actually does?
Memory audit. Take stock of memory across all projects, promote anything cross-cutting to global, and send project-specific design decisions back to the project they belong to.
Index upkeep. One hub page maps every asset, covering the config directory, business documents and development work, updated whenever a project is added or moved. Knowing where things are pays off more as projects accumulate.
A terminology ledger. When a session reaches for an unnatural literal translation, one line gets added: the term to avoid, and what to say instead.

Every one of these was added after a session got something wrong. The individual diffs are small. Stacked up, they are what keeps "able to keep up" true.

Closing

"More sessions, more throughput" is a common claim. In my case, running more only got easier once the human side, perception and instruction, was in place first. Without that, time spent searching and time spent explaining cancel the gain.

The important question is not how to make the AI faster. It is how one person keeps up with that speed. What is written here is today's answer, and tomorrow I will be fixing another line of it. If you are doing the same thing, I would like to hear in the comments where you have put your effort on perception and on instruction.

Resources

GitHub: Cognisant-llc/sublime-claude-code, MIT, Sublime Text 4, unofficial community plugin
The design argument: Don't Switch Your Editor, Connect the Agent
Protocol reference: claudecode.nvim PROTOCOL.md

Read this elsewhere

Zenn (Japanese, canonical): 人間が AI の速度に追いつくための運用
note (Japanese, the everyday-life version): AI の速度に、人間はどう追いつくか

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