How to Install Optional Feynman Packages Like `session-search`

Install the session-search preset by running feynman packages install session-search on Node.js 22.x; the CLI validates your runtime against src/cli.ts, fetches the npm package @kaiserlich-dev/pi-session-search, and applies runtime patches from src/pi/runtime-patches.ts.

The Feynman CLI maintains a lightweight core by separating extended capabilities into optional presets. The session-search package adds indexed recall of prior research sessions using a native SQLite dependency, but requires specific Node.js versioning and installation commands to function correctly according to the advaitpaliwal/feynman source code.

Prerequisites: Node.js 22.x Runtime

The session-search preset relies on native SQLite bindings that only compile against Node.js 22.x. Before installation, verify your active version matches this constraint.

node -v

# Expected output: v22.x.x (e.g., v22.12.0)

Running on Node 24.x or later triggers a validation failure in src/cli.ts (lines 26-33), causing the CLI to skip the native package installation and fall back to file-based search methods.

Installing the session-search Package

The session-search preset is declared in the package registry at src/pi/package-presets.ts (lines 38-43). The CLI consumes this metadata to resolve the npm source npm:@kaiserlich-dev/pi-session-search.

Run the install command:

feynman packages install session-search

The CLI performs three distinct operations defined in src/cli.ts:

1. Preset Discovery – Resolves the preset name against the registry in src/pi/package-presets.ts
2. Runtime Validation – Checks Node version compatibility (lines 26-33)
3. Package Installation – Executes npm install under Feynman’s managed prefix (around line 50)

If successful, you will see:

npm install @kaiserlich-dev/pi-session-search@latest
Optional packages installed.

Post-Install Patching

After installation, Feynman applies runtime-specific patches to ensure the package respects Feynman-specific session directories. This logic resides in src/pi/runtime-patches.ts (line 53) and modifies the installed module to point to ~/.feynman/sessions for its indexing operations.

Handling Unsupported Node Versions

If you attempt installation on Node 24.x, the CLI outputs a warning and skips the native dependency:

$ node -v
v24.0.0

$ feynman packages install session-search
Skipped npm:@kaiserlich-dev/pi-session-search on Node 24.0.0 (native packages are only supported through Node 22.x).

In this scenario, the REPL remains functional but lacks the /search slash command. Use the fallback file-search utility with rg:

rg -n "protein folding" ~/.feynman/sessions

Using session-search in the REPL

Once installed, start the Feynman REPL and invoke the search command:

$ feynman
/.../ REPL> /search transformer scaling laws

The command returns matching prior sessions with timestamps and excerpts. You can verify availability by checking if the /search slash command appears in the REPL help, which the CLI populates based on installation status (referenced in src/cli.ts, lines 70-73).

Summary

• Node.js 22.x is mandatory – The native SQLite dependency in session-search requires this specific runtime, validated in src/cli.ts
• Install via preset name – Run feynman packages install session-search to trigger the npm fetch for @kaiserlich-dev/pi-session-search
• Registry location – Preset definitions live in src/pi/package-presets.ts (lines 38-43)
• Automatic patching – src/pi/runtime-patches.ts applies directory-specific fixes post-installation
• Graceful degradation – On unsupported Node versions, the CLI skips installation but allows fallback file searching with rg

Frequently Asked Questions

What Node.js version is required to install session-search?

Node.js 22.x is strictly required. The native SQLite bindings used by the package only compile against this version, and the CLI explicitly checks for this in src/cli.ts (lines 26-33) before attempting installation.

Can I force installation on Node 24.x or newer?

No. The CLI will skip the npm package installation and output a warning message. However, you can still search session files directly using rg or similar tools against the ~/.feynman/sessions directory as a fallback.

Where does Feynman define the session-search preset?

The preset metadata is defined in src/pi/package-presets.ts (lines 38-43), which maps the preset name session-search to its npm source npm:@kaiserlich-dev/pi-session-search.

How do I verify that session-search installed correctly?

Start the Feynman REPL with feynman and check if the /search slash command is available in the help menu. Alternatively, attempt to run /search <query>; if the command returns indexed results with timestamps, the installation succeeded.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}