Installation

Palimem runs as a local service on your machine. No cloud account. No mandatory SaaS. Your memory data lives in a SQLite database on disk you control.

Prerequisites

Python 3.13+

Required for the MCP server and hook CLIs. Verify with python3 --version.

Node.js 18+

Required for the MCP stdio wrapper and operator CLI. Verify with node --version.

Git

Clone palimem/palimem for contributors, or install from npm.

Claude Code, Cursor, or another MCP harness

At least one supported coding agent.

Platform prerequisites

Homebrew (recommended):

brew install python@3.13 node

Verify:

python3 --version   # Python 3.13.x
node --version      # v18.x or higher

macOS data directory default: .ai-memory/data inside your project root.

Ubuntu/Debian:

sudo apt update
sudo apt install python3.13 python3.13-venv nodejs npm

Fedora/RHEL:

sudo dnf install python3.13 nodejs npm

Verify:

python3 --version
node --version

winget:

winget install Python.Python.3.13
winget install OpenJS.NodeJS.LTS

Or download installers:

Windows data directory default: .ai-memory\data inside your project root. Use %APPDATA%\palimem\data for a user-global store.

Windows MCP path note: Use absolute paths with forward slashes in MCP config files, or use the ai-memory connect CLI which resolves paths automatically.

Quick install (npx)

Install @palimem/mcp from npm. No clone required. From your project directory with Node.js 18+:

npx -y @palimem/mcp@latest ai-memory connect <harness> \
  --project-root "$(pwd)" \
  --launcher npx \
  --data-dir .ai-memory/data

Harness	`<harness>` value	Integration guide
Cursor	`cursor`	Cursor
Windsurf	`windsurf`	Windsurf
Copilot CLI	`copilot`	Copilot CLI
Codex	`codex`	Codex
VS Code + Copilot Agent / Copilot IDE	`vscode`	VS Code
Gemini CLI	`gemini`	Gemini CLI

--launcher npx tells the connect helper to write MCP config with npx -y @palimem/mcp instead of a local clone path. See v1.7.2 release notes for the version matrix.

Fallback (GitHub specifier, no npm registry): npx github:palimem/palimem ai-memory connect <harness> --project-root "$(pwd)" --launcher npx --data-dir .ai-memory/data

Claude Code and the Claude Code plugin use separate install paths — see Claude Code and Claude Code plugin.

Install from source

Clone the repository

git clone https://github.com/palimem/palimem
cd palimem

Install Node.js dependencies
Terminal window
```
cd app
npm install
cd ..
```
This installs the MCP stdio wrapper (memory-service-mcp.js) and the operator CLI (ai-memory.js).
Verify the component validation entrypoint (optional, for contributors)
Terminal window
```
python3 tests/run_validation.py
```
Expect 143/143 behaviors passing against spec v1.7.0. This is the orchestrator-facing black-box validation suite.

Optional maintainer release gate:
Terminal window
```
bash examples/claude-code/demo/phase6-readiness.sh
bash integrations/run_readiness.sh
```
Verify the MCP server (after connecting a harness)

Ask your agent to call tools/list (expect 11 tools), then memory_status with scope and namespace (expect ok: true and index_status.state: "current").

Connect to your harness

Use ai-memory connect <harness> to write the MCP config for your coding agent.

npx (no clone):

npx -y @palimem/mcp@latest ai-memory connect cursor \
  --project-root "$(pwd)" --launcher npx --data-dir .ai-memory/data

From a cloned repository:

# Claude Code: copy .mcp.json manually (see integration page)
# Cursor:
node app/scripts/ai-memory.js connect cursor \
  --project-root "$(pwd)" --data-dir .ai-memory/data

# Windsurf:
node app/scripts/ai-memory.js connect windsurf \
  --project-root "$(pwd)" --data-dir .ai-memory/data

# Copilot CLI:
node app/scripts/ai-memory.js connect copilot \
  --project-root "$(pwd)" --data-dir .ai-memory/data

# Codex:
node app/scripts/ai-memory.js connect codex \
  --project-root "$(pwd)" --data-dir .ai-memory/data

# VS Code + Copilot Agent / Copilot IDE:
node app/scripts/ai-memory.js connect vscode \
  --project-root "$(pwd)" --data-dir .ai-memory/data

# Gemini CLI:
node app/scripts/ai-memory.js connect gemini \
  --project-root "$(pwd)" --data-dir .ai-memory/data

Add --launcher npx with the npx invocation to write config that runs Palimem without a local clone.

Data directory

Palimem stores all memory in a SQLite database. The default location is .ai-memory/data relative to your project root.

Environment variable	Default	Purpose
`MEMORY_SERVICE_DATA_DIR`	`.ai-memory/data`	Override the data directory path
`MEMORY_SERVICE_NAMESPACE`	workspace folder name	Default namespace for session scope
`MEMORY_SERVICE_PYTHON`	`python3` / `py -3`	Python interpreter for hook CLIs

Using an absolute path (recommended for shared machines):

export MEMORY_SERVICE_DATA_DIR="$HOME/.local/share/palimem/data"

Future rename: The .ai-memory/ prefix will become .palimem/ in a future version. Both names resolve to the same store during the migration window.

Docker image

A Docker image is available for operators who prefer containerised deployment. The image exposes the MCP stdio server via a subprocess entrypoint.

# Informational — package publish pending
docker run --rm -v "$(pwd)/.ai-memory:/data" \
  ghcr.io/palimem/palimem-service:1.7.1 \
  --data-dir /data

See the component spec for Docker deployment details.

Python install (no Node wrapper)

If you prefer to run the Python MCP server directly without the Node wrapper:

python3 app/run_production_stdio_server.py

Point your MCP config at python3 with run_production_stdio_server.py as the argument.

Verify installation

After connecting to your harness, ask your agent to call:

memory_status with scope "repository" and namespace "<project-name>"

Expected: 11 tools from tools/list, and memory_status with ok: true and index_status.state: "current" for your scope and namespace.

Next steps

Choose your harness for full setup instructions: