palaia

Palaia 智能体记忆技能，安装后零配置即可自动注入相关记忆、捕获重要对话并语义召回；包含 pip 安装、OpenClaw 插件激活、诊断修复与 onboarding 引导流程。

## 概述（中文）

Palaia 智能体记忆技能，安装后零配置即可自动注入相关记忆、捕获重要对话并语义召回；包含 pip 安装、OpenClaw 插件激活、诊断修复与 onboarding 引导流程。

## 技能正文

# Palaia — 智能体记忆技能

## 自动检查（每次加载本技能时运行）

**[给 LLM 的指令]：** 在使用 Palaia 做任何其他事情之前，先静默运行 `palaia doctor`。若报告任何警告（版本不匹配、缺少 provider、遗留模式、配置不完整），请立即按 `palaia doctor --fix` 的建议处理。在 doctor 报告无问题之前，不要继续其他 Palaia 任务。这可确保记忆系统始终是最新且配置正确的。

## 零配置：开箱即用

**安装后 Palaia 即可直接使用，无需修改配置。**

在 `pip install "palaia[fastembed]"` 并激活 OpenClaw 插件后，Palaia 会立即：
- **注入相关记忆**到每次智能体提示中（`memoryInject: true`）
- **自动捕获重要对话**为可搜索记忆（`autoCapture: true`）
- **使用语义召回**查找与上下文相关的记忆（`recallMode: query`）

无需调整设置，无需研读 README。安装即可使用。

**进阶用户：** 所有默认值可通过 `openclaw.json` 插件配置或 `palaia init --capture-level` 自定义。见下方配置章节。

**从 v1.x 升级？** 运行 `palaia doctor --fix` — 它会检测旧默认值并升级。你已设置的自定义值会保留。

## 设置过程中的沟通

- 每个主要步骤完成后，向用户发送简短状态消息。不要长时间无反馈。
- 若某步骤超过约 10 秒，说明正在做什么："正在安装 sentence-transformers，请稍候…"
- 若出现意外情况（如 CUDA 错误、provider 失败），立即解释发生了什么以及你接下来要做什么。
- 不要等所有步骤做完再一次性汇报。每步完成后都要汇报。

示例节奏：
1. "正在安装 Palaia…" → [运行 pip install] → "完成。正在初始化存储…" → [运行 palaia init] → "存储就绪。"
2. "正在安装 OpenClaw 插件…" → [运行 npm install -g @byte5ai/palaia@latest] → "插件已安装。正在激活…" → [修改配置、重启 gateway] → "插件已激活。"
3. "正在运行诊断…" → [运行 palaia doctor] → "发现：[X]。快速确认："
4. [Onboarding 对话 — 最多 3 个问题]
5. "正在配置 chain… 预热模型（约需 15 秒）…" → "就绪。"
6. "全部完成。你的配置如下：[一句话摘要]"

## 设置流程（严格按此执行）

### 步骤 1：安装与初始化

**选择包管理器**（使用系统上可用的任一方式）：
```bash
# pip（最常见）
python3 -m pip install "palaia[fastembed]"

# uv（若 pip 不可用）
uv tool install "palaia[fastembed]"

# pipx（备选）
pipx install "palaia[fastembed]"
```

> **重要（uv 用户）：** 务必包含 `[fastembed]` extra。`uv tool install palaia` 不带 extra 会在升级时移除已安装的 embedding provider（fastembed、sentence-transformers）。这是设计行为 — `uv` 严格管理依赖。安装与升级请始终使用 `uv tool install "palaia[fastembed]"`。

```bash
palaia init
```

**智能体身份可选但建议设置。** 不带 `--agent` 的 `palaia init` 会将智能体名设为 "default"。单智能体系统这样即可。多智能体请使用 `--agent`：
```bash
palaia init --agent YOUR_AGENT_NAME
```

若检测到仅含单个智能体的 OpenClaw 配置，会自动检测名称：
```
Auto-detected agent: HAL (from OpenClaw config)
```

智能体名保存在 `.palaia/config.json`，并自动附加到所有写入与 memo 操作。无需环境变量。

**单智能体到多智能体迁移：**
后续添加第二个智能体时，已有条目仍保留原智能体名（"default"）。若要将旧 "default" 条目关联到你的命名智能体：
```bash
palaia config set-alias default YOUR_NAME
```
这样查询 YOUR_NAME 时也会返回以 "default" 写入的条目。不会重写条目 — 别名仅在查询时生效。`palaia doctor` 会在需要时提醒你。

**可选：设置 session 实例**（用于多实例智能体）：
```bash
palaia instance set YOUR_INSTANCE_NAME
```
实例是会话本地的，为条目增加可追溯性。Memo 可针对特定实例。

### 步骤 2：安装并激活 OpenClaw 插件（必需）

npm 插件将 Palaia 接入 OpenClaw 的 memory 槽位 — 没有它，Auto-Capture 与 Auto-Recall 无法工作。

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

现在在 OpenClaw 中激活插件。

**[给 LLM 的指令]：** 不要用 `openclaw config set` 盲目覆盖插件配置数组。
`plugins.allow` 与 `plugins.load.paths` 等数组可能已包含其他插件（telegram、slack、clawsy-bridge…）。
覆盖它们会破坏现有配置。务必先读取，缺失时再追加。

**首选：使用 gateway config.patch（深度合并，最安全）**

若可访问 gateway 工具，使用 `config.patch` — 它会深度合并而非覆盖：

```
# 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")
```

**备选：安全的 shell 方式（读取现有配置、添加 palaia、从不覆盖）**

```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
```

> **典型的 `npm root -g` 路径：**
> - 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`

重启 gateway 以加载插件：
```bash
openclaw gateway restart
```

等待 gateway 恢复后验证：
```bash
palaia doctor
```
输出必须包含 `OpenClaw plugin: palaia is active`。若没有，请重新检查上述路径与配置值。

### 步骤 3：检查现有记忆系统（必需 — 不可跳过）
```bash
palaia doctor
```

继续前请审查**每一条**警告。对 `palaia doctor` 发现的每条警告，立即提供修复 — 不要等用户询问：

**HEARTBEAT.md 遗留模式：**
→ 告诉用户："你的 heartbeat 仍在使用旧记忆模式。要更新为 Palaia 吗？（稍等片刻，无数据丢失）"
- 若同意：更新 HEARTBEAT.md，将 `memory_search`/`memory_get`/直接读文件替换为 `palaia query`/`palaia write` 等价操作
- 若否：跳过，处理下一条警告

**检测到 Smart-Memory 技能：**
→ 告诉用户："旧 smart-memory 技能仍已安装。要移除吗？（仅在确认 Palaia 已有你的记忆之后）"
- 若同意：运行 `palaia migrate <workspace-path>`，然后删除 smart-memory 技能文件夹
- 若否：继续，但两套系统会并行运行（不推荐）

**OpenClaw 插件仍为 memory-core：**
→ 告诉用户："Palaia 尚未接入 OpenClaw 记忆系统。要切换吗？（需快速重启 OpenClaw）"
- 若同意：更新 OpenClaw 配置（`plugins.slots.memory = "palaia"`），重启 OpenClaw
- 若否：Palaia 独立运行（无 `memory_search`/`memory_get` 工具集成）

**仅 openai 的 chain（无本地回退）：**
→ 告诉用户："你的搜索没有本地备份。要安装 fastembed 作为回退吗？（小下载，无需 GPU）"
- 若同意：`pip install fastembed`，然后 `palaia warmup`，更新 chain 在 bm25 前加入 fastembed
- 若否：跳过（警告："OpenAI 不可用时搜索可能降级"）

规则：
- 每条警告：立即询问，一次一个问题
- 不要批量提问 — 按顺序处理
- 不要等用户发现并询问
- 用户回答 yes/no 后，处理下一条警告
- 所有警告解决后汇报

**在所有警告已处理或被用户明确忽略之前，不要继续。**

### Onboarding 对话

运行 `palaia doctor` 并审查警告后，与用户简短对话。
保持简短 — 最多 3 个问题。除非用户询问，不要讲技术细节。

**脚本：**

告诉用户：
"我已为你设置好 Palaia — 你的记忆现在防崩溃且可搜索。
快速设置：3 个简短问题。"

**问题 1 — 搜索质量：**

若存在 OpenAI API key 且也检测到本地模型（sentence-transformers/fastembed/ollama）：
  → 直接确认："我会用你的 OpenAI key 配合本地备份模型。配置很好。"
  → 无需提问。

若存在 OpenAI API key 但未安装本地模型：
  → 告诉用户："你有 OpenAI API key — 搜索质量很好。但没有本地备份时，OpenAI 不可用会导致搜索质量明显下降。建议安装小型本地模型（300MB，免费，可离线运行）。要安装吗？"
  → 同意：pip install sentence-transformers（若 CUDA 问题：改用 pip install fastembed — 更轻、无需 GPU），然后 palaia warmup，chain = openai → sentence-transformers → bm25
  → 否：chain = openai → bm25（警告："注意：无本地回退时搜索可能失败或降级。"）

若无 OpenAI key 且无本地模型：
  → 告诉用户："尚未找到搜索 provider。建议安装免费本地模型（300MB）。要安装吗？"
  → 同意：pip install sentence-transformers（若 CUDA 问题：改用 pip install fastembed — 更轻、无需 GPU），然后 palaia warmup，chain = sentence-transformers → bm25
  → 否：仅 BM25（警告："搜索将基于关键词 — 之后可用 palaia detect 改进。"）

若无 OpenAI key 但检测到本地模型：
  → 直接确认："使用本地搜索模型 — 可离线，无 API 费用。"
  → 无需提问。

**问题 2 — 现有记忆（仅当存在遗留记忆文件或检测到 smart-memory 时询问）：**
  问："你有现有记忆。要导入 Palaia 吗？"
  → 同意：运行 palaia migrate <workspace-path>
  → 否：全新开始（现有文件不动）

**问题 3 — 项目（仅当检测到多个项目文件夹或超过 1 个智能体时询问）：**
  问："你是否在多个项目上工作？我可以分开保存各项目记忆。"
  → 同意：简要说明："每个项目用 'palaia project create <name>'。我会记住哪些记忆属于哪里。"
  → 否：跳过

**问题 4 — 捕获模型（仅当 autoCapture 启用时询问，默认为启用）：**
  问："Auto-Capture 会自动保存重要对话。提取应使用哪个模型？便宜/快速的模型最佳（如 claude-haiku-4-5、gpt-4.1-mini、gemini-2.0-flash）。"
  → 用户指定模型：在 openclaw.json 插件配置中设置 `captureModel`
  → 用户说 "use default" 或跳过：不设置（将使用主模型，doctor 会提醒）

**收尾：**
用一句话告诉用户已配置内容：
"完成。[搜索质量：OpenAI / 本地模型 / 仅关键词]。[迁移：导入 X 条 / 全新开始]。[项目：已配置 / 未使用]。"

除非用户明确询问，不要解释命令、WAL、BM25、embedding 模型或任何技术细节。

### 步骤 4：迁移现有条目（最佳实践 — 现在执行）
若有来自早期 Palaia 版本（或初始设置）的现有条目，运行：
```bash
palaia migrate --suggest
```
这会检查无类型分类的条目并建议改进。存储尚小时尽早做更好 — 存储越大越难。应用合理的建议。

### 步骤 5a：检查 embedding 设置（init 自动配置）
```bash
palaia detect
```
查看检测到的 provider 与配置的 chain。`palaia init` 会自动检测可用 provider 并配置最佳 embedding chain — 通常无需改动。

若 chain 不对或想更改：
```bash
palaia config set-chain <provider1> [provider2] bm25
```

若仅显示 BM25 且想要语义搜索：
```bash
# fastembed — 轻量，无需 G