palaia

Local, crash-safe persistent memory for OpenClaw agents. Replaces built-in memory-core with semantic search, projects, and scope-based access control. After installing or updating, run: palaia doctor --fix to complete setup.

# Palaia — Agent Memory Skill

## Auto-Check (run every time this skill is loaded)

**[INSTRUCTION for LLM]:** Before doing anything else with Palaia, run `palaia doctor` silently. If it reports ANY warnings (version mismatch, missing providers, legacy patterns, incomplete setup), address them immediately by following `palaia doctor --fix` recommendations. Do not proceed with other Palaia tasks until doctor reports no issues. This ensures the memory system is always up-to-date and correctly configured.

## Zero-Config: It Just Works

**Palaia works out of the box after installation. No config edits needed.**

After `pip install "palaia[fastembed]"` and activating the OpenClaw plugin, Palaia immediately:
- **Injects relevant memories** into every agent prompt (`memoryInject: true`)
- **Auto-captures significant exchanges** as searchable memories (`autoCapture: true`)
- **Uses semantic recall** to find context-relevant memories (`recallMode: query`)

No settings to tweak. No README to study. Install it and it works.

**For power users:** All defaults can be customized via `openclaw.json` plugin config or `palaia init --capture-level`. See the Configuration section below.

**Upgrading from v1.x?** Run `palaia doctor --fix` — it detects old defaults and upgrades them. Custom values you've set are preserved.

## Communication During Setup

- After each major step, send a brief status message to the user. Don't go silent.
- If a step takes longer than ~10 seconds, say what you're doing: "Installing sentence-transformers, this takes a moment…"
- If something unexpected happens (e.g. CUDA error, provider fails), explain what happened and what you're doing instead — immediately.
- Don't batch all steps and report at the end. Report after each step.

Example pacing:
1. "Installing Palaia…" → [runs pip install] → "Done. Initializing store…" → [runs palaia init] → "Store ready."
2. "Installing OpenClaw plugin…" → [runs npm install -g @byte5ai/palaia@latest] → "Plugin installed. Activating…" → [patches config, restarts gateway] → "Plugin active."
3. "Running diagnostics…" → [runs palaia doctor] → "Found: [X]. Quick question:"
4. [Onboarding conversation — max 3 questions]
5. "Configuring chain… warming up model (this takes ~15 seconds)…" → "Ready."
6. "All set. Here's your setup: [one sentence summary]"

## Setup Flow (follow this exactly)

### Step 1: Install and initialize

**Choose your package manager** (use whichever is available on your system):
```bash
# pip (most common)
python3 -m pip install "palaia[fastembed]"

# uv (if pip is not available)
uv tool install "palaia[fastembed]"

# pipx (alternative)
pipx install "palaia[fastembed]"
```

> **Important (uv users):** Always include the `[fastembed]` extra. `uv tool install palaia` without extras will remove previously installed embedding providers (fastembed, sentence-transformers) on upgrade. This is by design — `uv` strictly manages dependencies. Always use `uv tool install "palaia[fastembed]"` for both install and upgrade.

```bash
palaia init
```

**Agent identity is optional but recommended.** `palaia init` without `--agent` sets the agent name to "default". This works fine for single-agent systems. For multi-agent setups, use `--agent`:
```bash
palaia init --agent YOUR_AGENT_NAME
```

If an OpenClaw config with a single agent is detected, the name is auto-detected:
```
Auto-detected agent: HAL (from OpenClaw config)
```

The agent name is stored in `.palaia/config.json` and automatically attached to all writes and memo operations. No env vars needed.

**Single-Agent to Multi-Agent Migration:**
When adding a second agent later, existing entries keep their original agent name ("default"). To associate old "default" entries with your named agent:
```bash
palaia config set-alias default YOUR_NAME
```
This makes queries for YOUR_NAME also return entries written as "default". No entries are rewritten — aliases are query-time only. `palaia doctor` will remind you if this is needed.

**Optional: Set session instance** (for multi-instance agents):
```bash
palaia instance set YOUR_INSTANCE_NAME
```
Instance is session-local and adds traceability to entries. Memos can target specific instances.

### Step 2: Install and activate OpenClaw plugin (REQUIRED)

The npm plugin wires Palaia into OpenClaw's memory slot — without it, Auto-Capture and Auto-Recall don't work.

```bash
npm install -g @byte5ai/palaia@latest
```

Now activate the plugin in OpenClaw.

**[INSTRUCTION for LLM]:** Do NOT blindly overwrite plugin config arrays with `openclaw config set`.
Arrays like `plugins.allow` and `plugins.load.paths` may already contain other plugins (telegram, slack, clawsy-bridge...).
Overwriting them destroys the existing configuration. Always read first, then append if missing.

**Preferred: Use gateway config.patch (deep-merges, safest)**

If you have access to the gateway tool, use `config.patch` — it deep-merges instead of overwriting:

```
# First, read existing values to avoid duplicates
PALAIA_PATH="$(npm root -g)/@byte5ai/palaia"
existingAllow = gateway(action="config.get", key="plugins.allow")  // e.g. ["telegram","slack"]
existingPaths = gateway(action="config.get", key="plugins.load.paths")  // e.g. ["/path/to/telegram"]

# Then patch (only add palaia if not already present)
gateway(action="config.patch", raw=JSON.stringify({
  plugins: {
    load: { paths: [...existingPaths, palaiaPath] },
    allow: [...existingAllow, "palaia"],
    slots: { memory: "palaia" },
    entries: { palaia: { enabled: true } }
  }
}), note="Palaia plugin activated")
```

**Alternative: Safe shell approach (reads existing config, adds palaia, never overwrites)**

```bash
PALAIA_PATH="$(npm root -g)/@byte5ai/palaia"

# Add to plugins.allow (only if not already present)
CURRENT_ALLOW=$(openclaw config get plugins.allow 2>/dev/null || echo '[]')
if ! echo "$CURRENT_ALLOW" | grep -q '"palaia"'; then
  NEW_ALLOW=$(echo "$CURRENT_ALLOW" | python3 -c "import sys,json; a=json.load(sys.stdin); a.append('palaia'); print(json.dumps(a))")
  openclaw config set plugins.allow "$NEW_ALLOW"
fi

# Add to plugins.load.paths (only if not already present)
CURRENT_PATHS=$(openclaw config get plugins.load.paths 2>/dev/null || echo '[]')
if ! echo "$CURRENT_PATHS" | grep -q "$PALAIA_PATH"; then
  NEW_PATHS=$(echo "$CURRENT_PATHS" | python3 -c "import sys,json,os; a=json.load(sys.stdin); a.append(os.environ['PALAIA_PATH']); print(json.dumps(a))")
  openclaw config set plugins.load.paths "$NEW_PATHS"
fi

# Set memory slot (safe — single value, not array)
openclaw config set plugins.slots.memory palaia
```

> **Typical `npm root -g` paths:**
> - Linux (Homebrew): `/home/linuxbrew/.linuxbrew/lib/node_modules`
> - macOS (Homebrew): `/opt/homebrew/lib/node_modules`
> - macOS (nvm): `~/.nvm/versions/node/vXX/lib/node_modules`
> - Linux (system): `/usr/lib/node_modules`
> - Windows: `%AppData%\npm\node_modules`

Restart the gateway so the plugin loads:
```bash
openclaw gateway restart
```

Wait for the gateway to come back up, then verify:
```bash
palaia doctor
```
The output must include `OpenClaw plugin: palaia is active`. If it does not, re-check the path and config values above.

### Step 3: Check for existing memory systems (REQUIRED — do not skip)
```bash
palaia doctor
```

Review **every** warning before continuing. For each warning found by `palaia doctor`, immediately offer to fix it — do not wait for the user to ask:

**HEARTBEAT.md legacy patterns:**
→ Tell the user: "Your heartbeat still uses old memory patterns. Should I update it to use Palaia? (Takes a moment, no data loss)"
- If yes: update HEARTBEAT.md, replace `memory_search`/`memory_get`/direct file reads with `palaia query`/`palaia write` equivalents
- If no: skip, move to next warning

**Smart-Memory skill detected:**
→ Tell the user: "The old smart-memory skill is still installed. Should I remove it? (Only after confirming Palaia has your memories)"
- If yes: run `palaia migrate <workspace-