# https://github.com/leesgit/claude-session-continuity-mcp Project Manual

Generated at: 2026-07-08 10:25:12 UTC

## Table of Contents

- [Project Overview and System Architecture](#page-1)
- [Claude Hooks and Automatic Context Capture](#page-2)
- [Data Storage, Memory, and Semantic Search](#page-3)
- [Tools API, Installation, and Operations](#page-4)

<a id='page-1'></a>

## Project Overview and System Architecture

### Related Pages

Related topics: [Claude Hooks and Automatic Context Capture](#page-2), [Data Storage, Memory, and Semantic Search](#page-3), [Tools API, Installation, and Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/index.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/index.ts)
- [src/types.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/types.ts)
- [src/schemas.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/schemas.ts)
- [src/storage/database.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/storage/database.ts)
- [src/hooks/index.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/hooks/index.ts)
- [src/utils/logger.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/utils/logger.ts)
- [src/last-work.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/last-work.ts)
- [README.md](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/README.md)
- [package.json](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/package.json)
</details>

# Project Overview and System Architecture

## Purpose and Scope

`claude-session-continuity-mcp` is a Model Context Protocol (MCP) server that preserves the continuity of a Claude session across process restarts, conversation boundaries, and CLI invocations. Rather than rebuilding context from scratch every time a new Claude conversation begins, the server records structured artifacts (user intent, last work in progress, decisions, and tool-call outcomes) and replays them on demand.

The project is published as the npm package defined in `package.json`, where the binary entry point declared under `bin` launches the MCP stdio server implemented in `src/index.ts`. Source: [package.json:1-40](). Because it is consumed by the Claude CLI as an MCP server, the codebase avoids any long-running HTTP surface and instead communicates through JSON-RPC over stdio. Source: [src/index.ts:1-120]().

## System Architecture

The runtime is split into three concentric layers: a thin MCP transport layer, a domain layer that owns the data model and business rules, and a persistence layer backed by a local SQLite database.

```mermaid
flowchart TB
    subgraph Client["Claude CLI / Host"]
        C[stdio / JSON-RPC]
    end
    subgraph MCP["MCP Server (src/index.ts)"]
        T[Transport & Tool Registration]
        H[Hook Pipeline]
    end
    subgraph Domain["Domain Layer"]
        D[last_work, session state, schemas]
    end
    subgraph Store["Persistence"]
        DB[(SQLite via better-sqlite3)]
    end
    C --> T
    T --> H
    H --> D
    D --> DB
    DB --> D
    D --> T
    T --> C
```

The transport layer registers the tools the host can call and serializes responses back over stdio. Source: [src/index.ts:40-200](). The hook pipeline intercepts lifecycle events emitted by the host (for example, session start, message, and end) and writes them through the domain layer. Source: [src/hooks/index.ts:1-80](). The domain layer enforces the typed shape of records, and the persistence layer commits them transactionally.

## Core Components

**Type system and schemas.** Shared TypeScript types live in `src/types.ts`, while runtime validation is enforced by Zod-style schemas declared in `src/schemas.ts`. Splitting static types from runtime schemas lets the server trust tool inputs without re-validating them inside hot paths. Source: [src/types.ts:1-60]() and Source: [src/schemas.ts:1-80]().

**Hooks and lifecycle capture.** Five hooks are wired into the MCP server to observe Claude sessions without blocking them: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `SessionEnd`. Each hook writes a normalized event row through the same `logHookError`-guarded path so that a failure in one hook cannot silently disable the others. Source: [src/hooks/index.ts:20-160]().

**`last_work` extraction.** The continuity endpoint exposes a `last_work` projection, which strips injected command bodies from the raw prompt stream and extracts only the user's genuine request so that resumption starts from the real intent rather than a wrapper script. Source: [src/last-work.ts:1-120]().

**Persistence.** Session rows, hook events, and `last_work` snapshots are stored in a local SQLite database opened via `better-sqlite3`. The wrapper in `src/storage/database.ts` opens the connection lazily, applies the schema migration on first boot, and exposes typed helpers for inserts and reads. Source: [src/storage/database.ts:1-140]().

**Observability.** A small logger utility (`src/utils/logger.ts`) wraps every hook entry point with `logHookError`, ensuring that exceptions are captured to stderr instead of crashing the stdio transport, which would otherwise disconnect the MCP server from the host. Source: [src/utils/logger.ts:1-60]().

## Data Flow and Continuity Quality

A typical lifecycle begins when `SessionStart` writes a new session row keyed by the conversation id supplied by the host. Subsequent `UserPromptSubmit` and tool hooks append event rows referencing that session. When the host next asks the server to resume, the domain layer joins the latest session id with the most recent `last_work` projection and returns a compact summary that the LLM can load into its context window. Source: [src/index.ts:200-340]().

The `v1.15.0` release tightened this path in two ways. First, a Node 26 (ABI 147) runtime change broke the prebuilt `better-sqlite3` native module that the project shipped for ABI 141, which caused all five hooks to fail silently. The dependency was pinned to `better-sqlite3@12.11.1` and `logHookError` was applied to every hook entry so future regressions surface in logs instead of disappearing. Source: [README.md:1-120]().

Second, the `last_work` projection was rewritten to ignore command-body wrappers so that the extracted request reflects what the user actually asked, improving continuity quality on resumption. Source: [src/last-work.ts:30-110]().

## Configuration and Deployment

The server is configured declaratively: the host process passes the MCP server command, and the entry defined in `package.json` boots the stdio server. There is no HTTP port to open and no external service to register; the entire system is a single Node.js process per active Claude session. Source: [package.json:20-60]().

Because persistence is local SQLite, users do not need to provision a database, but they should ensure the runtime version stays within the range the native module supports — a constraint that motivated the v1.15.0 dependency upgrade. Source: [README.md:40-90]().

---

<a id='page-2'></a>

## Claude Hooks and Automatic Context Capture

### Related Pages

Related topics: [Project Overview and System Architecture](#page-1), [Data Storage, Memory, and Semantic Search](#page-3), [Tools API, Installation, and Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/hooks/session-start.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/hooks/session-start.ts)
- [src/hooks/user-prompt-submit.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/hooks/user-prompt-submit.ts)
- [src/hooks/post-tool-use.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/hooks/post-tool-use.ts)
- [src/hooks/pre-compact.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/hooks/pre-compact.ts)
- [src/hooks/session-end.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/hooks/session-end.ts)
- [src/hooks/install.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/hooks/install.ts)
</details>

# Claude Hooks and Automatic Context Capture

## Overview

Claude Code exposes a hook API that lets a project run user-defined scripts at well-defined points in a session's lifecycle (`SessionStart`, `UserPromptSubmit`, `PostToolUse`, `PreCompact`, `SessionEnd`). The `claude-session-continuity-mcp` repository implements one handler for each of these five events under `src/hooks/`. The handlers run transparently inside the user's working copy of Claude Code, and their only job is to copy whatever Claude Code is about to send, just sent, or just finished doing into a local SQLite database that backs the MCP server. When Claude Code later loses working memory (context window compaction, manual `/clear`, new terminal tab), the MCP tools can re-hydrate the conversation from that database so the user does not have to re-explain anything. Source: [src/hooks/session-start.ts:1-40](), [src/hooks/post-tool-use.ts:1-30]().

## The Five Handlers

### `SessionStart` — bootstrap

`src/hooks/session-start.ts` fires once per new Claude Code session. The handler derives a stable `sessionId` from the payload Claude Code sends, opens (or creates) the SQLite database, and inserts a row into the `sessions` table marking the session as active. Without this row, downstream hooks have no foreign key to attach messages to, and the MCP server cannot tell a current run from a stale one. Source: [src/hooks/session-start.ts:1-60]().

### `UserPromptSubmit` — capture user intent

`src/hooks/user-prompt-submit.ts` fires on every user turn. The handler normalizes the raw prompt text and writes a `role='user'` row into the `messages` table. Starting with the v1.15.0 "continuity quality" update, this hook also computes a cleaned `last_work` string by stripping injected command bodies (e.g. `/commit`, slash-commands) so the resume summary reflects what the human actually asked for, not the boilerplate Claude Code prepended. Source: [src/hooks/user-prompt-submit.ts:1-80]().

### `PostToolUse` — capture tool activity

`src/hooks/post-tool-use.ts` fires after Claude invokes any tool (Read, Edit, Bash, Grep, etc.). It records the tool name, the JSON-serialized arguments, and the truncated result into the `messages` table with `role='tool'`. This is the most voluminous writer in the pipeline, and it is the row source the MCP server uses when reconstructing "what files did the agent touch last time." Source: [src/hooks/post-tool-use.ts:1-90]().

### `PreCompact` — snapshot before window collapse

`src/hooks/pre-compact.ts` fires immediately before Claude Code compacts the in-memory transcript. The handler dumps the full conversation slice that is about to be summarized into a dedicated `compaction_snapshots` table, so a `continue_session` call after compaction can still recover the pre-compact text rather than only the lossy summary. Source: [src/hooks/pre-compact.ts:1-50]().

### `SessionEnd` — close the ledger

`src/hooks/session-end.ts` fires when the session terminates (clean exit, `/exit`, or terminal close). It updates the `sessions` row to `ended_at = now`, `status = 'closed'`, and writes a final continuity marker so the next session knows where to resume. Source: [src/hooks/session-end.ts:1-40]().

## Installation and Wiring

`src/hooks/install.ts` is a one-shot CLI that registers all five hook scripts in Claude Code's settings file (`.claude/settings.json`). Each hook entry is added under the matching event name and points at the compiled `dist/hooks/*.js` entry point. Running the installer is idempotent: it detects existing entries and rewrites them rather than duplicating. The MCP server itself is registered in the same pass so that the capture pipeline and the read-side tools land together. Source: [src/hooks/install.ts:1-120]().

## Resilience: the v1.15.0 Fix

The community context for v1.15.0 highlights a silent-failure class that motivated a critical fix. A Node.js 26 runtime ships with native-module ABI 147, but `better-sqlite3@12.0.x` was built against ABI 141. When such a mismatch occurred, the native binding threw at module load, every one of the five hooks crashed before its handler body ever ran, and the entire capture pipeline went dark with no user-visible signal. The release addresses this in two layers:

1. **Dependency pin.** The package now requires `better-sqlite3@12.11.1`, which ships a prebuilt binding compatible with ABI 147, restoring the hooks on a fresh Node 26 install. Source: community release notes for v1.15.0.
2. **`logHookError` guard.** Each handler is wrapped in a top-level `try/catch` that funnels any thrown error to stderr via `logHookError` and returns a non-fatal exit code to Claude Code. A database write failure, schema drift, or permission error therefore can no longer kill the parent Claude Code process. Source: [src/hooks/session-start.ts:1-40](), [src/hooks/post-tool-use.ts:1-30]().

## Data Flow

```mermaid
sequenceDiagram
    participant CC as Claude Code
    participant H as Hook Handler
    participant DB as SQLite (continuity.db)
    participant MCP as MCP Server

    CC->>H: SessionStart
    H->>DB: INSERT sessions (active)
    CC->>H: UserPromptSubmit
    H->>DB: INSERT messages(role=user, last_work)
    CC->>H: PostToolUse (Read/Edit/Bash/...)
    H->>DB: INSERT messages(role=tool)
    CC->>H: PreCompact
    H->>DB: INSERT compaction_snapshots
    CC->>H: SessionEnd
    H->>DB: UPDATE sessions ended_at, status
    Note over MCP,DB: Later: continue_session queries DB
```

Every handler reads the JSON payload from `stdin`, normalizes it, and writes synchronously through `better-sqlite3`. Synchronous writes are intentional: the hook must finish before Claude Code proceeds, and any pending async I/O on process exit would be lost. The MCP server side treats the same SQLite file as read-only, so the two halves of the system never contend on a write lock during normal operation. Source: [src/hooks/user-prompt-submit.ts:1-80](), [src/hooks/session-end.ts:1-40](), [src/hooks/pre-compact.ts:1-50]().

## Operational Notes

- The hooks are pure write paths; they never modify the user's repository. All artifacts live in the SQLite file pointed to by the project's data directory.
- A handler that throws is caught and logged by `logHookError`; the parent Claude Code session continues. This is by design and is what makes the capture pipeline safe to leave installed permanently.
- Because the install step rewrites `.claude/settings.json`, re-running it after upgrading is the supported way to pick up new hook entries or signature changes. Source: [src/hooks/install.ts:1-120]().

---

<a id='page-3'></a>

## Data Storage, Memory, and Semantic Search

### Related Pages

Related topics: [Project Overview and System Architecture](#page-1), [Claude Hooks and Automatic Context Capture](#page-2), [Tools API, Installation, and Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/db/database.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/db/database.ts)
- [src/utils/embedding.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/utils/embedding.ts)
- [src/utils/cache.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/utils/cache.ts)
- [src/tools/memory.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/tools/memory.ts)
- [src/tools/relation.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/tools/relation.ts)
- [src/tools/solution.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/tools/solution.ts)
</details>

# Data Storage, Memory, and Semantic Search

The persistence and retrieval layer of `claude-session-continuity-mcp` is responsible for durable storage of session state, semantic memory entries, entity relations, and validated solutions, and for surfacing the most relevant items back to the agent through vector-based search. The system is built on a local embedded SQLite database, an in-memory LRU cache, and an embedding provider that powers similarity lookup. Together these components form the "memory" of the MCP server.

## Storage Architecture

The persistence layer is centered on a single SQLite file accessed through the `better-sqlite3` native binding. As of v1.15.0, the binding is pinned to `better-sqlite3@12.11.1` to match the Node 26 ABI 147 runtime; an earlier mismatch against ABI 141 silently broke all five session hooks, which is why version pinning and `logHookError` were introduced. Source: [package.json]() (see community context for v1.15.0).

The connection and schema are managed in [src/db/database.ts](). The module exposes a singleton accessor that opens the database in WAL mode for concurrent reads, applies `PRAGMA journal_mode = WAL`, and runs idempotent `CREATE TABLE IF NOT EXISTS` statements for the core tables: `memories`, `relations`, `solutions`, `sessions`, and an `embeddings` table keyed by memory id. Source: [src/db/database.ts:1-80]().

A typical schema excerpt (representative of what the migration code creates) is:

| Table | Key columns | Purpose |
|---|---|---|
| `memories` | `id`, `content`, `tags`, `created_at`, `access_count` | User- and project-scoped facts worth recalling |
| `relations` | `src_id`, `dst_id`, `relation_type`, `weight` | Directed edges between memories or entities |
| `solutions` | `id`, `problem`, `resolution`, `verified` | Validated patterns the agent can reuse |
| `embeddings` | `memory_id`, `vector` (BLOB), `model` | Cached embedding vectors for fast similarity search |

All write paths funnel through prepared statements so the same query plan is reused across calls, and a single `withTransaction(fn)` helper wraps multi-row inserts to keep the WAL from fragmenting.

## Memory Tool

The user-facing memory interface lives in [src/tools/memory.ts](). It exposes `memory_add`, `memory_query`, `memory_update`, and `memory_delete`. Each method validates input against a Zod schema, normalizes tags to lowercase, and calls the database layer. Source: [src/tools/memory.ts:1-60]().

`memory_query` is the most complex path: it accepts either an exact text match, a tag filter, or a free-form natural-language prompt. When a prompt is supplied the tool embeds it (see next section), retrieves the top-k memory rows by cosine similarity, increments `access_count` for hits, and returns the rows ordered by score. The result payload includes the raw `content`, the similarity score, and a `recency` hint derived from `created_at` so callers can bias toward fresh context. Source: [src/tools/memory.ts:60-140]().

## Embeddings and Semantic Search

Embedding generation is isolated in [src/utils/embedding.ts](). The module abstracts the model provider behind an `Embedder` interface with a single async `embed(text: string): Promise<Float32Array>` method, allowing the default OpenAI-compatible endpoint to be swapped for a local model via configuration. Source: [src/utils/embedding.ts:1-40]().

Vectors are stored as packed `Float32Array` BLOBs in the `embeddings` table, accompanied by the model name and the source text hash. Cosine similarity is computed in pure JavaScript inside the tool layer; for corpora above a few thousand rows the implementation falls back to a NumPy-style prefilter that loads only the row ids and vectors into memory, avoiding a full table scan. Source: [src/utils/embedding.ts:40-95]().

The following diagram shows how a query flows from the tool layer to the storage layer and back:

```mermaid
flowchart LR
  A[memory_query] --> B[Embedder.embed]
  B --> C[vector BLOB]
  C --> D[cosine similarity scan]
  D --> E[top-k memories]
  E --> F[increment access_count]
  F --> G[return ranked results]
```

## Relations and Solutions

Beyond raw memory, the system models how memories connect to each other and to reusable solutions. [src/tools/relation.ts]() provides `relation_add`, `relation_list`, and `relation_traverse`, which follow directed edges of arbitrary `relation_type` (e.g., `caused_by`, `supersedes`, `blocks`). Traversal is depth-limited and uses an in-memory adjacency cache so repeated graph walks do not re-query SQLite. Source: [src/tools/relation.ts:1-120]().

[src/tools/solution.ts]() manages the `solutions` table, which is distinct from memory because entries here are explicitly marked `verified` by the user or by a successful self-check before they become eligible for retrieval. The `solution_search` tool combines an embedding lookup with a `verified = 1` filter and a minimum score threshold, ensuring the agent is only suggested resolutions the system has confidence in. Source: [src/tools/solution.ts:1-90]().

## Caching and Resilience

To avoid re-embedding identical prompts and re-walking hot subgraphs, [src/utils/cache.ts]() implements a small LRU cache keyed by a SHA-256 hash of the input string. Embedding results and serialized relation traversal paths are cached with a configurable TTL; the cache is process-local and is invalidated on database writes that touch the corresponding rows. Source: [src/utils/cache.ts:1-70]().

Resilience was tightened in v1.15.0: the new `logHookError` helper wraps every hook invocation so that a storage failure (such as the ABI mismatch that previously killed writes) is logged and surfaced rather than silently dropping data. This means a temporary SQLite issue now degrades gracefully to a no-op write with a warning, instead of corrupting the continuity contract with the agent. Source: community context, v1.15.0 release notes.

## Practical Notes

- The database file is created on first run in the working directory; users who want isolation across projects can pass a custom path through the server's `DB_PATH` environment variable.
- Embedding model selection is configured globally; mixing vectors from different models in the same table will produce incorrect similarities, so the schema records `model` per row to detect drift.
- For best recall quality, callers should write memory entries as self-contained facts rather than fragmented snippets, and should use `relation_add` to link related entries so graph traversal can supplement pure vector search.

---

<a id='page-4'></a>

## Tools API, Installation, and Operations

### Related Pages

Related topics: [Project Overview and System Architecture](#page-1), [Claude Hooks and Automatic Context Capture](#page-2), [Data Storage, Memory, and Semantic Search](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/tools/index.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/tools/index.ts)
- [src/tools-v2/index.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/tools-v2/index.ts)
- [src/tools/session.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/tools/session.ts)
- [src/tools/project.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/tools/project.ts)
- [src/tools/task.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/tools/task.ts)
- [src/tools/verify.ts](https://github.com/leesgit/claude-session-continuity-mcp/blob/main/src/tools/verify.ts)
</details>

# Tools API, Installation, and Operations

## Overview

The Tools API is the public contract an MCP client invokes to manage sessions, projects, tasks, and integrity checks for the continuity layer. Registration is split between two parallel entry points: a stable v1 set in `src/tools/index.ts` and an iterative v2 set in `src/tools-v2/index.ts`. Each entry point imports individual tool definition modules and concatenates them into a single list that the MCP server exposes. Source: [src/tools/index.ts:1-50](), [src/tools-v2/index.ts:1-50]().

Conceptually, the system has two paths that share one SQLite store: a **write path** made of five Claude Code hooks, and a **read/mutate path** made of the tools listed in the registration files. The Tools API only ever sees the database; the hooks are the producers. This separation matters for operations because a native-module failure used to break the write path silently while leaving the read path responsive, producing empty results with no error to the client.

## Installation

The server is distributed as a Node package and depends on the native `better-sqlite3` binding for synchronous on-disk persistence. As of v1.15.0 the required version is `better-sqlite3@12.11.1`, which restores compatibility with Node 26 / ABI 147. Source: [package.json]() (per release notes).

The install sequence is:

1. Install dependencies in the project root.
2. Confirm the native module loads under the host's Node ABI.
3. Register the MCP server with the host (Claude Code, Claude Desktop, or any compatible client).
4. Invoke the `verify` tool to confirm write and read paths are healthy.

A pre-v1.15.0 mismatch between Node's ABI and the prebuilt `better-sqlite3` binary silently disabled the persistence layer. Hooks fired, but writes never reached the database, which in turn made `last_work` return stale or empty data. The v1.15.0 fix pins a compatible native build and adds a `logHookError` helper so any hook failure surfaces in logs instead of being swallowed. Source: [CHANGELOG / release notes v1.15.0]().

## Tool Modules

Each tool module exports a definition object that the registration file imports. The four canonical v1 tools are described below.

### session
`src/tools/session.ts` defines operations for creating, resuming, and ending sessions, plus retrieval of the most recent activity summary (`last_work`). The v1.15.0 release refined `last_work` to skip injected command bodies and extract the real user request, reducing noise in resumed context. Source: [src/tools/session.ts:1-120]().

### project
`src/tools/project.ts` exposes project-scoped operations: binding a working directory to a project identifier, listing known projects, and updating project metadata. Tools that mutate project state validate the supplied path before writing. Source: [src/tools/project.ts:1-100]().

### task
`src/tools/task.ts` manages the task list attached to a session, including create, list, update, and complete. Tasks are persisted in the same SQLite store as session metadata, which is what enables continuity across restarts. Source: [src/tools/task.ts:1-150]().

### verify
`src/tools/verify.ts` provides health-check and integrity operations. It is the recommended entry point for diagnosing whether hooks are active and whether the database is reachable, and it is the first tool to call after a fresh install or upgrade. Source: [src/tools/verify.ts:1-80]().

## Operations, Hook Wiring, and Migration to v2

| Layer | Responsibility | Failure surface before v1.15.0 |
| --- | --- | --- |
| Five hooks | Capture events, write to DB | Silently failed on ABI mismatch |
| Tools API | Read/mutate DB on demand | Returned empty or stale results |
| `logHookError` | Surface every hook error | New in v1.15.0 |

Operational checklist:

- Confirm `better-sqlite3` loads by calling the `verify` tool after install.
- Watch the server log for `logHookError` output during the first session; any line that mentions a hook name and a SQLite error is a hard failure to investigate, not noise.
- If `last_work` returns an injected command body instead of a real request, upgrade to v1.15.0+ where the extraction logic is corrected.

`src/tools-v2/index.ts` is the staging area for the next tool surface. It is exported alongside the v1 list so that clients can opt in by name. Until v1 is deprecated, both registrations are served concurrently, and new tool names should generally be added in v2 first. Source: [src/tools-v2/index.ts:1-60]().

When operating the server, treat the `verify` tool and the hook log as the two observability surfaces: `verify` confirms the read path is healthy, and `logHookError` lines confirm whether the write path is healthy. Both must be green for the continuity guarantees advertised by the Tools API to actually hold.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: leesgit/claude-session-continuity-mcp

Summary: Found 10 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v1.12.1
- User impact: Upgrade or migration may change expected behavior: v1.12.1
- Evidence: failure_mode_cluster:github_release | https://github.com/leesgit/claude-session-continuity-mcp/releases/tag/v1.12.1

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v1.15.0 — Write-stop recovery + continuity quality
- User impact: Upgrade or migration may change expected behavior: v1.15.0 — Write-stop recovery + continuity quality
- Evidence: failure_mode_cluster:github_release | https://github.com/leesgit/claude-session-continuity-mcp/releases/tag/v1.15.0

## 3. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/leesgit/claude-session-continuity-mcp

## 4. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.13.1
- User impact: Upgrade or migration may change expected behavior: v1.13.1
- Evidence: failure_mode_cluster:github_release | https://github.com/leesgit/claude-session-continuity-mcp/releases/tag/v1.13.1

## 5. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/leesgit/claude-session-continuity-mcp

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/leesgit/claude-session-continuity-mcp

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/leesgit/claude-session-continuity-mcp

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/leesgit/claude-session-continuity-mcp

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/leesgit/claude-session-continuity-mcp

## 10. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/leesgit/claude-session-continuity-mcp

<!-- canonical_name: leesgit/claude-session-continuity-mcp; human_manual_source: deepwiki_human_wiki -->