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

> Easily install optional Feynman packages like session-search. Learn how to enhance your Feynman installation with custom presets and runtime patches for Node.js 22.x.

- Repository: [Advait Paliwal/feynman](https://github.com/advaitpaliwal/feynman)
- Tags: how-to-guide
- Published: 2026-09-08

---

**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`](https://github.com/advaitpaliwal/feynman/blob/main/src/cli.ts), fetches the npm package `@kaiserlich-dev/pi-session-search`, and applies runtime patches from [`src/pi/runtime-patches.ts`](https://github.com/advaitpaliwal/feynman/blob/main/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.

```bash
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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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:

```bash
feynman packages install session-search

```

The CLI performs three distinct operations defined in [`src/cli.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/cli.ts):

1. **Preset Discovery** – Resolves the preset name against the registry in [`src/pi/package-presets.ts`](https://github.com/advaitpaliwal/feynman/blob/main/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:

```text
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`](https://github.com/advaitpaliwal/feynman/blob/main/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:

```bash
$ 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`:

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

```

## Using `session-search` in the REPL

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

```bash
$ 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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/src/pi/package-presets.ts) (lines 38-43)
- **Automatic patching** – [`src/pi/runtime-patches.ts`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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`](https://github.com/advaitpaliwal/feynman/blob/main/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.