memtrace rail & routeBeta

Rail is an experimental Memtrace-first discovery router: it intercepts an agent’s raw grep/glob/find calls and, depending on mode, allows, nudges, or replaces them with graph search — fully fail-open by design.

Usage#

Rail is Memtrace's experimental "Memtrace-first discovery router." Once enabled, it intercepts an AI coding agent's raw discovery calls — Claude Code's native Grep/Glob, or a shell rg/grep/find/ag/fd invocation wrapped in Bash — via PreToolUse-style hooks on supported agent hosts. Depending on the configured mode, it lets the raw search through unchanged, injects Memtrace context alongside it, or suppresses the raw search entirely in favor of Memtrace's own find_code results.

memtrace rail is the management surface: it enables/disables the feature (persisting a mode and wiring hooks into every supported agent host) and reports status/telemetry/wiring health. The actual per-attempt routing decision is made by the sibling memtrace route command, which the installed hooks invoke on every discovery call.

Modes#

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

• off — routing is a complete no-op; raw search always runs.
• observe (the global default when nothing is configured) — 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 mode when you run rail enable with no argument) — 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#

Every wired hook resolves to the same pipeline. 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 once per discovery tool call by an installed PreToolUse-style 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. The installed hooks actually 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.
# In default observe mode this always allows raw and never touches
# the daemon.

$ memtrace route --hook --host claude-code
# The exact form the Claude Code PreToolUse hook invokes: stdin is
# Claude's raw hook payload, stdout is Claude's hookSpecificOutput
# JSON.

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