Installation

Requirements

Desktop platform target: macOS 13+ on Apple silicon for the Electron app/pkg; Intel Macs are not supported, and install.sh and imprint update stop with a message on one (ADR 0111); Windows x64 and Linux x64/ARM artifacts have separate native validation gates. Native Windows/macOS execution of the current fixes is pending; see platform validation.

Core:

• Claude Code CLI
• A working network connection on first run (so the bundled uv can fetch Python + wheels)
• git, to index git repositories: imprint ingest and refresh take a repository’s files from git so its ignore rules apply. On Windows, repositories inside a WSL distribution use the distribution’s git; repositories on Windows drives need Git for Windows (ADR 0107)

Host Python is not required. Every release archive now ships Astral’s uv binary alongside imprint; on first run uv downloads a pinned Python 3.12 via python-build-standalone into the install dir’s .venv/. Nothing is installed system-wide.

Local models — llama.cpp: every installation includes llama-cpp-python 0.3.36, llama.cpp’s Python binding, which runs embeddings, the local tagger, summaries and chat (ADR 0086). Windows x64 and Linux x64/arm64 install upstream’s prebuilt wheel (ADR 0035), and macOS the prebuilt Metal wheel this repository publishes (ADR 0090), so no compiler is needed. ONNX Runtime’s CPU build (about 15 MB) is installed for OCR and the opt-in privacy filter.

Optional — GPU acceleration: any NVIDIA, AMD or Intel GPU through its graphics driver; no CUDA or other toolkit is installed. On Windows x64 and Linux x64 the gpu and auto install profiles install llama.cpp’s Vulkan build (a 40 MB wheel on Windows, 121 MB on Linux) and keep it only when it finds a GPU; macOS uses Metal (ADR 0049). Embeddings and the local LLM then run on one GPU: on an RTX 4080 Laptop, embedding ran at 7,316 tokens/s against 438 on the CPU, and a tagging call took about 4 s against 38 s. Pick the profile with --profile gpu at install, or imprint profile set gpu later. model.device (default auto) decides whether embeddings use the GPU (embeddings).

LLM topic tagging (IMPRINT_LLM_TAGS=1) — anthropic and openai SDKs are installed automatically in the base profile. No extra steps needed for any provider.

Optional — kreuzberg document extractor (ELv2, opt-in) — Replaces the built-in PDF/DOCX/image extractors with a more capable alternative that also adds archive formats (.zip, .7z, .tar), Apple iWork files, ODF documents, and email/mbox. Turn it on and Imprint installs it (kreuzberg 4.10.4, hash-locked in requirements/kreuzberg.lock.txt) into its own environment (ADR 0121):

imprint config set ingest.use_kreuzberg true

Wheels exist for Linux x64/arm64 (glibc 2.28 or later), Apple silicon macOS and Windows x64; elsewhere Imprint reports that it cannot be installed and keeps the built-in extractors. When kreuzberg is missing or fails on a file — its own image OCR needs Tesseract language data Imprint does not install — the built-in extractor handles that file.

License note: kreuzberg is published under the Elastic License 2.0 (ELv2). Internal and self-hosted use is permitted; offering Imprint as a hosted/SaaS service that exposes kreuzberg’s extraction is not. Turning ingest.use_kreuzberg on is your acceptance of ELv2: Imprint installs kreuzberg only while that setting is on.

Optional — obscura headless browser (Apache 2.0, opt-in) — Provides JS-rendered HTML extraction for imprint ingest-url, making it possible to fully index JS-heavy SPAs and documentation sites that return blank pages to static fetchers. Turn it on and Imprint downloads the pinned obscura release (v0.2.5, about 70 MB, checked against its SHA-256) into data/obscura-bin/; an obscura already on PATH is used when that is missing:

imprint config set ingest.use_obscura true

Releases exist for Linux x64/arm64, Apple silicon macOS and Windows x64. When use_obscura=true, imprint ingest-url pipes each URL through obscura fetch for JS execution before extraction, and falls back to a plain fetch when obscura is unavailable or fails.

Installing these tools. Setting either one with imprint config set installs it before the command returns; switching it on in the dashboard installs it in the background, and the setting shows the progress or the failure. imprint bootstrap (and so imprint update) installs every turned-on tool that is missing, and the first document or URL that needs a missing tool installs it once per process. A failure is printed with the manual fallback (imprint bootstrap --non-interactive, or the tool’s own install), extraction continues with the built-in extractors, and imprint doctor lists the tool until it is installed.

Quick Install

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/alexandruleca/imprint-memory-layer/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/alexandruleca/imprint-memory-layer/main/install.ps1 | iex

This downloads the pre-built imprint binary + bundled uv, picks the install profile (install.sh asks on a terminal, defaulting to GPU, and installs cpu under curl | bash; install.ps1 uses auto), provisions a Python venv via uv, installs the selected dependencies, registers the MCP server, configures Claude Code hooks, and sets up shell aliases. One command, everything ready.

Desktop startup and background operation

Search for Imprint in your system’s app launcher, or run imprint ui open. Either starts Imprint, or shows the dashboard when it already runs. The Windows installer adds Imprint to the Start menu and the macOS package installs /Applications/Imprint.app. Setup adds the rest: on Linux an application menu entry (~/.local/share/applications/imprint.desktop, or under $XDG_DATA_HOME, with the Imprint icon), and for a macOS install from install.sh an Imprint.app in ~/Applications, which Spotlight and Launchpad find. Uninstall removes what setup added. An install path with quotes, $, backslashes or newlines gets no launcher; setup says so. The desktop shell shows a loading screen while its hidden local service starts and the dashboard loads. Startup errors offer Try again and View startup log; cancelling startup exits the app. Ready Windows installs launch the GUI directly without opening a CLI console.

The shortcut and imprint ui open tell the desktop app where its runtime is (installation, data directory and Python). When the operating system starts the app by itself, for example Reopen after a crash, a Dock or Spotlight launch on macOS, or a pinned taskbar icon, the app asks the imprint CLI that ships beside it (imprint ui runtime, which prints the same paths as JSON). The paths stay defined in one place, the CLI.

Closing the dashboard hides it to the tray and keeps the service running, as on Windows: on Linux it leaves the taskbar, and on macOS the Dock icon goes too, back when the dashboard opens. Minimizing leaves it in the taskbar, unless the floating Imprint button is turned on (Settings → Desktop app, off by default), when minimizing hides to the tray too. The floating button and Echo stay off the taskbar. Reopen the dashboard from the tray (the macOS menu bar), the floating button when it is on (double-click it, or click it and choose Open dashboard) or the app launcher. Choose Quit Imprint at the bottom of the sidebar or in the tray menu to exit and stop the app’s service. On Linux desktops without a tray, close minimizes the window so you can reopen it from the taskbar; on macOS without a menu bar icon, the Dock icon stays.

If you previously ran imprint ui start, the app reuses that independent service and leaves it running on Quit. Whichever started it, the dashboard server registers itself in imprint_ui.json under the data directory: imprint ui status reports it, imprint ui stop stops it (the app then shows that its service stopped, with Try again), and imprint ui restart restarts it with the installed code without changing who owns it (ADR 0050). Both write startup diagnostics to imprint_ui.log under the data directory (imprint ui log shows the location). Qdrant is shared with CLI/MCP clients and remains independent of the dashboard. Browser-only distributions continue to use the explicit daemon lifecycle.

See ADR 0025 and platform validation for ownership and native GUI limitations.

If the dashboard reports Failed to connect to API, it retries automatically every three seconds; Try again retries immediately. Check imprint ui status and start the server with imprint ui start if it is stopped. Could not load dashboard means the API returned an error while loading memory data; starting another server will not fix that error. Run imprint ui log to locate the log, inspect its recent entries, and use Try again after correcting the cause. To diagnose an older release that keeps showing an error after the API starts, open the URL printed by imprint ui status in a browser and compare it with the app; quit with Quit Imprint before reopening the installed app (closing the window only hides it).

Memory index needs rebuilding means the collection’s embedding profile is incompatible with the configured encoder. The workspace menu remains available to create and switch to a fresh workspace. This preserves the old workspace; reindex sources and reimport any durable notes you need in the new workspace. Earlier releases report this as HTTP 500 and Failed to connect to API, even while /api/ping returns 200. See rebuilding after upgrading, including the CLI recovery command and limits on copying old vectors.

Clients inside WSL

The Windows installer offers Connect clients in WSL after copying its files. Select the detected Claude Code, Codex, Cursor, GitHub Copilot and/or Cline profiles you want to connect. They share the Windows installation’s memories and dashboard; a second Linux runtime is not installed. Discovery may start a distribution, skips Docker/Rancher utility distributions and inspects the distro’s default Linux user. No choices are selected on a fresh install.

Repair and silent updates reuse saved WSL choices. A fresh silent install does not change WSL profiles. Selected registration failures appear in the setup log and fail setup. Unchecking a profile stops future add/repair work for that choice; use the removal command to disconnect an existing profile.

You can enroll or remove profiles later in the dashboard: Settings → WSL profiles lists each distribution’s default-user profile for every client a WSL profile can be registered for, with whether it was found and whether this installation enrolled it. Enroll and Remove (asked first) run imprint wsl setup / imprint wsl remove through the job queue and show its log. The list comes from imprint wsl list --json, which reads the CLI’s client table, so a client added there appears without a dashboard change. Checking runs every distribution, which starts stopped ones, so the section checks only when you ask. Enrolling registers the installed Windows runtime and installs nothing (ADR 0053). Profiles enrolled this way are not installer selections: Repair does not replay them, and they keep working because the installation path does not change. Other Linux users and custom homes remain CLI-only.

Or from PowerShell (imprint wsl list prints the same listing as a table; --json for scripts):

$ImprintBin = Join-Path $env:LOCALAPPDATA 'Programs\Imprint\bin\imprint.exe'
& $ImprintBin wsl list
& $ImprintBin wsl setup --distribution Ubuntu --target claude-code
& $ImprintBin wsl setup --distribution Ubuntu --target codex
& $ImprintBin wsl setup --distribution Ubuntu --target cursor
& $ImprintBin wsl setup --distribution Ubuntu --target copilot
& $ImprintBin wsl setup --distribution Ubuntu --target cline

A Cursor selection is for learning only. With Remote-WSL, the Windows Cursor app runs the agent against the distribution and writes its conversations to the distribution’s ~/.cursor. Registering that profile lets imprint learn read them and writes nothing into it. Cursor’s MCP server and hooks come from imprint setup cursor on Windows (ADR 0052).

Under Remote-WSL, VS Code’s Copilot agent host runs inside the distribution, as the Copilot CLI does. A Copilot selection registers in the distribution’s Copilot home (COPILOT_HOME or ~/.copilot): the bridge launcher, the imprint entry in mcp-config.json, the managed block in copilot-instructions.md and hooks/imprint.json (SessionStart and Stop through the bridge). Learn reads its session-state (ADR 0057).

Cline’s VS Code extension runs inside the distribution under Remote-WSL, as the Cline CLI does, so a Cline selection registers there: the bridge launcher, the imprint entry in <cline home>/data/settings/cline_mcp_settings.json and the rule <cline home>/rules/imprint.md, where the Cline home is CLINE_DIR or ~/.cline. Learn reads its sessions from <cline home>/data/sessions. Cline gets no hooks (ADR 0056).

For Claude Code, Codex and Copilot, restart the selected client, verify the Imprint MCP server and review/trust its hooks. For Cline, reload the extension or restart the CLI. WSL Windows-executable interoperability must be enabled. The wizard detects existing default-user profile directories; it does not install Claude Code, Codex or WSL. Settings exported only by your interactive shell are not sourced during discovery. For another Linux user or profile, pass --user <name>, --claude-home /absolute/profile or --codex-home /absolute/profile. An explicit --python <Windows-path> can select an existing Windows Imprint interpreter. A non-default user’s profile must also be accessible through the Windows account’s WSL filesystem provider; setup does not change Linux permissions or elevate privileges.

Every distribution home with a connected client also gets the imprint command, at ~/.local/bin/imprint, where the Linux installer links it. It runs this Windows installation: status, doctor, ingest, refresh, learn, ingest-url, refresh-urls, retag, purge, workspace, config and device, with Linux paths translated. Setup, installation, updates and desktop commands run from Windows. Open a new WSL shell after the first registration: Ubuntu’s and Debian’s ~/.profile put ~/.local/bin on PATH only when it exists at login. Setup leaves an imprint that is not this command alone, such as a Linux installation’s link, and says so; that home keeps reaching the Windows runtime through "$HOME/.codex/imprint-wsl" cli … (or .claude). The command goes with the home’s last registration. Homes registered before the command existed get it on the next repair or update, or from imprint wsl setup (ADR 0091).

Setup does not approve or index project directories. To work with a WSL project through the Windows store, approve and index it from WSL:

cd ~/code/my-project
imprint workspace roots add "$PWD"
imprint ingest "$PWD"

Existing workspace overlap, sharing and purge rules apply. Linux files are accessed through the distribution’s Windows UNC namespace; mounted Windows drives use their real Windows paths, honoring custom mount locations. Windows paths returned by other tools can be translated with wslpath -u. Spaces, Unicode and apostrophes are supported; paths that cannot be represented through Windows filesystem APIs fail explicitly. Hook support follows the current host adapters; a configured entry alone does not establish host-side trust or transcript-version compatibility.

imprint learn and the dashboard’s Learn action also read each registered profile’s Claude Code, Codex, Cursor, Copilot and Cline conversations through \\wsl.localhost\<distro>\…, comparing their working directories the way the bridge does. Reading a distribution’s mount table can start it. A distribution that cannot be reached is skipped and listed under “Not learned” at the end of the run; the other stores are still learned.

To disconnect a selected profile manually:

& $ImprintBin wsl remove --distribution Ubuntu --target claude-code
& $ImprintBin wsl remove --distribution Ubuntu --target codex
& $ImprintBin wsl remove --distribution Ubuntu --target cursor
& $ImprintBin wsl remove --distribution Ubuntu --target copilot
& $ImprintBin wsl remove --distribution Ubuntu --target cline

Use the same user/profile override flags when removing a custom registration. Removal preserves memories and other integrations; it refuses to remove an Imprint entry that now points to a different runtime. Windows disable/uninstall also disconnects the WSL profiles previously registered by this installation, including recorded custom users and homes. If a recorded distribution or profile cannot be reached, cleanup fails and uninstall keeps the runtime for a retry. See ADR 0026 and platform validation.

Disable and uninstall

imprint disable disconnects this runtime from supported local clients and recorded WSL profiles, removes its hooks, Claude permission and managed instructions, and stops the explicit dashboard daemon and Qdrant. Runtime and memories remain available for imprint enable. Another installation’s MCP registration and associated rules are preserved. Cursor/Cline standalone rules are removed only when their contents match the generated rule; edited files are retained and reported. Other settings, servers, hooks and user-authored text are preserved. Configuration backups remain as inert recovery files.

imprint connect [client] and imprint disconnect [client] (default: all clients) rehook and unhook clients without the rest. Connect registers the installed runtime as setup would, but installs and starts nothing, and fails with “Run imprint setup first” when the runtime is missing. Disconnect removes only the chosen clients’ registrations, including the WSL profiles recorded for them, and stops nothing. ChatGPT Desktop registers through Codex’s profile, so disconnecting either disconnects both; a WSL registration comes back with imprint wsl setup. imprint clients shows which clients are connected, and the dashboard’s Commands page offers both commands (ADR 0053). Both also write your skills and personas into the folders the connected clients read, and take them out of folders no connected client reads any more.

Uninstalling removes Imprint completely (ADR 0028). After you confirm, it disconnects clients, then stops every process of this installation: the desktop app, its local service, MCP servers your clients started, running jobs and Qdrant. Then it deletes the runtime and your memories, workspaces and settings, together with the desktop app’s profile (window positions and the dashboard’s browser storage, in ~/Library/Application Support/imprint-ui on macOS, %APPDATA%\imprint-ui on Windows, ~/.config/imprint-ui on Linux). Every Imprint installation on your account shares that profile (ADR 0074). Processes Imprint only opened, such as a browser tab on the dashboard, and services you run yourself, such as Ollama, are left alone. To keep your data for a later reinstall, answer No when asked, or use the flags below. If a process cannot be stopped or a client cannot be disconnected, nothing is deleted; the log names the cause.

Use Windows Settings → Apps → Imprint → Uninstall, or the Start menu uninstaller. After Windows’ confirmation it asks whether to delete your data too (Yes deletes it, No keeps data\ in the install folder, Cancel stops). A silent uninstall (unins000.exe /VERYSILENT) deletes everything unless you add /KEEPDATA. It removes only this install’s user PATH segment. A failure cancels file removal; inspect uninstall-cleanup.log in the install directory, correct the reported error and retry. WSL cleanup uses the concrete profiles recorded during setup, with compatibility for the older installer’s saved distro/target selections. Registrations created manually by older versions with custom user/home flags were not recorded; disconnect those using the same flags before uninstalling.

On macOS, run Uninstall Imprint.command. It asks whether to delete your data in ~/.local/share/imprint and the desktop profile, cleans up as above, then removes the app, its CLI symlink and ~/.local/share/imprint once nothing is left in it, and stops on cleanup errors.

For archive/script installations, run imprint uninstall [-y]. It removes the whole installation including memories; --keep-data keeps memories and settings (--delete-data states the default explicitly). Cleanup errors stop runtime removal. Shell aliases and symlinks are removed only when they point into this runtime, and a source checkout never deletes a separate release installation. The command leaves the source/release tree when keeping data; native installer-owned files and OS shortcuts are removed through the native uninstaller. Hosted ChatGPT connectors and project-local configurations installed by hand are not managed local files and must be removed where they were configured. Custom native profiles require their setup environment (CLAUDE_CONFIG_DIR / CODEX_HOME) when running cleanup.

See ADR 0027 for client ownership and retry behavior, ADR 0028 for process and data removal and ADR 0074 for the desktop profile.

Profile flags

Skip the interactive prompt with CLI flags:

# GPU build when llama.cpp finds a GPU, no prompts
curl -fsSL .../install.sh | bash -s -- --profile gpu

# CPU build only (the default when piped)
curl -fsSL .../install.sh | bash -s -- --profile cpu

# Fully non-interactive: fail fast on any ambiguity
curl -fsSL .../install.sh | bash -s -- --non-interactive

The profile selects llama.cpp’s build, which runs embeddings and the local LLM: cpu installs the CPU build, and gpu and auto (the default of imprint setup and imprint bootstrap) install the GPU build and keep it when llama.cpp finds a GPU, so the two behave the same (ADR 0049, ADR 0086). On gpu and auto it also picks ONNX Runtime’s build for the Privacy Filter (below); cpu keeps ONNX Runtime’s CPU build. data/profile.json records it. Swap it later with imprint profile set cpu|gpu|auto, which re-runs the installer’s bootstrap step via uv. Whether embeddings use the GPU is model.device, which installs nothing.

Supported hosts

imprint setup all probes for each of the following and wires whichever it finds. Missing tools are skipped cleanly:

Target	Config path	Notes
claude-code	~/.claude/	Claude Code CLI (stdio MCP + hooks).
claude-desktop	macOS ~/Library/Application Support/Claude/ · Windows %LOCALAPPDATA%\Claude-Data\<install>\ (current builds), else %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\ (older MS Store install) or %APPDATA%\Claude\ (older standalone)	Anthropic’s desktop app. Writes the layout the installed app reads, newest first; an entry left in an older layout is removed by disconnect and does not count as connected. WSL2-aware: when run from a WSL shell, writes the config to the Windows-side claude_desktop_config.json and wires the command through wsl.exe -d <distro> -- env <PYTHONPATH=...> <venv-python> -m imprint, so the Windows app launches the Linux venv directly. No second Windows-side install needed.
chatgpt-desktop	~/.codex/config.toml (shared)	Current ChatGPT desktop versions load local MCP servers from Codex’s config.toml, so setup registers Imprint there; connecting or disconnecting either app does both. Under WSL it only reports the install: run the native Windows setup for the Windows app.
cursor	~/.cursor/	MCP + hooks + always-on rule.
codex	~/.codex/	Codex CLI (TOML config).
copilot	~/.copilot/ (COPILOT_HOME)	GitHub Copilot on VS Code 1.143+, the Copilot CLI and JetBrains: mcp-config.json entry, managed block in copilot-instructions.md, and hooks/imprint.json (SessionStart, Stop). Detected from the Copilot home, copilot on PATH or a VS Code install. imprint learn reads its sessions.
cline	~/.cline/ (CLINE_DIR; data in CLINE_DATA_DIR)	Cline 4 on every surface (VS Code extension and forks, CLI, JetBrains, desktop): MCP entry in <data>/settings/cline_mcp_settings.json (or CLINE_MCP_SETTINGS_PATH) and the rule <CLINE_DIR>/rules/imprint.md. No hooks; imprint learn reads its sessions.
opencode	~/.config/opencode/ (OPENCODE_CONFIG_DIR, or under XDG_CONFIG_HOME)	MCP entry under mcp in opencode.json, the rule imprint.md listed in its instructions, and plugins/imprint.js, which learns a session when it goes idle. imprint learn reads its sessions from OpenCode’s SQLite database (ADR 0124).
openclaw	~/.openclaw/openclaw.json	Also recognized as clawdbot / moltbot. Nested mcp.servers key.

Target a specific host with imprint setup <target> (e.g. imprint setup claude-desktop).

Auto-syncing past conversations from Claude Desktop / ChatGPT Desktop

Neither consumer app keeps conversation content in a stable on-disk format — both load chats from the vendor’s server on demand. The supported path is the built-in export:

• Claude Desktop / claude.ai — Settings → Privacy → Export data. Emails a zip.
• ChatGPT Desktop / chat.openai.com — Settings → Data controls → Export. Emails a zip.

Once the zip lands in your Downloads folder, run:

imprint learn --desktop

What it does:

• Scans common Downloads locations (WSL-aware: both ~/Downloads on Linux and /mnt/c/Users/<user>/Downloads on the Windows side).
• Detects Claude / ChatGPT exports by sniffing the zip contents (fingerprint files like projects.json, message_feedback.json), not just filenames.
• Runs each new zip through the existing JSON extractor — one searchable memory per conversation, split into chunks, tagged.
• Dedups by SHA-256 of the zip; re-runs are cheap and skip anything already indexed.
• Stores under projects claude-desktop-convos and chatgpt-desktop-convos.

Keep it running in the background while you request new exports:

imprint learn --desktop --watch            # polls every 30 s by default
imprint learn --desktop --interval 300     # every 5 min
imprint learn --desktop --path ~/Archive   # extra folder(s) in addition to Downloads

imprint learn on its own indexes Claude Code transcripts and auto-memory files, Codex sessions, Cursor agent conversations, GitHub Copilot sessions and Cline sessions. It reads them from this computer’s profiles (CLAUDE_CONFIG_DIR or ~/.claude, CODEX_HOME or ~/.codex, ~/.cursor, COPILOT_HOME or ~/.copilot, and Cline’s sessions directory: CLINE_SESSION_DATA_DIR, else <CLINE_DATA_DIR, else CLINE_DIR/data, else ~/.cline/data>/sessions) and from every client profile registered in WSL. --desktop is additive. Neither needs an approved workspace root: the Downloads folders are where exports land, and each conversation’s recorded working directory decides which workspace it belongs to. Extra --path folders must be inside the workspace’s approved roots. See workspaces.

Install a specific version or channel

The default installer resolves /releases/latest, which GitHub maps to the most recent stable (non-prerelease) build. Two release channels are published (ADR 0066):

Channel	Tag pattern	Produced by
stable	vX.Y.Z	conventional-commit release on every merge to main
dev	vX.Y.Z-dev.N	prerelease of the next stable version on each push to dev that has a feat, fix, perf or breaking change; N counts the builds of that version

Dev builds go through the same packaging and native checks as stable releases. A dev build ranks below the stable release it leads to: v0.25.0-dev.3 comes after v0.24.1 and before v0.25.0. The dev channel installs the highest version published, prerelease or stable. Once dev has been released as stable, that stable release is also the dev channel’s latest build, because no prerelease is built for a commit that main holds.

Pin a specific release or switch channels via env var or CLI flag.

Linux / macOS:

# Pin to a specific tag (env var)
IMPRINT_VERSION=v0.2.0 curl -fsSL https://raw.githubusercontent.com/alexandruleca/imprint-memory-layer/main/install.sh | bash

# Pin via CLI arg
curl -fsSL https://raw.githubusercontent.com/alexandruleca/imprint-memory-layer/main/install.sh | bash -s -- --version v0.2.0

# Latest dev build
IMPRINT_CHANNEL=dev curl -fsSL https://raw.githubusercontent.com/alexandruleca/imprint-memory-layer/main/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/alexandruleca/imprint-memory-layer/main/install.sh | bash -s -- --dev

Windows (PowerShell):

# Pin to a specific tag
$env:IMPRINT_VERSION = "v0.2.0"; irm https://raw.githubusercontent.com/alexandruleca/imprint-memory-layer/main/install.ps1 | iex

# Latest dev build
$env:IMPRINT_CHANNEL = "dev"; irm https://raw.githubusercontent.com/alexandruleca/imprint-memory-layer/main/install.ps1 | iex

# Or download and pass args directly
irm https://raw.githubusercontent.com/alexandruleca/imprint-memory-layer/main/install.ps1 -OutFile install.ps1
.\install.ps1 -Version v0.2.0
.\install.ps1 -Dev

Precedence: CLI flag > IMPRINT_VERSION env > IMPRINT_CHANNEL=dev env > default stable. The installer downloads that release’s archive and verifies it against SHA256SUMS.

Updating an existing install

When a newer release exists on this installation’s update channel, the dashboard shows Update to vX.Y.Z at the top right. It explains what will happen on this machine, runs the update and reloads the dashboard once the new version is running. The dashboard checks GitHub’s releases API at most every six hours while it is open, and again as soon as the channel changes.

While the dashboard runs, new releases also install by themselves (update.auto, on by default, Settings → Updates; ADR 0175). The dashboard looks every 30 minutes, asking GitHub at most every 6 hours, and installs only when nothing would be interrupted: no job, recording, chat reply or Echo conversation running, no agent using Imprint in the last 15 minutes, and no keyboard or mouse input for 10 minutes on Windows and macOS. Like Update now, it restarts the dashboard and, on Windows, closes and reopens the desktop app. A macOS package install still waits for Update now, since the Installer needs you. Turn it off to choose when Imprint changes.

The channel is the update.channel setting, Settings → Updates in the dashboard (ADR 0108):

• stable (the default): only stable releases are offered. An installation running a dev build is offered the stable release that follows it.
• dev: dev builds are offered too, as they are published, and stable releases once they are newer. Switching back to stable offers nothing until a stable release is newer than the build installed.

The terminal follows the same setting, so imprint update and the dashboard always agree. --stable or --dev overrides it for one run:

imprint update                 # latest release on the update channel (asks for confirmation)
imprint update --stable        # latest stable, whatever the setting
imprint update --dev           # latest dev build (a dev prerelease, or stable once it is newer)
imprint update --version v0.3.1
imprint update --check         # prints current + latest and exits
imprint update --check --json  # the same, as JSON
imprint update -y              # skip confirmation, for scripts / CI

Every download is verified against the release’s SHA256SUMS before anything is installed. An update refuses to start while an ingest or other queued job runs. How it installs depends on how Imprint was installed (ADR 0023):

Installed with	Update
install.sh / install.ps1	Replaces the install tree in place, re-runs imprint setup and restarts the running dashboard server. The previous files in bin/ are kept as bin/<name>.prev for a manual rollback.
Windows installer	Runs the new setup.exe silently while Imprint keeps running. After provisioning, it restarts the running dashboard server and reopens Imprint; your install profile (llama.cpp’s build) and settings are kept. When the release replaces installed packages, setup first stops Imprint’s MCP servers, so AI clients reconnect Imprint (ADR 0084). The installer log is data/update-setup.log; the dashboard follows it, shows it if the installer fails, and restarts its server itself if the installer’s restart did not reach it (ADR 0128).
macOS .pkg	Opens the new .pkg in Installer, which asks for your password, then restarts the running dashboard server.
Docker	Pull the new image and recreate the container; the /data volume is kept.
Source checkout	git pull and rebuild.

Intel Macs get no new releases (ADR 0111). An Intel build of this version or later refuses to update with “Intel Macs are no longer supported”; one running under Rosetta on an Apple silicon Mac is told to install the Apple silicon build instead. Earlier Intel builds stop when the release has no imprint-darwin-amd64 asset, without changing anything.

What’s preserved: data/ (workspaces, Qdrant storage, SQLite graphs, config.json, workspace.json, profile.json) and .venv/ (Python virtual environment). An in-place update overwrites the release’s files and leaves files that newer releases dropped. Installations from before ADR 0023 update once by the old route (installer, install script or imprint update) before the dashboard can update them.

The dashboard server is restarted under whoever started it: the desktop app or imprint ui start. The desktop app’s own window code updates the next time you quit and reopen Imprint. Releases before ADR 0050 cannot restart their server this way, so after the first update from one of them, reopen Imprint once.

Re-running install.sh against an existing install also still works, but it now requires confirmation:

# Interactive (TTY): prompts "Upgrade existing install? [y/N]"
bash install.sh

# Non-interactive (curl | bash): must opt in explicitly
IMPRINT_ASSUME_YES=1 curl -fsSL .../install.sh | bash
curl -fsSL .../install.sh | bash -s -- --yes

llama.cpp and ONNX Runtime

Setup installs two native runtimes into the venv (ADR 0086):

• llama.cpp’s binding runs embeddings, the local tagger, summaries and chat. The install profile picks its build: the GPU build from requirements/llm-gpu.txt, kept when llama.cpp finds a GPU (llama_supports_gpu_offload()), otherwise the CPU build from requirements/llm.txt. On those profiles setup checks the GPU build on every run, so after installing or updating a graphics driver another imprint setup picks it up. Setup fails when the binding does not load. A binding that stops loading later is a damaged installation: chat, the tagger and imprint doctor say to run imprint bootstrap --non-interactive.
• ONNX Runtime runs OCR, audio VAD and the opt-in privacy filter: its CPU build (requirements/cpu.txt), or a GPU build in its place for the privacy filter (below). ONNX Runtime’s builds share one package directory, so setup keeps exactly one: it removes any other build, with what only that build brought in, and reinstalls a build with missing files. Rerunning imprint bootstrap --non-interactive repairs module 'onnxruntime' has no attribute 'InferenceSession', and imprint doctor reports the damage (ADR 0032).

Privacy Filter on a GPU

The opt-in Privacy Filter (redact.privacy_filter, secret redaction) takes about a second per memory on a CPU. On the gpu and auto profiles setup installs ONNX Runtime’s build for a GPU it finds instead of the CPU build, checks that it runs a tiny model on that GPU, and otherwise goes back to the CPU build (ADR 0122). OCR and audio keep running on the CPU with any build.

Machine	Build	Extra download
NVIDIA GPU of compute capability 7.5 or newer listed by nvidia-smi (CUDA 13’s minimum, ADR 0126), Linux x64 or Windows x64	onnxruntime-gpu with NVIDIA’s CUDA 13 and cuDNN wheels (requirements/onnx-cuda.lock.txt); needs only the NVIDIA driver	about 2.5 GB installed
AMD GPU on Linux x64 with ROCm 7.2.0–7.2.4 installed (/opt/rocm/.info/version, and rocminfo lists a GPU agent)	AMD’s onnxruntime-migraphx 1.23.2 wheel for that ROCm release, from repo.radeon.com, pinned by SHA-256 in requirements/onnx-rocm.json	about 20 MB
Windows x64 with a DirectX 12 GPU where CUDA does not apply or does not run (AMD, Intel, NVIDIA without CUDA)	onnxruntime-directml 1.24.4 (requirements/onnx-directml.lock.txt)	about 25 MB
Apple silicon	the standard build, which includes Core ML	none
Anything else	the CPU build	none

Setup does not install GPU drivers or ROCm. An AMD GPU on Linux without ROCm, or with another ROCm release, stays on the CPU, and setup says so: install ROCm 7.2.x from AMD (it needs root and a kernel driver matched to it), then run imprint setup again. A GPU build is only the opportunity: the model itself moves to the GPU only after its first-use check finds the GPU labels exactly like the CPU and is at least 1.5 times faster. Some providers run only part of this model (DirectML and Core ML have no kernel for its mixture-of-experts layers, which then run on the CPU), so the check may keep the CPU. To keep the CPU build and its smaller download, choose the cpu profile: imprint profile set cpu, or --profile cpu at install; that also puts llama.cpp on its CPU build.

An installation from a release that embedded through CUDA loses onnxruntime-gpu and the NVIDIA libraries only it brought in on its next update or imprint setup (python -m imprint.onnx_runtime unused names them), and setup clears them from the install’s uv cache, whose files the environment shares, so their disk space is freed. onnx and ml-dtypes, which the old CUDA check installed (about 20 MB), stay. Before it replaces or removes packages, setup restarts the dashboard server and, on Windows, stops Imprint’s MCP servers; AI clients reconnect Imprint (ADR 0084). The new embedding model also changes the embedding profile: reindex into a new workspace (embeddings).

Run the relay server (Docker)

Prebuilt multi-arch images (linux/amd64, linux/arm64) are published to GHCR after every release:

docker run -p 8430:8430 ghcr.io/alexandruleca/imprint-relay:latest

Full deployment guide — pinned tags, docker compose, TLS termination (Caddy / Traefik / Nginx), health checks, and manual rebuilds — lives on the dedicated Docker page. See sync.md for how peer sync uses the relay.

Integrity and diagnostics

Install/update verifies release archives against SHA256SUMS before extraction. Bundled uv and auto-downloaded Qdrant use pinned SHA256 values; Python profiles use hash locks. This is not an offline installer or independently signed publisher verification. Models and managed Python still download on first use. Windows signatures/macOS notarization remain pending maintainer configuration.

Run imprint doctor --json --probe-mcp after installation to inspect runtime dependencies, dashboard, primary Codex registration, Qdrant readiness and a timed MCP initialize/list-tools handshake. It is read-only and does not provision models. Confirm client-side trust/tools after restarting the host.

OCR runtime

OCR defaults on for images and scanned PDFs. Bootstrap and update install RapidOCR with its bundled small Chinese/English models, Pillow and PDFium through the hashed base requirements. No separate Tesseract or Poppler install is needed for the default eng/auto path. Existing explicit OCR opt-outs are preserved. Other ingest.ocr_lang values select the Tesseract compatibility backend and still require that system tool and its language data. When extraction encounters missing bundled OCR dependencies, the managed ingest/refresh commands let the extraction worker exit, release the queue lock, try imprint bootstrap --non-interactive once, then retry in a fresh Python process. Repair logs appear on stderr; failed repairs remain visible and retain the previous index. Explicit opt-outs and custom Tesseract requirements do not trigger bootstrap. Direct Python callers still report the missing runtime; run the same command manually if automatic repair fails. See ADR 0109. See ADR 0076.