SessionRelay
SessionRelay’s MCP server gives AI agents read/write access to a project’s local session memory with provenance, scoped retrieval, and safety controls.
Search historical sessions with filters for query, source, topic, tag, file, date, and project.
Retrieve session details, messages, confirmed decisions, file discussion history, unresolved questions, stats, and related-session suggestions.
List sessions, query bidirectional session links, and adjust retrieval scope.
Annotate sessions with tags or human summaries, and save traceable conclusion notes that can enter the decision library.
Export/import
.hophandoff packages orHANDOFF.md; imports default to quarantine, with a separate release step for message bodies.Link sessions as
continues,related, orpinned.Safety boundaries include no AI delete power, mandatory provenance, context-size limits, and project-selection fallback.
SessionRelay 会话接力
English | 简体中文
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

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 |
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):
Mandatory provenance — every answer must cite which session, which message, which tool. Traceable sources leave no room for confident guessing.
Pull, not push — the AI queries only when needed. Clean context, no ambient memory pollution.
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).sessionrelayignorehard boundary: privacy exclusions apply to auto-capture, manualsave, and export alikeTwo-phase verdict:
active → pending_end → confirmed, auto-rollback on resume; raw session files are the single source of truth (the DB is alwaysrebuildable)Backfill:
srelay initbackfills the last 30 days by default;srelay sync --backfill allimports your full history
🔍 Chinese-optimized search
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, flaggedviaSemantic, 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 whenRule of thumb: aging & disk space →
archive; make one conversation disappear forever →forgetDual anti-resurrection barriers: a precise
.sessionrelayignorerule (survives rebuild) + a tombstone table — the raw file stays on disk but is never re-ingestedPrefix 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 |
| "Did we ever discuss X?" (Chinese/English full-text + metadata filters) |
| "What exactly did we say?" (full messages, ranged, role-filtered) |
| "What topics has this project covered?" |
| "Why X instead of Y?" (all confirmed decisions, with provenance) |
| "Why is this file written this way?" (cross-session file discussion history) |
| "What else relates to this discussion?" (algorithmically discovered, explainable reasons) |
| "What's still undecided?" (open questions) |
| "How big is the memory?" (sessions/sources/size) |
| Retrieval-boundary escape hatch |
Tool | Capability | Safety boundary |
| tag sessions / write human summaries | metadata only, never rewrites conversations |
| AI records conclusions as notes (decision phrasing enters the decision library) |
|
| produce a .hop handoff package | read-only export |
| import a package (sha256 verified + normalized) | quarantine by default (bodies pending release) |
| release quarantined message bodies | explicit call required |
| relate sessions (continues/related/pinned) | links are queryable and revocable |
| 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.1only · 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.jsonproject contract (shared by CLI and MCP), intersection semantics — can only narrowTier 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_projectkept 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 linkInitialize 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-checkTeam 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 tooMCP integration
Claude Code (one command)
claude mcp add sessionrelay --scope user -- srelay serveRun /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
projectonce 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_detaildefaults to 20 messages × 1,000 chars ≈ 20KB, hard-capped at 50KBWhen truncated, responses carry
truncated: trueplus 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.0protocol
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 testCI green across 3 platforms × Node 22/24 (typecheck + test + build + dist smoke)
TypeScript strict,
npm run typecheckcleanReal-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;
--aienhancement 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
attachConcurrent 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_noteto 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
User Guide (Chinese) — the complete manual from install to team handoff
Import & Export Guide (Chinese) — five scenarios with complete commands
Adapter SDK — how to write a custom adapter (7 lines of code per new AI tool)
HOP handoff protocol spec, hop/1.0 — open format, MIT
Privacy & data lifecycle (Chinese) — the three-layer privacy model
Design decision logs (Chinese, contributor-facing): see CONTRIBUTING.md
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 toolsannotate_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.
link_sessions建立会话关联B
把两个会话建立关联(continues=延续 / related=相关 / pinned=挂载),供 get_linked_sessions 与跨会话追溯
Inputs: linked_ids (required), session_id (required), kind, project.
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
Scored across 16 tools
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.
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.
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.
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
Related MCP Connectors
Private memory for AI agents: save and recall facts across Claude Code, Codex, Cursor and ChatGPT.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
Shared memory for AI tools: save once, recall word for word from Claude, ChatGPT, Codex or Gemini.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Related MCP Servers
AlicenseAqualityBmaintenancePersistent 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.33169 PyPI12Business Source 1.1- AlicenseAqualityBmaintenanceShared, 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.10242 PyPI4MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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 PyPI1MIT
- AlicenseAqualityBmaintenanceLocal 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.91MIT