claude-mem/PATHFINDER-2026-04-22/_reference.md

PATHFINDER-2026-04-22 Reference

Verified API signatures, current-code anchors, and canonical snippets. Every plan in this corpus cites this document for exact file:line anchors and verified APIs.

Verification date: 2026-04-22. Anchors verified by direct file read. External APIs verified against documentation and usage patterns.

---

Correction to prior conversation assumptions

1. Bun.spawn does NOT support detached option. detached: true is a Node child_process.spawn option, not a Bun one.
2. claude-mem uses Node's child_process, not Bun.spawn. Every subprocess spawn in the codebase uses node:child_process.spawn/spawnSync (verified by cross-check with Deno migration audit). So detached: true + setsid IS available to us — through the Node API, not through Bun.
3. respawn npm package is NOT currently a dependency. Adding it is a new-dep decision.
4. fs.watch(dir, { recursive: true }) on Linux requires Node 20+. package.json currently pins >=18.0.0. Preflight: bump to >=20.0.0.

---

Part 1: Current-code anchors

Data layer

src/services/sqlite/PendingMessageStore.ts:99-145 — claimNextMessage

Transaction-wrapped claim. Resets stale rows (status='processing' older than STALE_PROCESSING_THRESHOLD_MS=60_000) INSIDE the claim transaction. The self-heal block (lines 107-115) is the target of Plan 01-data-integrity Phase 4.

src/services/sqlite/PendingMessageStore.ts:486-495 — clearFailedOlderThan

DELETE FROM pending_messages WHERE status='failed' AND COALESCE(failed_at_epoch,…) < ?. Currently called from 2-minute interval at worker-service.ts:567. Moves to boot-once OR gets deleted entirely (Plan 02 principles: if nothing needs purge, don't purge).

src/services/sqlite/PendingMessageStore.ts:349-374 — markFailed

Retry ladder: reads retry_count, bumps to pending if < maxRetries, marks failed otherwise. Principle decision for Plan 01: retry exists for a reason (transient SDK failures); KEEP the ladder but verify maxRetries is reasonable (currently 3).

src/services/sqlite/Database.ts:37-130 — repairMalformedSchema

Python subprocess fallback when SQLite reports malformed database schema. Writes script to tempfile, execFileSync. Closes connection first to avoid lock conflicts. Target for Plan 07-dead-code deletion — this is cross-machine WAL corruption that should be root-caused, not repaired.

src/services/sqlite/migrations/runner.ts:621-628 — Migration 19 (DEPRECATED)

No-op after migration 17 made renames idempotent. Records itself as applied, does nothing. Dead code. Plan 07-dead-code deletes with next schema.sql regeneration.

src/services/sqlite/migrations/runner.ts:658-837 — Migration 21 (FK cascade fix)

Recreates observations + session_summaries tables to add ON UPDATE CASCADE. Exists because an earlier design allowed memory_session_id mutations. Plan 01-data-integrity §Invariants: memory_session_id must be immutable post-creation; if this holds, migration 21 is a one-time historical fix, safe to absorb into schema.sql.

src/services/sqlite/observations/store.ts:13-46 — DEDUP_WINDOW_MS + findDuplicateObservation

30-second content-hash dedup window. Plan 01-data-integrity Phase 2 replaces with DB UNIQUE(memory_session_id, content_hash) constraint + ON CONFLICT DO NOTHING.

src/services/sqlite/SessionStore.ts:52-70 — Duplicated migration logic

Re-calls every ensure* / add* migration method already owned by MigrationRunner. Plan 07-dead-code: SessionStore delegates to a single new MigrationRunner(db).runAllMigrations().

src/services/sync/ChromaSync.ts:290-318 — Delete-then-add reconciliation

Chroma MCP has no upsert. On already exist error, the code deletes the IDs then re-adds. Plan 01-data-integrity §Chroma: document the brittle error-text match; consider guarding behind a flag until Chroma exposes upsert natively.

Worker / lifecycle

src/services/worker/ProcessRegistry.ts:244-309 — killIdleDaemonChildren

Walks ps -eo output, filters by ppid == daemonPid, kills any child idle > 1 minute. Used by 30s-interval startOrphanReaper. Plan 02-process-lifecycle DELETES (function body) — replaced by process-group teardown.

src/services/worker/ProcessRegistry.ts:315-344 — killSystemOrphans

ppid=1 sweep matching claude.*haiku|claude.*output-format. Plan 02-process-lifecycle DELETES — orphans are prevented by process-group spawning, not swept.

src/services/worker/ProcessRegistry.ts:349-382 — reapOrphanedProcesses

Three-layer cleanup (registry-tracked, ppid=1, idle daemon children). DELETES wholesale.

src/services/worker/ProcessRegistry.ts:452-465 — spawn site for Claude SDK children

Currently uses spawn(command, args, { stdio: 'pipe', … }) with NO detached and NO process group. Plan 02-process-lifecycle Phase 2: change to spawn(cmd, args, { detached: true, stdio: ['ignore','pipe','pipe'] }) and track via pgid.

src/services/worker/worker-service.ts:537, 547, 567, 581, 1094-1120

• :537 — startOrphanReaper call
• :547 — staleSessionReaperInterval = setInterval(…)
• :567 — clearFailedOlderThan interval
• :581 — explicit PRAGMA wal_checkpoint(PASSIVE) interval
• :1094-1120 — shutdown sequence (clears intervals, calls performGracefulShutdown)

Plan 02-process-lifecycle deletes all interval setup and collapses shutdown.

src/supervisor/process-registry.ts:85-173 — captureProcessStartToken

Reads /proc/<pid>/stat field 22 on Linux, ps -o lstart= on macOS, returns null on Windows. Used for PID-reuse detection (commit 99060bac). Plan 02-process-lifecycle KEEPS — legitimate primary-path correctness.

src/supervisor/shutdown.ts:22-99, 116, 163 — runShutdownCascade

5-phase: SIGTERM all → wait 5s → SIGKILL survivors → wait 1s → unregister + rm PID file. Uses process.kill(pid, signal) — SINGLE-PID, not process group. Plan 02-process-lifecycle Phase 3: change to process.kill(-pgid, signal) where children have their own process groups.

src/services/worker/SessionManager.ts:397, 477, 516-568, 573-579, 631-670

• :397 — deleteSession(sessionDbId) — awaits generator + subprocess exit
• :477-506 — evictIdlestSession (pool-eviction, candidate for DELETE per Tier 1 #11)
• :516-568 — reapStaleSessions (DELETE per Plan 02)
• :573-579 — shutdownAll
• :631-670 — getMessageIterator (idle-timer callback is second-system per earlier audit)

src/services/worker/SessionQueueProcessor.ts:6, 51-52, 62-63, 130, 145

Per-iterator idle setTimeout (3-min). Plan 02-process-lifecycle §Invariants: this is per-session not global-scanner. KEEP as the only runtime defense against hung SDK generators.

src/services/infrastructure/GracefulShutdown.ts:52-86 — performGracefulShutdown

6-step canonical shutdown (HTTP server close → sessions → MCP → Chroma → DB → supervisor). Plan 06-api-surface CONSOLIDATES — currently four shutdown functions (WorkerService.shutdown, performGracefulShutdown, runShutdownCascade, stopSupervisor) collapse to this one.

src/services/infrastructure/ProcessManager.ts:1013-1032, 1053-1075

Daemon spawn + liveness. :1013 uses setsid on Unix, :1028 falls back to detached: true on macOS. Liveness at :1053-1075 is plain process.kill(pid, 0). Plan 02-process-lifecycle KEEPS daemon spawn pattern; extends to SDK children.

Ingestion

src/sdk/parser.ts:33-111 — parseObservations

Parses <observation> blocks. Fallback type logic (line 54-69) is legitimate (type field is optional per schema). KEEP.

src/sdk/parser.ts:122-259 — parseSummary + coerceObservationToSummary

coerceObservationToSummary at lines 222-259 is a second-system effect (maps <observation> fields to <summary> when LLM violates contract). Plan 03-ingestion-path DELETES the coerce function. Contract violations must fail-fast to markFailed, not coerce.

src/services/worker/agents/ResponseProcessor.ts:96-200 — Circuit breaker

consecutiveSummaryFailures + MAX_CONSECUTIVE_SUMMARY_FAILURES. Plan 03-ingestion-path DELETES field, constant, guard.

src/services/transcripts/processor.ts:23, 202, 232-236, 252, 275-285, 317

• :23 — pendingTools Map (per-session toolId → toolInput)
• :202, :232-236 — dispatcher pairing tool_use with tool_result
• :252 — HTTP loopback (observationHandler.execute() → workerHttpRequest → same worker)
• :275-285 — maybeParseJson silent passthrough

Plan 03-ingestion-path Phase 1 deletes the Map; Phase 2 routes through direct function call ingestObservation(payload) (no HTTP loopback); Phase 3 changes maybeParseJson to fail-fast.

src/services/transcripts/watcher.ts:124-132, 156-159, 183-188

• :124-132 — 5-second setInterval rescan
• :156-159 — resolveWatchFiles silent empty-return on stat() failure
• :183-188 — startAtEnd offset fallback (benign, KEEP)

Plan 03-ingestion-path replaces rescan with fs.watch(dir, { recursive: true }).

src/utils/tag-stripping.ts:37-44, 63-69 — countTags, stripTagsInternal

Six separate .replace() / .match() calls for six tag types. Plan 03-ingestion-path §Tag stripping: one regex with alternation, single-pass.

src/utils/transcript-parser.ts:28-90 — DEAD CLASS

TranscriptParser class exists but has no active imports. Plan 07-dead-code DELETES.

src/shared/transcript-parser.ts:41-144 — Active function

extractLastMessage(path, role, opts) — the active parser. KEEP.

Search / read path

src/services/worker/search/SearchOrchestrator.ts:85-110 — Silent fallback

Three paths: (1) filter-only → SQLite, (2) query + Chroma → try Chroma, on usedChroma=false strip query and re-query SQLite, (3) no Chroma → empty silent. Plan 04-read-path Phase 1: DELETE the stripping branch. On Chroma failure, throw 503.

src/services/worker/search/strategies/ChromaSearchStrategy.ts:76-86

try { … } catch { return usedChroma: false } swallows real errors. Plan 04-read-path Phase 1: only return usedChroma: false when Chroma is explicitly not initialized; propagate real errors.

src/services/worker/search/strategies/HybridSearchStrategy.ts:64-185

Three near-identical methods (findByConcept, findByType, findByFile) each with its own try/catch fallback to metadata-only. Plan 04-read-path Phase 2: propagate errors, don't silently degrade to metadata-only.

src/services/worker/SearchManager.ts:230, 247-259, 488, 978-985, 1064-1071, 1150-1157, 1209-1310, 1277, 1399, 1840-1847

• Seven duplicated recency-filter call sites
• findByConcept/File/Type implementations that duplicate HybridSearchStrategy

Plan 04-read-path Phase 3: import RECENCY_WINDOW_MS from types.ts:16, delete the seven copies; delete SearchManager.findBy* methods and route through SearchOrchestrator.

src/services/worker/search/ResultFormatter.ts:264 vs src/services/worker/knowledge/CorpusRenderer.ts:90

Two different token estimates. Plan 04-read-path §Utilities: one shared estimateTokens(obs) in src/shared/.

src/services/context/formatters/ — four formatters (AgentFormatter, HumanFormatter, ResultFormatter, CorpusRenderer) share a common walk with four strategy knobs (header, grouping, row density, colors). Plan 04-read-path Phase 4: single renderObservations(obs, strategy: RenderStrategy).

Hooks / CLI

src/shared/worker-utils.ts:221-239 — ensureWorkerRunning

Single health check, returns false on failure. Caller decides whether to proceed. Plan 05-hook-surface §Primary path: KEEP the check; REPLACE "proceed gracefully" with consecutive-failure counter that exits code 2 after N failures (surface worker death instead of hiding it).

src/cli/handlers/summarize.ts:117-150 — 120s polling loop

Polls every 1s for 120s waiting for summary completion, logs timeout on failure but exits 0. Plan 05-hook-surface Phase 2: replace with blocking /api/session/end endpoint (server-side wait, single HTTP POST with server-side timeout). Delete the polling loop.

src/cli/handlers/session-init.ts:57-60, 120-129

Settings loaded per-handler. Agent init conditional on initResult.contextInjected → skips agent spawn when context already present. Plan 05-hook-surface Phase 1: settings cached once per hook process. Phase 3: agent init is idempotent (always call).

src/cli/handlers/observation.ts:17, 53-54, 58-61

HTTP loopback + cwd validation after adapter normalization + project exclusion. Plan 05-hook-surface §DRY: executeWithWorkerFallback() helper; cwd validation moves to adapter boundary.

plugin/hooks/hooks.json:27, 32, 43 — Shell retry loops

20-iteration curl health-check retries across three hook entries. Plan 05-hook-surface Phase 1: delete shell retries; ensureWorkerRunning() does the one check.

API surface

src/services/worker/http/routes/DataRoutes.ts:305, 475, 510, 529, 548

• :305 — /api/processing-status (KEEP)
• :475 — /api/pending-queue GET inspection (DELETE)
• :510 — /api/pending-queue/process POST (convert to internal startup call or DELETE)
• :529 — /api/pending-queue/failed DELETE (DELETE)
• :548 — /api/pending-queue/all DELETE (DELETE)

Plan 06-api-surface Phase 1: delete diagnostic endpoints.

src/services/worker/http/routes/SessionRoutes.ts:148, 256 — threshold check + markSessionMessagesFailed. Plan 06-api-surface consolidates failure-marking paths.

---

Part 2: External API verification

API	Verified	Signature	Canonical use	Source
Node child_process.spawn({ detached: true })	✅ yes	spawn(cmd, args, { detached: true, stdio: ['ignore','pipe','pipe'] })	Creates new process group on Unix (setpgid). Child survives parent death unless parent signals group.	Node docs: https://nodejs.org/api/child_process.html#optionsdetached
Node process.kill(-pgid, signal)	✅ yes	Negative PID signals the whole process group on Unix. Works in Bun (uses libuv).	process.kill(-pgid, 'SIGTERM') tears down the whole child subtree.	POSIX kill(2); Node docs.
Bun.spawn detached	❌ NOT SUPPORTED	No detached option. Use proc.unref() for detach-from-parent-exit behavior only.	Not applicable to claude-mem — claude-mem uses Node API.	Bun docs: https://bun.com/docs/runtime/child-process
SQLite INSERT OR IGNORE / ON CONFLICT DO NOTHING	✅ yes	INSERT INTO t (a,b) VALUES (?,?) ON CONFLICT(a,b) DO NOTHING	Idempotent insert; silently skips row on UNIQUE violation.	SQLite core docs.
SQLite UNIQUE on added column	✅ yes with caveat	ALTER TABLE t ADD COLUMN c TEXT then CREATE UNIQUE INDEX ux_t_c ON t(c)	Must backfill c before creating unique index, or backfill with unique random values. See migration 22 precedent in runner.ts.	SQLite ALTER TABLE limitations doc.
fs.watch(dir, { recursive: true }) on Linux	✅ Node 20+ only	Recursive mode works on Linux in Node 20+ (was macOS/Windows-only earlier).	fs.watch(transcriptsRoot, { recursive: true }, (eventType, filename) => {…})	Node 20 release notes. Preflight: bump engines.node to >=20.0.0.
Claude Code hook exit codes	✅ per claude-mem CLAUDE.md	0 = success / graceful shutdown; 1 = non-blocking error (stderr to user); 2 = blocking error (stderr fed back to Claude)	process.exit(0) default; process.exit(2) to surface consecutive failures.	CLAUDE.md §Exit Code Strategy.
launchd user LaunchAgent plist	✅ (not currently used)	<key>KeepAlive</key><true/> + <key>ProgramArguments</key>… in ~/Library/LaunchAgents/ai.cmem.worker.plist	Documented for future installer if/when we adopt OS-supervised fallback.	Apple: launchd.plist(5).
systemd user unit	✅ (not currently used)	[Service]\nType=simple\nExecStart=/path/to/bun worker.js\nRestart=on-failure\nKillMode=control-group	Documented for future installer.	systemd.service(5), systemd.kill(5).
respawn npm package	✅ exists, NOT currently a dep	respawn(command, opts).start() with maxRestarts, sleep, kill. ~200 LOC pure JS.	Optional — only needed in the lazy-spawn wrapper for startup-crash retries.	https://github.com/mafintosh/respawn

---

Part 3: Plugin conventions

Concern	File	Pattern
Hook manifest	plugin/hooks/hooks.json	Setup, SessionStart, UserPromptSubmit, PreToolUse (Read matcher), PostToolUse, Stop, SessionEnd. Each shell-wraps bun-runner.js → worker-service.cjs.
Hook build targets	plugin/scripts/*-hook.js	TS source in src/hooks/ and src/cli/handlers/ → esbuild → plugin/scripts/*-hook.js (ESM).
Settings schema	src/services/domain/SettingsDefaultsManager.ts	loadFromFile(USER_SETTINGS_PATH). Flat key-value schema. Accepts 'true' string OR boolean true.
Privacy tags	src/utils/tag-stripping.ts	Six tag types: <private>, <claude-mem-context>, <system-reminder>, etc. Single-pass strip at every ingress (after Plan 03).
HTTP loopback replacement	(future) src/services/worker/http/shared.ts	ingestObservation(payload) → direct function call. Hooks still use HTTP (cross-process); worker→worker uses function call.
Observation XML	src/sdk/parser.ts	<observation type="…"><title/><narrative/><facts><fact/>…</facts>…</observation>.
Summary XML	src/sdk/parser.ts	<summary><request/><investigated/><learned/><completed/><next_steps/><notes/></summary>. Optional <skip_summary reason="…"/> bypass.
Project scoping	src/utils/project-name.ts	getProjectContext(cwd) → { primary, allProjects, excluded }. Excluded list from settings.

---

Part 4: Confidence + gaps

Confidence: HIGH (95%) — all anchors verified by direct read, all external APIs verified against docs.

Known gaps to flag in plans:

1. Chroma upsert fallback is brittle — error-text match for "already exist". Plan 01 must guard behind a flag until Chroma exposes upsert natively.
2. Prompt-caching TTL assumption — Plan 04 depends on SDK cache TTL ≈ 5 min. Run a cost smoke test before Plan 10 lands.
3. Node 20+ requirement — Plan 03 Phase 1 requires fs.watch recursive on Linux. Preflight: engines.node bump.
4. Zod is not currently a dep — Plan 06 Phase 1 is npm install zod@^3.x.
5. respawn dep is optional — Plan 02 §Lazy-spawn wrapper: decide in that plan whether to add respawn or hand-roll a 3-attempt startup retry.
6. Two registries today — src/services/worker/ProcessRegistry.ts + src/supervisor/process-registry.ts. Plan 02 consolidates to supervisor-only.

---

Status: READY FOR CORPUS AUTHORING. All plans in PATHFINDER-2026-04-22/ may cite this file directly.