Prerequisites and troubleshooting

Check the prerequisites first. Most installation problems come from a missing prerequisite. Windows-specific problems follow, then problems with Claude Desktop, then problems that affect every platform. To check that the installer supports your agent on your operating system, see Supported clients. To add Recallium to Claude Desktop chats, see Configure Recallium for chat apps.

Prerequisites

You need	For	Why
Node.js 22 or later	Everything	The installer and the Recallium connection run on Node.js.
Git	Coding agents, such as Claude Code, Codex, and Cursor	Coding agents run Recallium’s hooks through Git. Claude Desktop does not need Git.
Windows 10 or 11, macOS, or Linux	Everything	Windows 7 and 8 are not supported.

Let your agent check for you

Copy these instructions and paste them into your coding agent or Claude Desktop. The agent checks each prerequisite and tells you what to install. It does not change anything on your computer. To check each prerequisite yourself, follow the sections below.

Node.js 22 or later

The Recallium installer needs Node.js 22 or later. Check your version:

node --version

If the command is not found or shows a version below 22, install Node.js:

macOS
Windows
Linux

Install with Homebrew:

brew install node

Or download the LTS installer from nodejs.org.

Install with winget in PowerShell:

winget install OpenJS.NodeJS.LTS

Or download the LTS installer from nodejs.org. Open a new terminal after you install.

Git

The installer checks for Git before it connects any coding agent. Check your version:

git --version

If the command is not found, install Git:

macOS
Windows
Linux

Install Apple’s command line tools, which include Git:

xcode-select --install

Follow the steps in the window that opens.

Install Git for Windows with winget in PowerShell:

winget install --id Git.Git -e --source winget

Or download the installer from git-scm.com. Keep the default options so that Git Bash is installed. Claude Code on Windows runs its hooks through Git Bash.

Install Git with your distribution’s package manager. For example, on Debian or Ubuntu:

sudo apt install git

Installation

The installer says Git is missing

If Git is missing, the installer opens on a Before we start screen instead of the agent list. The screen names what is missing and how to install it. On Windows, the screen can also report Git Bash not found when Git is installed without Git Bash. Use these keys on the screen:

Key	Action
`o`	Opens the Git download page on Windows, or Apple’s installer on macOS
`r`	Checks again after you install Git
`s`	Continues without Git. Only Claude Desktop can be installed.
`q`	Quits the installer

Install Git as described in Git, then press r. The installer continues to the agent list.

When the installer runs without a screen, such as in a script or with --yes, it skips every coding agent, still connects Claude Desktop, prints the fix, and exits with an error.

`npx` runs an old version of Recallium

Without @latest, npx runs any copy of recallium that is installed in the current folder or a folder above it, before it downloads the published version. An old copy, for example in your home folder, makes npx -y recallium install start an outdated installer. Always include @latest in Recallium commands:

npx -y recallium@latest install

To remove the old copy, run this in the folder where it was installed, usually your home folder:

cd ~
npm uninstall recallium

Confirm the version that runs. It prints recallium v2 or later:

npx -y recallium@latest --version

The installer says the terminal is too small

The install screen needs a terminal at least 60 columns wide and 23 rows tall. In a smaller window, the installer stops without changing anything:

recallium install: this terminal is 20 rows; the Install/Modify screen needs 23.
  Nothing was written. Make the window taller and re-run, or wire what is
  detected here without the screen:  recallium install --yes

Make the terminal window taller or wider, then run npx -y recallium@latest install again. In a split pane, maximize the pane first. A terminal at least 120 columns wide also shows the guide panel next to the agent list.

Agent hooks fail after a restore or a cleanup

After you restore your computer from a backup, or delete the .recallium folder in your home folder, an agent can report a hook error such as:

/Users/you/.recallium/bin/recallium-hooks.cjs: No such file or directory

The agent’s settings still point at Recallium, but the files they run are gone. Run the installer again:

npx -y recallium@latest install

The install screen marks the affected agents as broken and names the reason. Press Start to repair them. The installer rewrites only the files that changed, and asks you to sign in again if the sign-in was lost.

Windows

PowerShell reports that running scripts is disabled

When you run the installer in PowerShell, the command stops before Recallium starts:

npx : File C:\Program Files\nodejs\npx.ps1 cannot be loaded because running scripts
is disabled on this system.

PowerShell blocks all scripts by default, and npx runs as a PowerShell script. Allow scripts for your user account, then run the installer again.

Allow scripts for your account

Open PowerShell and run:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Enter Y if PowerShell asks you to confirm the change.

Confirm the setting

Get-ExecutionPolicy -Scope CurrentUser

The command prints RemoteSigned.

Run the installer again

npx -y recallium@latest install

This setting applies to your user account only. It does not require administrator rights, and it does not change the policy for other users on the computer.

On a computer that your organization manages, a group policy can override this setting. If the error continues after you change the policy, ask your IT administrator to allow PowerShell scripts for your account.

Claude Desktop

Recallium does not appear in Claude Desktop

Claude Desktop reads its settings only when it starts, so you must quit it completely and start it again after you install.

On Windows, closing the Claude Desktop window is not enough. The app keeps running in the system tray, and opening it again returns to the same running app, which has not loaded Recallium. Exit Claude Desktop from the system tray, then start it again.

Exit Claude Desktop

On Windows, right-click the Claude icon in the system tray and click Quit. If you do not see the icon, click the ^ arrow in the taskbar to show hidden icons. On macOS, choose Claude > Quit Claude.

Start Claude Desktop again

If a browser window opens, sign in to Recallium once.

Look in the right place

Open Settings > Developer. Recallium is listed under Local MCP servers. It does not appear on the Connectors page.

Claude Desktop rejects the Recallium plugin

When you upload the Recallium plugin, Claude Desktop shows these errors:

A skill cannot contain a plugin manifest (recallium-chat/.claude-plugin/plugin.json).
SKILL.md file must be in the top-level folder, not nested deeper.

The file went into the skills uploader instead of the plugins uploader. In Claude Desktop, click Customize > Plugins > Add plugin, then upload the same file. Skills sits directly above Plugins in the menu.

All platforms

Check what is connected

Run the installer:

npx -y recallium@latest install

On a terminal, the install screen shows each agent with its state. On a wide terminal, the System panel shows whether you are signed in, whether the server is reachable, and whether hooks are running. Press Start to repair anything marked broken. npx -y recallium@latest status and npx -y recallium@latest doctor open the same screen.

My agent is not remembering anything

First check what is connected. Then make the request explicit and complete:

Remember this JWT implementation, including refresh-token rotation, the security trade-off, and the files we changed.

Look for the agent’s confirmation that the memory was stored.

Search returns nothing

Use a broader natural-language topic instead of an exact function or symbol name. Try:

Search our memories for user authentication and token validation.

If you know the file, include it as a second clue.

The result comes from the wrong project

Name the project and topic in the request:

Find authentication decisions in the payment-service project.

Check the repository mapping when the current clone uses a different name:

git config --local --get recallium.projectName

Search returns too many results

Add the kind of context, directory, or time window you need:

Find recent authentication decisions related to files under src/auth/.

Ask the agent to expand only the strongest matches before using their details.

A different coding agent cannot find the same context

Check what is connected and confirm that both agents are connected. Make sure both sessions resolve to the same Recallium project. If necessary, map the repository explicitly:

git config --local recallium.projectName existing-project-name

npx -y recallium@latest login

I still need help

Email support@recallium.ai. Include:

Your operating system
The coding agent or chat app you are connecting
The output from npx -y recallium@latest --version
A screenshot of the install screen from npx -y recallium@latest install
The step that failed and any error text

Getting started

Core concepts

Use Recallium

Best practices

Reference

Prerequisites and troubleshooting

Prerequisites

Let your agent check for you

Node.js 22 or later

Git

Installation

The installer says Git is missing

`npx` runs an old version of Recallium

The installer says the terminal is too small

Agent hooks fail after a restore or a cleanup

Windows

PowerShell reports that running scripts is disabled

Claude Desktop

Recallium does not appear in Claude Desktop

Claude Desktop rejects the Recallium plugin

All platforms

Check what is connected

My agent is not remembering anything

Search returns nothing

The result comes from the wrong project

Search returns too many results

A different coding agent cannot find the same context

I still need help

​Prerequisites

​Let your agent check for you

​Node.js 22 or later

​Git

​Installation

​The installer says Git is missing

​npx runs an old version of Recallium

​The installer says the terminal is too small

​Agent hooks fail after a restore or a cleanup

​Windows

​PowerShell reports that running scripts is disabled

​Claude Desktop

​Recallium does not appear in Claude Desktop

​Claude Desktop rejects the Recallium plugin

​All platforms

​Check what is connected

​My agent is not remembering anything

​Search returns nothing

​The result comes from the wrong project

​Search returns too many results

​A different coding agent cannot find the same context

​Cloud sign-in expired

​I still need help

Prerequisites

Let your agent check for you

Node.js 22 or later

Git

Installation

The installer says Git is missing

`npx` runs an old version of Recallium

The installer says the terminal is too small

Agent hooks fail after a restore or a cleanup

Windows

PowerShell reports that running scripts is disabled

Claude Desktop

Recallium does not appear in Claude Desktop

Claude Desktop rejects the Recallium plugin

All platforms

Check what is connected

My agent is not remembering anything

Search returns nothing

The result comes from the wrong project

Search returns too many results

A different coding agent cannot find the same context

Cloud sign-in expired

I still need help