Related Pages

Related topics: Claude Hooks and Automatic Context Capture, Data Storage, Memory, and Semantic Search, Tools API, Installation, and Operations

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.

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 [email protected] 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.

Related Pages

Related topics: Project Overview and System Architecture, Data Storage, Memory, and Semantic Search, Tools API, Installation, and Operations

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 [email protected] 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 [email protected], 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

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.

Related Pages

Related topics: Project Overview and System Architecture, Claude Hooks and Automatic Context Capture, Tools API, Installation, and Operations

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 [email protected] 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:

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:

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.

Related Pages

Related topics: Project Overview and System Architecture, Claude Hooks and Automatic Context Capture, Data Storage, Memory, and Semantic Search

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 [email protected], 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

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.

Doramagic Pitfall Log

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
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.12.1. Context: Observed when using node, python
• 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
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.15.0 — Write-stop recovery + continuity quality. Context: Observed when using node
• 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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/leesgit/claude-session-continuity-mcp

4. Configuration risk: Configuration risk requires verification

• Severity: medium
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.13.1. Context: Source discussion did not expose a precise runtime context.
• 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
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/leesgit/claude-session-continuity-mcp

6. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• 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
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• 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
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/leesgit/claude-session-continuity-mcp

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/leesgit/claude-session-continuity-mcp

10. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/leesgit/claude-session-continuity-mcp

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using claude-session-continuity-mcp with real data or production workflows.

• v1.15.0 — Write-stop recovery + continuity quality - github / github_release
• v1.13.1 - github / github_release
• v1.12.1 - github / github_release
• Configuration risk requires verification - GitHub / issue