memtrace rail & routeBeta

Add relevant graph context to ordinary code discovery, choose a Rail mode, and manage the hooks maintained by your workspace daemon.

Usage#

Keep memtrace start running in your repository. Its bundled Node helper registers supported agent hooks automatically. With no mode configured, Rail usesnudge: relevant graph context accompanies ordinary discovery, and raw tools remain available. Use memtrace rail to inspect or change the behavior; a separate enable command is not required.

Managed stock skills adopt the contextual default on upgrade. Customized skills, explicit user or project workflows, and existing strict, off, or enrichment opt-outs are preserved. Standalone MCP supplies explicit tools and guidance; automatic context requires the workspace daemon.

Modes#

Rail has five modes, resolved with precedence --mode flag on route > MEMTRACE_RAIL env > persisted ~/.memtrace/rail.json > default nudge.

• off — routing is a complete no-op; raw search always runs.
• observe — the hook path never queries the daemon inline. A Memtrace-owned attempt is classified but the decision is always AllowRaw, so agent latency is unaffected. A separate, invisible shadow-measurement spool may record a content-free entry for later trust-dataset aggregation.
• nudge (the default when no mode is configured) — makes one bounded daemon query per Memtrace-owned attempt. A relevant hit still lets the raw command run, but attaches Memtrace's result alongside it (InjectContext). Never blocks.
• rail — enforcing. A relevant hit suppresses the raw search entirely and returns Memtrace's result instead (SuppressRawWithResult).
• strict — same enforcing behavior as rail, the strictest mode currently shipped.

Subcommands#

status

memtrace rail status is read-only: it prints a JSON object with the resolved mode, the MEMTRACE_RAW_SEARCH escape-hatch state, and a fixed advisory note that routing is search-backed (queries the running daemon's find_code), fails open on any backend failure, and requires memtrace start to be running for routing to take effect. It does not verify the daemon is actually running.

report

memtrace rail report reads the local rich telemetry JSONL (~/.memtrace/rail-telemetry.jsonl) and the content-free shadow telemetry JSONL (~/.memtrace/rail-shadow.jsonl), aggregates each into counters — coverage, precision proxy, hit/miss/unavailable counts, score/latency/query-shape histograms — and prints a combined {"local": ..., "shadow": ...} JSON report to stdout. Missing or unreadable files degrade silently to all-zero counters rather than erroring.

doctor

memtrace rail doctor prints a small fixed JSON health object: router: "ok", the resolved mode, and backend_port: "fail_open_placeholder".

enable [mode]

memtrace rail enable [off|observe|nudge|rail|strict] persists the given mode (default nudge if no argument) to ~/.memtrace/rail.json, then calls the bundled Node installer's install-rail subcommand to wire discovery hooks into every supported agent host: Claude, Cursor, Codex, Gemini, OpenCode, Windsurf, and VS Code Copilot. If the mode is nudge, it prints extra guidance that raw search still runs with Memtrace context injected alongside it.

Hook-wiring requires node on PATH and the bundled installer. If either is missing, enable still persists the mode — it prints a warning and tells you to run the installer manually rather than failing the command.

disable

memtrace rail disable persists mode off and best-effort removes the Rail hook entries from every supported host's config. Unlike enable, a failure here is silently swallowed rather than warned about.

help

memtrace rail help (also the fallback for no args, --help, or -h) prints the Rail usage banner to stderr and exits 0. An unrecognized subcommand instead prints an error to stderr and exits with status 2 — it does not fall back to help.

How a discovery call is routed#

Pre-tool routing uses the pipeline below; Nudge post-search enrichment uses the host's after-tool surface. Only attempts on a surface Memtrace actually owns (inside the indexed root, source, not generated/vendored) continue past classification — everything else allows the raw command through with zero backend contact.

In observe mode the daemon is never queried inline — the pipeline stops at the posture check. In nudge/rail/strict, a relevant hit (score clearing a mode-aware floor) either attaches Memtrace's result alongside the raw search (nudge) or suppresses the raw search and returns Memtrace's result instead (rail/strict). Any connection error, non-2xx status, timeout, or bad JSON from the daemon is treated as unavailable and always falls open to allow.

memtrace route#

route is the internal hook entry point that does the actual per-attempt classification. It is invoked by a supported pre-tool routing hook — not typically run by hand. memtrace route ARGS is a thin alias that forwards into the same dispatcher as memtrace rail route ARGS, one token shorter.

Pass --json '<ToolAttempt>' for a one-shot manual classification: it prints a bare DecisionEnvelope JSON to stdout and exits 0. Use --json - or --stdin to read the attempt from stdin instead. Pre-tool routing hooks invoke the --hook form — stdin is a raw host PreToolUse payload (not a pre-built ToolAttempt), and output is reshaped into that host's own hook-output schema (for example Claude's hookSpecificOutput.permissionDecision).

A relevant daemon hit is gated by score, not just result count: the top result must clear a mode-aware relevance floor (0.0 for nudge, since it never blocks anyway; 0.06 for rail/strict, calibrated against the RRF scorer's measured true-hit-versus-junk band) or it downgrades to a miss and the raw command proceeds untouched.

Environment variables#

Gotchas#

Examples#

$ memtrace rail status
# Shows resolved mode, MEMTRACE_RAW_SEARCH escape state, and a
# routing-requires-daemon note. Read-only.

$ memtrace rail enable nudge
# Persists mode=nudge and wires discovery hooks into every
# supported host. Requires node on PATH. Never blocks raw search,
# only injects Memtrace context alongside it.

$ memtrace rail enable rail
# Enforcing mode: Memtrace-owned hits suppress the raw search
# result entirely.

$ memtrace rail disable
# Persists mode=off and best-effort removes wired hooks from all hosts.

$ memtrace rail report
# Prints aggregated local + shadow telemetry counters as JSON.

$ memtrace route --json '{"host":"generic","cwd":"/repo","tool":"Bash","input":{"command":"rg foo"},"session_id":"s1"}'
# Manual one-shot classification; prints a DecisionEnvelope JSON.
# Manual classification uses the selected mode; ordinary tools remain
# available in the default nudge mode.

$ memtrace route --hook --host claude-code
# The form used by Claude Code pre-tool routing in Rail/Strict: stdin is
# Claude's raw hook payload, stdout is Claude's hookSpecificOutput
# JSON.

See also memtrace start, memtrace mcp, memtrace install, and Hooks.