Passbaton

passbaton

Session continuity for AI coding agents. Your agent picks up where it left off — never re-explain your project again. Persistent memory for Claude Code, OpenAI Codex CLI & Google Gemini CLI, sharing one local db: auto context injection, compaction handover, semantic search, and error→solution recall. Zero config, zero API cost, 100% local.

⚡ One install → context auto-loads every session · 🧩 survives compaction (0 re-explaining) · 🔒 100% local, $0 API

Renamed (v2.0.0): this project was previously claude-session-continuity-mcp. The old name suggested it was Claude-only — it never was. Claude Code, Codex CLI, and Gemini CLI are all first-class and share one local memory. Existing installs keep working: the old claude-hook-* commands still ship as aliases. See Migrating from v1.

The Problem

Every new session — whether you're in Claude Code, Codex CLI, or Gemini CLI:

"This is a Next.js 15 project with App Router..."
"We decided to use Server Actions because..."
"Last time we were working on the auth system..."
"The build command is pnpm build..."

5 minutes of context-setting. Every. Single. Time.

The Solution

Fully automatic. Lifecycle hooks handle everything without manual calls — on Claude Code, OpenAI Codex CLI, and Google Gemini CLI, sharing one local memory so context carries across all three:

# Session start → Auto-loads relevant context + recent session history
# When asking → Auto-injects relevant memories/solutions
# During conversation → Tracks active files + auto-injects error solutions
# On compact → Structured handover context for continuity
# On exit → Extracts commits, decisions, error-fix pairs from transcript

← Auto-output on session start:
# my-app - Session Resumed

📍 **State**: Implementing signup form

## Recent Sessions
### 2026-02-28
**Work**: Completed OAuth integration with Google provider
**Commits**: feat: add OAuth callback handler; fix: redirect URI config
**Decisions**: Use Server Actions instead of API routes

### 2026-02-27
**Work**: Set up authentication foundation
**Next**: Implement signup form validation

## Directives
- 🔴 Always use Zod for form validation
- 📎 Prefer Server Components by default

## Key Memories
- 🎯 Decided on App Router, using Server Actions
- ⚠️ OAuth redirect_uri mismatch → check env file

Zero manual work. Context follows you.

---

Why this over other memory tools?

Most Claude memory tools rely on explicit tool calls ("remember this"), a cloud API, or a background AI worker. This one is deliberately different:

If you want zero-config, offline, no-cost memory that just happens while you work — this is it.

Auto-injection vs. explicit search

There's also a great class of local search tools (e.g. ctx) that index your agent history so you can query it (search "failed migration"). That's complementary, not the same job:

Use search when you want to look something up. Use this when you want your context to follow you without asking.

---

Resume card — the repo is the source of truth (v2.6.0+)

Long-running projects usually keep their real hand-off in the repo — a HANDOFF.md whose newest entry is on top, a plan file with a "current task" block, a stop file left by an unattended loop. A DB summary of the last session cannot replace those, and it goes stale the moment someone else edits them. Since 2.6.0 a project can declare those files, and SessionStart shows verbatim excerpts of them first, each with its line range and a content hash:

// <project>/.claude/passbaton.config.json
{
  "continuity": {
    "sources": [
      { "path": "docs/HANDOFF.md",    "lines": 30,           "label": "HANDOFF (newest entry)" },
      { "path": ".ralph/fix_plan.md", "block": "지금 할 일", "label": "current task" },
      { "path": ".ralph/DEMO_STOP",   "lines": 3,            "label": "loop stop reason" }
    ]
  }
}

• lines — the first N lines (default 40, max 200)
• block — the first list item or heading containing that text, up to the next item/heading of the same or higher level (max 120 lines)
• Files are re-read on every start (never cached). A source that cannot be read is shown as NOT READ, never silently dropped
• When a card is present the DB state is relabelled Last recorded state (may be stale)
• The same card is available as the read-only MCP tool resume_card, so another agent can read it too
• Boundaries — the real path (after links/junctions) must stay inside the project; regular text files only (.md .markdown .txt .rst or no extension, checked on the link target too); at most the first 2 MB is read; at most 8 sources. Names that usually hold secrets are never read even if declared: any path segment matching .env*, .git, .ssh, .aws, .gnupg, .npmrc, .netrc, id_*, credentials*, secret(s)*, *.pem, *.key, *.pfx … (so docs/credentials-guide.md is refused; docs/secret-sauce.md is not — rename rather than weaken the rule)
• PASSBATON_CARD_CHARS (default 3200, 400–20000) caps the whole card, headings included
• (v2.7.2+) Space a missing or short source leaves unused is handed once, evenly, to the sources that were cut by their share (never to a source that hit its own lines/block cap, never reviving an omitted one). What was already shown stays as the start of each excerpt; if the files change between reads or the rendered card would exceed the cap, the card stays as it was. Ashfall: 2,390 → 3,064 of 3,200 chars, +3 ms

Routing from a workspace root (v2.7.0+)

Project detection follows the cwd, so a conversation opened at a monorepo root never got a sub-project's card. Declare which commands select which project in the root .claude/passbaton.config.json:

{ "routing": { "commands": { "/ashfall": "apps/kenshi-fantasy", "/astra": "apps/kenshi-fantasy", "/home": "." } } }

• Only a registered command at the very start of what you type selects a project (/ashfall …). The same text inside a sentence, a quote, code, a path mention or a harness notification does not. (Claude Code passes the typed text to the hook as-is — observed with a no-output probe hook under claude -p, tests/fixtures/hook-input-claude-code-2026-10-23.json — so the expanded <command-name> form seen in transcripts is not accepted.) Define every routing and release command as a real command (.claude/commands/<name>.md): whether an undefined /name reaches the hook in the interactive UI was not observed
• Routing runs only when the hook's cwd is the workspace root (same real path — a sub-app with the root's name does not count; no cwd in the input means no routing)
• A release command (mapped to ".") is required. Without one, routing is off as a whole
• The choice is per session and survives compaction/resume of that session; a new session starts unrouted. Another routed command switches; the release command releases. If the chosen mapping disappears from the config, the next turn says once that the route was cleared
• The card is sent when the choice changes, when the card (or its header — e.g. a renamed release command) changes, and after compaction — not every turn. If the post-compaction card did not fit the budget, it is sent on the next turn
• The card says what selected it and that the conversation is still recorded under the root project — passbaton does not re-file root sessions under the sub-project
• Paths must be real directories inside the workspace (checked after links/junctions); invalid entries are ignored
• All of this goes out in the hook's single output (Codex/Gemini receive one JSON object)
• Cost (Ashfall data, 15 runs, median, Windows): 94 ms (2.6.1) → 100 ms with nothing selected, 112 ms with a selection held

Decision index through the card (v2.7.0+)

When work is steered by written decisions (reviews, replies from another agent), keep a short index in the repo and declare its active section as a source. The index points to the original text; passbaton does not judge whether a decision is valid.

## Active
| ID | Decision | Decided by | Source | Resume condition | Unmet condition / evidence | State (A / H) | Replaces / invalidated |
|---|---|---|---|---|---|---|---|
| PB-07 | keep card cap 3200 | delegated reviewer | reply-132.md:70-81 (correction) | a measured case where truncation blocked a resume | none yet | A closed / H none | replaces reply-132.md:60-69 |

## Excluded — invalidated or replaced (not in force)
| Original location | Why excluded | Replaced by |
|---|---|---|
| reply-132.md:60-69 (first answer) | based on a miscounted figure | reply-132.md:70-81 |

{ "continuity": { "sources": [ { "path": "docs/INDEX.md", "block": "Active", "label": "decision index" } ] } }

• Table rows are never cut in the middle: a row that does not fit the card budget is left out and the source is marked truncated, so a half row (missing its resume condition) cannot read as a complete decision
• Use block on the active heading so excluded answers never reach the card as "active"; keep the excluded heading free of the active heading's text (otherwise the card reports an ambiguous match)
• Record who edits the index and which commit it was checked against at the top; an entry whose source is missing or conflicting should say so (unverified — do not act on it) rather than be dropped

Read-only MCP mode (v2.6.0+)

PASSBATON_READONLY=1 exposes only tools that do not change state (resume_card, session_history, search_sessions, memory_search, memory_get, …) and opens an existing DB with SQLite's own read-only flag, so a missed write path fails loudly instead of writing. Access counters and the embedding cache are not updated, the embedding model is not loaded (keyword search only), and prompts are not listed. If the DB file does not exist the server answers from an empty in-memory DB, creates nothing on disk, and says so in every result. Use it to share one memory/session ledger with a second agent (e.g. Codex) without letting it edit:

codex mcp add passbaton-ro --env WORKSPACE_ROOT=/path/to/workspace --env PASSBATON_READONLY=1 -- npx -y passbaton

What 2.6.0 stopped injecting

Measured on a real 2-month workspace DB (Ashfall, 2026-10-22):

2.6.1 — compaction recovery and hooks-only installs

Codex CLI support (v1.16.0+)

Beyond Claude Code, this also supports OpenAI Codex CLI. If ~/.codex exists, the installer registers the same hooks in ~/.codex/hooks.json (SessionStart, UserPromptSubmit, PreCompact, Stop), and the hooks auto-detect the host and emit the right output format (Codex's hookSpecificOutput.additionalContext).

The same local sessions.db is shared, so context carries across both agents: what you did in Codex is available in Claude Code and vice versa.

Scope: session save + context injection work on both. Codex file-change tracking (PostToolUse) isn't wired yet — session save already covers most of it via transcript parsing. Codex's transcript_path is treated as an unstable interface (it can be null at startup), so host detection uses an installer-injected --codex marker rather than relying on the path.

---

Gemini CLI support (v1.17.0+)

Also supports Google Gemini CLI. If ~/.gemini exists, the installer registers the hooks in ~/.gemini/settings.json (SessionStart, BeforeAgent, PreCompress, SessionEnd — Gemini's event names), preserving your other settings. Same shared local sessions.db, so context carries across all three agents.

Gemini's transcript format was verified against real ~/.gemini/tmp/.../chats/*.jsonl files — it uses two shapes (a flat {type, content} line and an older {"$set":{"messages":[…]}} diff line); the parser handles both. Like Codex, transcript_path can be null at startup, so host detection uses a --gemini marker.

Honest scope note: session save (SessionEnd) and context output are verified working. Gemini's SessionStart context injection is documented as advisory-only upstream (gemini-cli#15413) — if your Gemini build doesn't render the injected context on startup, that's an upstream limit, not this tool. Session continuity still works via the saved history.

---

Migrating from v1

If you installed this as claude-session-continuity-mcp (v1.x), nothing breaks — the v1 claude-hook-* commands still ship as aliases in v2.

To move to the new name:

npm install -g passbaton          # installs the new package
npm uninstall -g claude-session-continuity-mcp   # optional: drop the old one

To rewrite your hook entries, run passbaton-hooks install once: it replaces the old claude-hook-* lines with the current form and matches on both names, so you won't end up with duplicates. (The automatic install during npm install -g adds missing hooks but leaves existing passbaton lines as they are.) Your existing sessions.db is untouched: all past sessions, memories, and solutions carry over.

Nothing else changes — same hooks, same database, same behavior.

---

Quick Start

Requires Node.js 22+. The native better-sqlite3 dependency only ships prebuilt binaries for Node 22, 24, and 26 (the currently supported lines — Node 18 and 20 are both end-of-life). On older Node it falls back to compiling from source, which fails without build tools. Node 22 and up install cleanly with no compiler needed.

Recommended: Global Installation

npm install -g passbaton

That's it! The postinstall script automatically:

1. Registers MCP server in ~/.claude.json
2. Installs Claude Hooks in ~/.claude/settings.json

npm install-script policy (npm 11.16+ / v12). passbaton needs install-time scripts: its own postinstall (registers hooks and the MCP server) and better-sqlite3's native build. npm 11 runs them with an install-scripts … not yet covered by allowScripts warning; with strict-allow-scripts=true the install fails; npm v12 is announced to skip unapproved install scripts by default — passbaton would then install without hooks and without a working SQLite binding. Approve them explicitly:

npm install -g passbaton --allow-scripts=passbaton,better-sqlite3,sharp,protobufjs

If an install ran with scripts skipped (passbaton-hooks status reports better-sqlite3 does not load), run that same command again. Re-running passbaton-hooks install alone does not rebuild the SQLite binding.

Then check it and start Claude Code:

passbaton-hooks status

Installed Node.js just now? If Claude Code was already open before Node.js was installed, fully quit the app that launched it (VS Code, your terminal app) and start it again, then start Claude Code. Opening a new tab or window in the same app can keep the old PATH. No reboot is needed for this.

npm hides postinstall output by default, so if setup could not finish you may not see a message — passbaton-hooks status shows what is registered, and passbaton-hooks install (re)writes it.

passbaton-hooks is a command installed by the passbaton package — there is no npm package with that name, so don't run it through npx passbaton-hooks. Without a global install, use npx passbaton install / npx passbaton status (same installer).

Troubleshooting: npm: command not found / node: not found in a hook

UserPromptSubmit hook error
Failed with non-blocking status code: /usr/bin/bash: line 1: npm: command not found

The app that launched Claude Code has a PATH without Node.js (typically because it was opened before Node.js was installed). Hooks written by older versions call npm exec and need npm on that PATH. Run passbaton-hooks install from a terminal that has Node.js — it rewrites passbaton's hooks and MCP entry with absolute paths — then restart as above. passbaton-hooks status tells you which entries still depend on PATH. Its check uses the PATH of the terminal you run it in, not that of an already running Claude Code session.

Why Global (-g)?

This tool is designed to track all your Claude Code projects in a single unified database. Global installation is strongly recommended because:

Add the database to your project's .gitignore. Since 2.4.0 passbaton creates <project>/.claude/sessions.db on the first session in any project it recognises as a workspace root, so a project that had no database before will get one:

.claude/sessions.db
.claude/sessions.db-shm
.claude/sessions.db-wal
.claude/*.log

Do not ignore all of .claude/ — settings.json there is meant to be committed.

Important: Even with global install, you can still disable the hook for specific projects (see below). Global ≠ forced on every project.

Disabling Hooks for Specific Projects

Global install does not mean "always on everywhere". You have three layers of control:

To disable hooks in a specific project, create the override file with empty hook arrays:

// <project>/.claude/settings.json  (or settings.local.json for personal-only)
{
  "hooks": {
    "SessionStart": [],
    "UserPromptSubmit": [],
    "PostToolUse": [],
    "PreCompact": [],
    "Stop": []
  }
}

Empty arrays override the global setting → that project's sessions are no longer tracked.

Updating to a New Version

npm install -g passbaton@latest

That's the only step — all projects pick up the new binary on next Claude Code restart. No need to reinstall in each project.

Alternative: Local Install (Not Recommended)

If you really want per-project install (e.g., locked version for one project):

cd <project> && npm install passbaton

Drawback: you must install separately in every project, npm exec may not find the local copy reliably from hook context (cwd-dependent), and you pay the npm exec startup cost (~1.4 s) on every hook fire instead of ~135 ms. Stick with -g unless you have a specific reason.

What Gets Installed

MCP Server (in ~/.claude.json):

{
  "mcpServers": {
    "project-manager": {
      "command": "npx",
      "args": ["passbaton"]
    }
  }
}

Claude Hooks (in ~/.claude/settings.json):

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "passbaton-hook-session-start" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "passbaton-hook-user-prompt" }] }],
    "PostToolUse": [{ "matcher": "Edit", "hooks": [{ "type": "command", "command": "passbaton-hook-post-tool" }] }, { "matcher": "Write", "hooks": [{ "type": "command", "command": "passbaton-hook-post-tool" }] }],
    "PreCompact": [{ "hooks": [{ "type": "command", "command": "passbaton-hook-pre-compact" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "passbaton-hook-session-end" }] }]
  }
}

Note (v2.2.1+): Full lifecycle coverage with 5 hooks. The installer probes whether passbaton-hook-* resolves on PATH and writes the bare name if so (≈10× faster per fire); otherwise it writes npm exec -- …, which also finds a local node_modules/.bin.

Installed Hooks (v1.5.0+)

Manual Hook Management

# Check hook status
passbaton-hooks status

# Reinstall hooks
passbaton-hooks install

# Remove hooks
passbaton-hooks uninstall

3. Restart Claude Code

After installation, restart Claude Code to activate the hooks.

---

Features

---

Feature toggles — everything is opt-in

(v2.1.0+) Six behaviours are individually toggleable; the rest are shown for transparency but are always on (a hook's mere existence is controlled by your settings.json, not by config) or not yet wired. Config lives in a plain, hand-editable JSON file (~/.claude/passbaton.config.json) — separate from your data, so it survives a db reset. No file = today's defaults (nothing changes for existing users).

passbaton config                            # grouped table; ●/○ = toggleable, · = always on
passbaton config set solutionCapture off    # flip a toggleable feature
passbaton config set strictSolutionGate on  # opt into the strict error→fix filter
passbaton config preset minimal             # minimal | default | everything
passbaton config reset                       # back to defaults
passbaton config path                        # print the active config file path

Trying to set an always-on / not-yet-wired feature is rejected with a clear message. Each toggleable feature also has an env override for one-off/CI use: PASSBATON_<FEATURE>=0 (e.g. PASSBATON_SOLUTIONCAPTURE=0) wins over the config file.

On-by-default rule: a feature ships on only if it's silent, safe, and universally useful. Anything that speaks unprompted, guesses, or writes speculative rows ships off.

Legend: ●/○ = toggleable (on/off) · · = always on, not a config toggle · ⋯ = not yet wired.

Core (on by default)

sessionStart/sessionEnd are "always on" because a hook either runs or it doesn't — that's controlled by the hook registration in ~/.claude/settings.json, not by config. To disable them, remove the hook there.

Cross-agent (on by default)

Experimental (off by default)

The only genuinely user-flippable flags today are compactionHandover, hotPathPrewarm, verificationLedger, solutionCapture (on) and strictSolutionGate, hookTrace (opt-in).

Turning on hookTrace on Windows: edit ~/.claude/passbaton.config.json (or run passbaton config set hookTrace on). The PASSBATON_HOOKTRACE=1 env override works too, but hooks are launched from settings.json through cmd.exe, where a VAR=1 command prefix is a syntax error — so the config file is the practical path.

---

Claude Hooks - Auto Context System

How It Works

SessionStart Hook (npx passbaton-hook-session-start):

• Auto-detects project: monorepo (apps/project-name/) or single project (package.json root folder name)
• Loads context from .claude/sessions.db
• Injects: Current state, 3 recent sessions with commits/decisions, directives, pending tasks, filtered key memories
• Auto-cleans stale noise memories (3d+ auto-tracked, 14d+ auto-compact)

UserPromptSubmit Hook (npx passbaton-hook-user-prompt):

• Runs on every prompt submission
• (v1.11.0) No longer calls loadContext() — saves 24-60K tokens/session
• Injects relevant context (filtered: decisions, learnings, errors only)

PostToolUse Hook (npx passbaton-hook-post-tool):

• Tracks hot file paths and updates active_context.recent_files
• (v1.12.0) Auto-detects Bash errors → searches solutions DB → injects past solutions into context
• No longer creates observation memories (v1.10.0 — eliminates [File Change] noise)

PreCompact Hook (npx passbaton-hook-pre-compact):

• Builds structured handover context: work summary, active file, pending action, key facts, recent errors
• No longer stores auto-compact memories (v1.10.0)

Stop Hook (npx passbaton-hook-session-end):

• Extracts commit messages from JSONL transcript (git commit -m patterns)
• Extracts error-fix pairs (error → resolution within 3 messages)
• (v1.12.0) Auto-records error→fix pairs to solutions table for future reuse
• Extracts decisions ("because", "instead of", "chose" patterns)
• (v1.11.0) Single-pass transcript parsing (4 JSONL reads → 1)
• Stores structured metadata in sessions.issues column as JSON

Example Output (Session Start)

# my-app - Session Resumed

📍 **State**: Implementing signup form
🚧 **Blocker**: OAuth callback URL issue

## Recent Sessions
### 2026-02-28
**Work**: Completed OAuth integration
**Commits**: feat: add OAuth handler; fix: redirect config
**Decisions**: Use Server Actions over API routes
**Next**: Implement form validation

## Directives
- 🔴 Always use Zod for validation

## Pending Tasks
- 🔄 [P8] Implement form validation
- ⏳ [P5] Add error handling

## Key Memories
- 🎯 Decided on App Router, using Server Actions
- ⚠️ OAuth redirect_uri mismatch → check env file

Hook Management

# Check status
passbaton-hooks status

# Reinstall
passbaton-hooks install

# Remove
passbaton-hooks uninstall

# Temporarily disable
export MCP_HOOKS_DISABLED=true

Past Reference Detection (v1.8.0)

When you ask about past work, the UserPromptSubmit hook automatically searches the database:

You: "저번에 인앱결제 어떻게 했어?"
→ Hook detects "저번에" + extracts keyword "인앱결제"
→ Searches sessions, memories (FTS5), and solutions
→ Injects matching results into context automatically

Supported patterns (Korean & English):

Output example:

## Related Past Work (auto-detected from your question)

### Sessions
- [2/14] 카카오 로그인 앱키 수정, 인앱결제 IAP 플로우 수정

### Memories
- 🎯 [decision] 테스트: 인앱결제 상품 등록 완료

### Solutions
- **IAP_BILLING_ERROR**: StoreKit 2 migration으로 해결

Why npm exec? (v1.4.3+)

Previous versions used absolute paths or npx:

// v1.3.x - absolute paths (broke on multi-project)
"command": "node \"/path/to/project-a/node_modules/.../session-start.js\""

// v1.4.0-1.4.2 - npx (required global install or hit npm registry)
"command": "npx passbaton-hook-session-start"

Now we use npm exec --:

"command": "passbaton-hook-session-start"

npm exec -- finds local node_modules/.bin first, then falls back to global. Works with both local and global installation without hitting npm registry.

---

Tools (v5 API) - 25 Focused Tools

1. Session Lifecycle (4) ⭐

// Start of session - auto-loads context
session_start({ project: "my-app", compact: true })

// End of session - auto-saves context
session_end({
  project: "my-app",
  summary: "Completed auth flow",
  modifiedFiles: ["src/auth.ts", "src/login/page.tsx"]
})

// View session history
session_history({ project: "my-app", limit: 5 })

// Semantic search past sessions
search_sessions({ query: "auth work", project: "my-app" })

2. Project Management (4)

// Get project status with task stats
project_status({ project: "my-app" })

// Initialize new project
project_init({ project: "my-app" })

// Analyze project tech stack
project_analyze({ project: "my-app" })

// List all projects
list_projects()

3. Task Management (4)

// Add a task
task_add({ project: "my-app", title: "Implement signup", priority: 8 })

// Update task status
task_update({ taskId: 1, status: "done" })

// List tasks
task_list({ project: "my-app", status: "pending" })

// Suggest tasks from TODO comments
task_suggest({ project: "my-app" })

4. Solution Archive (3)

// Record an error solution
solution_record({
  errorSignature: "TypeError: Cannot read property 'id'",
  solution: "Use optional chaining: user?.id"
})

// Find similar solutions (keyword or semantic)
solution_find({ query: "TypeError property", semantic: true })

// AI-powered solution suggestion
solution_suggest({ errorMessage: "Cannot read property 'email'" })

5. Verification (3)

// Run build
verify_build({ project: "my-app" })

// Run tests
verify_test({ project: "my-app" })

// Run all (build + test + lint)
verify_all({ project: "my-app" })

6. Memory System (5)

// Store a classified memory
memory_store({
  content: "State management with Riverpod makes testing easier",
  type: "learning",  // observation, decision, learning, error, pattern
  project: "my-app",
  tags: ["flutter", "state-management"],
  importance: 8,
  relatedTo: 23  // Connect to existing memory
})

// Search memories — returns index (id, type, tags, score) for token efficiency
memory_search({
  query: "state management test",
  type: "learning",
  semantic: true,  // Use embedding similarity
  limit: 10
})

// Get full memory content by ID (v1.11.0)
memory_get({ memoryId: 23 })

// Find related memories (graph + semantic)
memory_related({
  memoryId: 23,
  includeGraph: true,
  includeSemantic: true
})

// Get memory statistics
memory_stats({ project: "my-app" })

7. Knowledge Graph (2)

// Connect two memories with a typed relation
graph_connect({
  sourceId: 23,
  targetId: 25,
  relation: "solves",  // related_to, causes, solves, depends_on, contradicts, extends, example_of
  strength: 0.9
})

// Explore knowledge graph
graph_explore({
  memoryId: 23,
  depth: 2,
  relation: "all",  // or specific relation type
  direction: "both"  // outgoing, incoming, both
})

Memory Types

Relation Types

---

Data Storage

SQLite database at ~/.claude/sessions.db:

---

Environment Variables

---

Development

# Clone
git clone https://github.com/leesgit/passbaton.git
cd passbaton

# Install
npm install

# Build
npm run build

# Test
npm test

# Test with coverage
npm run test:coverage

---

Performance

---

Roadmap

• [x] v2 API (15 focused tools)
• [x] v4 API (24 tools - memory + graph)
• [x] v5 Claude Hooks (auto-capture)
• [x] Knowledge Graph with typed relations
• [x] Memory classification (6 types)
• [x] Semantic search (embeddings)
• [x] Multilingual pattern detection (KO/EN/JA)
• [x] Git commit integration
• [x] 111 tests (6 test suites)
• [x] GitHub Actions CI/CD
• [x] Multilingual semantic search (v1.6.0 - multilingual-e5-small)
• [x] Cross-language search EN↔KR (v1.6.0)
• [x] Solution semantic search (v1.6.0)
• [x] Fix hooks settings file path (v1.6.1 - settings.json, not settings.local.json)
• [x] Auto-migrate legacy hooks (v1.6.1)
• [x] Fix PostToolUse matcher format to string (v1.6.3)
• [x] Fix README documentation for new hook format (v1.6.4)
• [x] Empty session skip and techStack save improvements (v1.7.1)
• [x] Past reference auto-detection in UserPromptSubmit hook (v1.8.0)
• [x] User directive extraction ("always/never" rules) (v1.8.0)
• [x] Memory quality overhaul — no more [File Change] noise (v1.10.0)
• [x] Structured handover context in PreCompact (v1.10.0)
• [x] Smart session-end: commit/decision/error-fix extraction from transcript (v1.10.0)
• [x] Auto noise cleanup (3d+ observations, 14d+ auto-compact) (v1.10.0)
• [x] 3 recent sessions display with structured metadata (v1.10.0)
• [x] Token efficiency — remove loadContext from UserPromptSubmit, saves 24-60K tokens/session (v1.11.0)
• [x] Single-pass transcript parsing, 4 JSONL reads → 1 (v1.11.0)
• [x] Temporal decay for memory scoring with type-specific half-lives (v1.11.0)
• [x] Progressive disclosure — memory_search returns index, memory_get for full content (v1.11.0)
• [x] Memory consolidation via Jaccard similarity (v1.11.0)
• [x] Auto error→solution pipeline — PostToolUse detects Bash errors, injects past solutions (v1.12.0)
• [x] SessionEnd auto-records error-fix pairs to solutions table (v1.12.0)
• [x] Cross-project solution search with current project prioritization (v1.12.0)
• [ ] sqlite-vec native vector search (v2 - when data > 1000 records)
• [ ] Web dashboard
• [ ] Cloud sync option

---

Contributing

PRs welcome! Please:

1. Fork the repo
2. Create a feature branch
3. Add tests for new features
4. Ensure npm test passes
5. Submit PR

---

License

MIT © Byeongchang Lee

---

Acknowledgments

• Model Context Protocol by Anthropic
• Xenova Transformers for embeddings

---

If this saves you from re-explaining your project, consider giving it a ⭐ — it genuinely helps others find it.