Skip to main content
Glama

SessionRelay 会话接力

English | 简体中文

CI npm downloads Node MCP Platform Semantic License

A local memory layer that belongs to your project — not to any vendor. Memory is always complete. Retrieval is always yours to shape.

You spent three days settling an architecture with your AI. That shouldn't vanish when the window closes. It belongs to the project — and to whoever picks it up next.

📖 中文文档:README.md

60-second demo

SessionRelay demo

The GIF is silent — full narrated versions (English / 中文, plus a 9:16 vertical cut) are playable directly on the Releases · v0.2.2 page.

Related MCP server: mnemolith

What it solves

Pain point

SessionRelay's answer

Amnesia across time: you ask a new session "what did we decide last week?" — the AI has no idea

Search historical sessions on demand, with mandatory provenance

Fragmentation across tools: the plan was settled in Claude Code; ZCode knows nothing

Multi-source, one database — any agent queries the same memory via MCP

Handoff across people: you spent 3 days with your AI; your teammate inherits "go read the code"

Export a .hop handoff package — their AI instantly owns the full context

The architectural difference vs. claude-mem: session-level storage

This is the core design decision — not a feature difference, a storage-granularity difference:

Fragment memory (claude-mem style)

SessionRelay

Unit of storage

compressed shards, mixed across sessions

complete sessions (title / timeline / source / status / decisions)

What the AI sees

"you once said..." shards

"ZCode session Database Selection, Aug 20, message 12..."

Hallucination risk

high: context pollution + compression distortion + no provenance

structurally suppressed: mandatory provenance + on-demand queries + jump back to the original text

Three anti-hallucination commitments (architecture, not features):

  1. Mandatory provenance — every answer must cite which session, which message, which tool. Traceable sources leave no room for confident guessing.

  2. Pull, not push — the AI queries only when needed. Clean context, no ambient memory pollution.

  3. Original text, always — the AI gets the full raw conversation, not a pre-chewed summary. The "why" survives.

Architecture overview

Everything you discuss with any AI tool flows into one project-level database; you, your AI, and your teammates can all query it. Switch tools without losing memory. Switch people without losing context.

graph TB
    subgraph Sources["🖥️ Your AI coding tools (each in its own silo)"]
        CC["Claude Code<br/>JSONL files"]
        ZC["ZCode<br/>SQLite database"]
        CX["Codex<br/>JSONL files"]
        QD["Qoder<br/>JSONL files"]
        TR["Trae<br/>partial*"]
    end

    subgraph Relay["🧠 SessionRelay (local memory layer)"]
        DAEMON["daemon (watch)<br/>auto-sync every 30s"]
        DB[("relay.sqlite<br/>unified memory")]
        EXTRACT["structured extractors<br/>decisions · topics · summaries · key exchanges"]
    end

    subgraph Consumers["👥 Who queries the memory"]
        YOU["You (CLI)<br/>search · decisions · history"]
        AGENT["AI agents (MCP)<br/>16 tools"]
        TEAM["Teammates (.hop handoff)<br/>export → import"]
    end

    CC -->|adapter| DAEMON
    ZC -->|adapter| DAEMON
    CX -->|adapter| DAEMON
    QD -->|adapter| DAEMON
    TR -.->|user prompts only| DAEMON
    DAEMON --> DB
    DB --> EXTRACT
    DB --> YOU
    DB --> AGENT
    DB --> TEAM

    style Relay fill:#1a1a2e,color:#e94560
    style Sources fill:#16213e,color:#fff
    style Consumers fill:#0f3460,color:#fff

* Trae encrypts assistant replies end-to-end; only user prompts are readable. Tool not on the list? Write a custom adapter — zero core changes.

Memory lifecycle

Every session passes through a two-phase verdict. Better to wait than to crystallize an unfinished conversation:

stateDiagram-v2
    [*] --> active: conversation starts / daemon captures
    active --> pending_end: 10 min without new messages
    pending_end --> active: you resume (revival)
    pending_end --> confirmed: 6 h of silence
    active --> active: new messages appended
    confirmed --> active: new message (rollback + re-extraction)
    confirmed --> archived: srelay archive
    archived --> active: new message arrives (revival)

    confirmed: ✅ Confirmed
    confirmed: decisions/topics extracted
    confirmed: enters the main full-text index

    archived: 📦 Archived
    archived: skeleton kept (decisions/topics)
    archived: bodies released (99.4% space)

Why the pending stage exists: conversations resurrect (you --resume the next morning). Crystallize too early and the extracted decisions are incomplete. Pending is a 6-hour buffer; even after confirmation, appended messages trigger a rollback and re-extraction. Raw session files remain the single source of truth — the database can always be rebuilt with srelay rebuild.

Core capabilities

🖥️ Passive capture (zero friction)

  • Five-source adapters: Claude Code · ZCode · Codex · Qoder (full) + Trae (partial: user prompts only) + custom adapters (drop in one JS file, zero core changes)

  • Three privacy modes: full (default) / meta (metadata only) / off (manual only)

  • .sessionrelayignore hard boundary: privacy exclusions apply to auto-capture, manual save, and export alike

  • Two-phase verdict: active → pending_end → confirmed, auto-rollback on resume; raw session files are the single source of truth (the DB is always rebuildable)

  • Backfill: srelay init backfills the last 30 days by default; srelay sync --backfill all imports your full history

  • jieba tokenization + SQLite FTS5 dual indexes (gated by six Chinese acceptance cases)

  • Session-level AND coverage with OR fallback: compound words split ("认证方案" → 认证 + 方案), quoted phrases match exactly ("按月分区")

  • Every result carries a mandatory provenance block (session ID / source tool / date / message numbers / snippet)

  • Semantic search (optional): srelay semantic enable — paraphrased queries now hit ("登录" ↔ "authentication", "很卡" ↔ "performance"). Local CPU inference (bge-small-zh), zero cloud; literal hits always rank first and are never replaced — semantic only appends, flagged viaSemantic, capped at top-5. Not enabled = byte-identical behavior to pure literal search. Measured: synonym-query miss rate 33% → 0%

🧹 Right to be forgotten (srelay forget)

Deletion belongs to humans — AI / MCP tools have zero delete power (tool list stays at 15, forever):

srelay forget a3f8c2d1        # preview (what gets removed vs kept)
srelay forget a3f8c2d1 --yes  # execute (irreversible)
srelay forget --history       # audit of what was forgotten when
  • Rule of thumb: aging & disk space → archive; make one conversation disappear forever → forget

  • Dual anti-resurrection barriers: a precise .sessionrelayignore rule (survives rebuild) + a tombstone table — the raw file stays on disk but is never re-ingested

  • Prefix ambiguity guard: multiple matches are listed and rejected, never silently picking one

🤖 MCP Server (16 tools: 9 read + 7 write-domain)

Once your AI agent connects via MCP, it stops being amnesiac in this project:

Tool

Question it answers

search_sessions

"Did we ever discuss X?" (Chinese/English full-text + metadata filters)

get_session_detail

"What exactly did we say?" (full messages, ranged, role-filtered)

list_sessions

"What topics has this project covered?"

get_decisions

"Why X instead of Y?" (all confirmed decisions, with provenance)

get_file_history

"Why is this file written this way?" (cross-session file discussion history)

suggest_related_sessions

"What else relates to this discussion?" (algorithmically discovered, explainable reasons)

get_unresolved

"What's still undecided?" (open questions)

get_stats

"How big is the memory?" (sessions/sources/size)

set_scope

Retrieval-boundary escape hatch

Tool

Capability

Safety boundary

annotate_session

tag sessions / write human summaries

metadata only, never rewrites conversations

save_note

AI records conclusions as notes (decision phrasing enters the decision library)

source=note, identifiable and auditable

export_handoff

produce a .hop handoff package

read-only export

import_handoff

import a package (sha256 verified + normalized)

quarantine by default (bodies pending release)

release_quarantine

release quarantined message bodies

explicit call required

link_sessions

relate sessions (continues/related/pinned)

links are queryable and revocable

get_linked_sessions

bidirectional link queries

read-only

Write-domain principles (D21): bypass the write path (never touches the state machine) · import defaults to quarantine · notes are traceable — every AI write is identifiable, auditable, revocable.

🖥️ Local dashboard (srelay ui, new in 0.6.0)

A third thin presentation layer: CLI, MCP, and the browser share the same query functions — zero core changes, zero new dependencies.

  • Registry overview: cards for every registered project — session composition, source distribution, disk usage, daemon liveness

  • Project detail: interactive growth chart (messages + active-sessions dual metric, click a bar to drill into that day), full-text filter, health cards with the daemon log tail

  • Session drill-down: metadata, decisions, open questions, paged message flow, and in-session keyword search — click a hit or a decision to jump to that message, highlighted

  • First write op — session forget: the exact same core as CLI srelay forget (transactional delete + tombstone + ignore-rule anti-resurrection + audit), behind a confirmation dialog; message-level deletion deliberately not offered (sessions are immutable, forgetting is session-granular)

  • Security model: off by default · binds 127.0.0.1 only · one-time token + Host validation (anti DNS-rebinding) · never returns CORS headers · foreground lifecycle (Ctrl-C stops it)

srelay ui    # start the local dashboard (random port + one-time token, opens the browser)

🎯 Scope: retrieval boundaries

  • Tier B: scope.json project contract (shared by CLI and MCP), intersection semantics — can only narrow

  • Tier A: auto-scope backstop (MCP-side, recent-30-days configurable) against context pollution

  • attach: mount specific historical sessions before starting new work (highest-priority predicate)

  • Hot reload: scope changes take effect on the next call

📦 HOP handoff protocol (hop/1.0, open format)

  • Standalone protocol spec (MIT, vendor-neutral, third-party readers welcome)

  • Per-file sha256 integrity (any tampering rejects the whole package)

  • Default secret redaction: AWS keys / private keys / Bearer tokens / password assignments / DB connection strings, with a redaction report

  • Quarantined import: metadata and summaries first; bodies released one by one — a structural defense against prompt injection

  • HANDOFF.md generated automatically (decision table / files involved / open questions / timeline / signature footer)

  • Cross-project import: packages land in any project path or name (auto-normalized, origin_project kept for provenance)

Quick start

Requires Node ≥ 22 (Windows / macOS / Linux):

# Option 1: npm (recommended)
npm install -g @ewanjasper/sessionrelay

# Option 2: zero-install trial
npx @ewanjasper/sessionrelay init

# Option 3: from source
git clone https://github.com/EwanJasper/SessionRelay.git
cd SessionRelay && npm install && npm run build && npm link

Initialize a project

cd your-project
srelay init                  # initialize + backfill last 30 days (last month searchable within a minute)
srelay sync --backfill all   # or backfill your entire history (old sessions auto-confirm + extract decisions)

Daily use

srelay search 中文关键词 [--topic --source --since --json]
srelay decisions         # all confirmed decisions, with provenance
srelay history src/db/   # which sessions discussed this file
srelay watch --install-service  # register the daemon (Windows), starts at login
srelay doctor            # environment self-check

Team handoff

srelay export --all      # handoff package (redacted by default) → send to a teammate
# The teammate, in any project root:
srelay import xxx.hop --from your-name

👉 Full walkthrough (five scenarios: project handoff / onboarding / safe import / cross-project migration / periodic archiving): Import & Export Guide

⚠️ Why the daemon is not optional

ZCode physically deletes old messages on context compaction (measured: one compaction deleted 3,976 messages from a long session). The daemon syncs every 30 seconds so messages land in the database before deletion.

Without the daemon: anything the AI compacts between two manual syncs is permanently lost.

srelay watch --install-service   # Windows registry autostart (no admin required)
srelay watch --foreground        # macOS/Linux foreground (service registration in progress)

Daemon overhead: ~0% idle CPU (event-driven), ~80MB memory (resident Node.js), negligible incremental disk I/O, zero network calls.

timeline
    title Without vs. with the daemon
    Without daemon : you chat (messages land in ZCode's store) : AI triggers context compaction : 💥 ZCode physically deletes messages : you remember to run sync : ❌ only the compaction summary remains; the original text is gone
    With daemon : you chat (messages land in ZCode's store) : daemon syncs within 30s : AI triggers compaction : ZCode deletes messages : 😌 no problem — the original text is already in your memory : the compaction summary is captured too

MCP integration

Claude Code (one command)

claude mcp add sessionrelay --scope user -- srelay serve

Run /mcp in Claude Code — sessionrelay should show as connected with 16 tools ready.

ZCode / other MCP clients

Add to your project's MCP config (.mcp.json or client settings):

{
  "mcpServers": {
    "sessionrelay": { "command": "srelay", "args": ["serve"] }
  }
}

Qoder users: Qoder launches MCP subprocesses without setting the working directory to the project root. Since 0.5.0 this needs no config: serve tries the MCP roots protocol (asks the client "which workspace") first, then the global project registry (auto-selects when exactly one project is alive); if neither resolves, the connection stays up and the first tool call returns a candidate list — the AI passes project once to pick (remembered for the connection). The env var below remains the most robust explicit pin.

Most robust fallback (any MCP client, bypasses PATH / cwd issues)

SRELAY_PROJECT_ROOT pins the project root regardless of the subprocess working directory — it saves you when PATH cannot resolve srelay or when the client does not set cwd (Qoder, in practice).

{
  "mcpServers": {
    "sessionrelay": {
      "command": "node",
      "args": ["/your/install/path/SessionRelay/dist/srelay.js", "serve"],
      "env": { "SRELAY_PROJECT_ROOT": "/your/project/path" }
    }
  }
}

How to verify it works

Open a fresh AI session and ask:

"Why did we decide on PostgreSQL?"

Correct behavior: the AI calls get_decisions or search_sessions and answers with provenance (date, source tool, session ID, message numbers). If it says "I don't know," MCP isn't connected — run srelay doctor.

Context safety (the AI never "eats too much")

  • get_session_detail defaults to 20 messages × 1,000 chars ≈ 20KB, hard-capped at 50KB

  • When truncated, responses carry truncated: true plus actionable hints (role="user" to see only your prompts / get_decisions() for conclusions / paginate)

  • More requires explicit parameters — safe by default, no trust in model restraint

Claude Code lifecycle hook (optional, speeds up session confirmation)

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "srelay hook session-end --id $CLAUDE_SESSION_ID" }] }]
  }
}

Custom adapters (adding a new agent)

SessionRelay's adapters are pluggable — adding a new AI tool = zero core changes:

.sessionrelay/adapters/my-agent.js   ← just drop in a JS file
// minimal implementation
module.exports = {
  id: 'my-agent',
  displayName: 'My Agent',
  discover(projectRoot, config) {
    // return the sessions belonging to this project
    return [{ source: 'my-agent', sourceSessionId: 'xxx', sourceFile: '...', sizeBytes: 1024, mtimeMs: Date.now() }];
  },
  async readNew(ds, cursor, config) {
    // incrementally read new messages (the cursor is your own watermark object)
    return { messages: [{ role: 'user', content: '...', seqNum: 1 }], badLines: 0, cursor: { offset: 100 } };
  },
};

Full interface and more capabilities (watchRoots / healthCheck / detectCompaction) in the Adapter SDK docs.

Privacy design

  • Local-first: zero cloud dependencies, zero runtime network calls (telemetry = a local counter + voluntary submission)

  • Three capture modes + ignore hard boundary + redacted-by-default export + quarantined import — four lines of defense

  • Trust model: handoff contents are data, not instructions — written into the hop/1.0 protocol

Quality & verification

  • 260 tests (unit / integration / MCP stdio real-handshake contract / serve root resolution / live daemon-service install / UI security matrix / end-to-end), one npm test

  • CI green across 3 platforms × Node 22/24 (typecheck + test + build + dist smoke)

  • TypeScript strict, npm run typecheck clean

  • Real-machine acceptance at every phase (including the product recording its own birth)

Known limitations (honest list)

  • Rule-based extraction precision is ~60-70% (provenance blocks let you verify item by item; --ai enhancement is Phase 4)

  • Daemon service registration on all three platforms (Windows registry run key / macOS launchd / Linux systemd user, all login-autostart)

  • "Auto-attach important sessions to new ones" needs session identity (branch/PID), landing in Phase 4; for now use manual attach

  • Concurrent multi-agent sessions on one project scope by project+cwd

  • Historical sessions under renamed/moved directories are not auto-discovered (use a handoff package to migrate)

  • Trae is partial only: user prompts are readable, assistant replies are end-to-end encrypted (use save_note to record conclusions)

  • DSH / Cursor and other tools are on the roadmap (custom adapters work today)

Roadmap (Phase 4)

--ai summary/extraction enhancement · session identity (branch/PID) and auto-attach · suggest_related_sessions (now cheap: session vectors from semantic search already encode topic similarity) · official DSH / Cursor adapters · macOS/Linux daemon service registration · third-party adoption of the HOP protocol

Documentation

Non-Chinese readers: the README you're reading is fully bilingual, but most deep-dive docs above (user guide, import/export, privacy design) are still Chinese-only. English translations are in progress — if you'd like to help, translation PRs are very welcome. The User Guide is structured enough that machine translation reads reasonably well in the meantime.

License

MIT © 2026 EwanJasper

Available Tools

16 tools
annotate_session注释会话(标签/摘要)A

为会话添加/移除标签、设置人工摘要(进入检索索引)。这是元数据编辑,不改写对话内容

Inputs: session_id (required), project, summary, add_tags, +1 more.

export_handoff导出交接包B

生成 .hop 交接包(sha256 完整性 + 默认脱敏)或 HANDOFF.md。默认尊重当前 scope

Inputs: all, format, output, project, +1 more.

get_decisions决策列表C

本项目全部已确认技术决策(带出处,可回跳)

Inputs: topic, source, project.

get_file_history文件讨论史C

某文件路径被哪些会话讨论过(跨 agent)

Inputs: file_path (required), project.

get_linked_sessions查询会话关联B

某会话的全部关联(双向:它指向的 / 指向它的),带 kind 与方向

Inputs: session_id (required), project.

get_session_detail会话详情A

取某会话的消息(可按角色过滤、限制范围与长度)。默认安全:最多 20 条 × 1000 字 ≈ 20KB。要更多请显式传 start_msg/end_msg 或 max_chars。session_id 支持前缀

Inputs: session_id (required), role, end_msg, project, +3 more.

get_stats索引统计A

本项目记忆库统计(会话数/状态/来源/体积/当前 scope)。开始处理项目任务前可调用,了解记忆库规模与覆盖范围

Inputs: project.

get_unresolved未决问题C

会话中提出但(启发式判定)未解决的问题

Inputs: limit, project.

import_handoff导入交接包(默认隔离)A

导入 .hop 交接包:sha256 全量校验 + 归化到当前项目。经 AI 发起的导入默认走隔离模式(只入元数据与摘要,正文待 release)

Inputs: path (required), from, project, quarantine.

list_sessions列出会话B

按过滤条件列出本项目会话(scope 生效)

Inputs: tag, file, limit, since, +5 more.

release_quarantine放行隔离会话B

把隔离导入的会话正文放行入库(用户确认后使用)

Inputs: session_id_prefix (required), project.

save_note写入结论笔记B

把结论/备忘写入项目记忆(source=note,origin=manual,立即确认并提取)。笔记中的决策句式会直接进入决策库

Inputs: title (required), content (required), tags, project.

search_sessions搜索历史会话A

搜索本项目的历史会话记忆。何时用:用户问"之前/上次/为什么当时/我们讨论过吗"、接手项目需要背景、实现前确认已有决策、报错排查怀疑有历史结论。何时不调:纯新问题、当前对话刚说过的内容

Inputs: query (required), tag, file, limit, +5 more.

set_scope调整检索边界(逃生口)A

收得太紧时的放宽通道:mode:"full" 解除裁剪(隐私 ignore 永不受影响);或设置新过滤条件

Inputs: mode, filters, project.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools target a clearly distinct action+resource (export/import handoff, save_note, link_sessions, get_decisions, get_stats), and descriptions explicitly state when to use and when not to call each one. The only mild overlap is the discovery trio (search_sessions, suggest_related_sessions, list_sessions) and get_linked_sessions vs suggest_related_sessions, but the keyword-vs-algorithmic-vs-filter distinction is spelled out well enough to disambiguate.

    Naming Consistency5/5

    All 16 names follow a consistent snake_case verb_noun pattern (export_handoff, annotate_session, save_note, get_session_detail, list_sessions, set_scope). Verbs are used predictably: get_/list_ for reads, save_/annotate_/link_/set_ for writes, export_/import_ for package transfer.

    Tool Count4/5

    16 tools is at the upper end of the ideal 3-15 range but each maps to a real capability in the session-memory/handoff lifecycle rather than being redundant. A few could arguably be folded (set_scope as a config tool, get_linked_sessions into get_session_detail), so it is slightly heavy but reasonable.

    Completeness4/5

    The surface covers the core lifecycle: capture (save_note, annotate_session), retrieve (search_sessions, get_session_detail, list_sessions, get_decisions, get_file_history, get_unresolved), link/graph, and handoff transfer with quarantine release. Gaps are minor: no delete/forget operation for sessions, notes or decisions, and no explicit add_decision tool (decision capture is only implicit via save_note).

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Persistent memory for AI agents across Claude Code, Cowork, Codex, Cursor and Hermes Agent. Saves, searches and recalls sessions from a local SQLite store through 40+ MCP tools, with auto-save and auto-load hooks, project tagging and export/import. Also a Hermes Agent memory provider plugin in the official catalog. Free: keyword search, 50 sessions. Pro ($8/mo): semantic search and team memory.
      33
      169 PyPI
      12
      Business Source 1.1
    • A
      license
      A
      quality
      B
      maintenance
      Shared, local memory for AI coding tools that stays true to your code. Claude Code, Cursor, and Codex share one memory per project; memories are linked to the files they depend on and retired automatically when those files change. Includes a local dashboard, import from CLAUDE.md/AGENTS.md, and export. Runs entirely on your machine.
      10
      242 PyPI
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude Code sessions to automatically capture and retrieve architectural decisions, code changes, bug fixes, and configuration context across sessions using local SQLite storage and hybrid semantic/keyword search.
      95 PyPI
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Local memory of your coding-agent sessions. Imports Claude Code, Codex, opencode and Copilot transcripts, extracts decisions and learnings with a link back to the session turn, and lets agents search them over MCP.
      9
      1
      MIT