Palaia

Local, crash-safe persistent memory for OpenClaw agents. SQLite-backed by default. Semantic search, projects, scopes, auto-capture. After installing or updating, run: palaia doctor --fix to complete setup.

# Palaia v2.4 — Agent Memory Skill

Palaia is the memory system for OpenClaw agents. It gives you persistent, searchable, crash-safe memory across sessions. You don't need to understand how it works — just use the commands below.

<!-- begin:install -->
## First-Time Setup

When a user asks you to "set up palaia", "enable memory", or "remember things across sessions", run these steps:

```bash
pip install "palaia[fastembed]"
```

```bash
palaia init
```

This creates `.palaia/` with SQLite storage and automatically configures fastembed for semantic search. No manual configuration needed.

Confirm success to the user: "Memory is ready. I'll automatically remember important context from our conversations."

If `pip` is not available, try alternatives in this order:
```bash
python3 -m pip install "palaia[fastembed]"
uv tool install "palaia[fastembed]"
pipx install "palaia[fastembed]"
```

Optional extras (install as needed):
```bash
pip install "palaia[mcp]"          # MCP server for Claude Desktop, Cursor
pip install "palaia[curate]"       # Knowledge curation
```

Note: `palaia[fastembed]` already includes sqlite-vec for native SIMD vector search. No separate install needed.

### OpenClaw Plugin Setup (for Auto-Capture and Auto-Recall)

After the CLI is installed, wire it into OpenClaw:

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

Then activate in OpenClaw config (read existing values first, never overwrite arrays):
```bash
PALAIA_PATH="$(npm root -g)/@byte5ai/palaia"
```

Add to `openclaw.json`:
```json
{
  "plugins": {
    "load": { "paths": ["<PALAIA_PATH>"] },
    "allow": ["..existing..", "palaia"],
    "slots": { "memory": "palaia" },
    "entries": { "palaia": { "enabled": true } }
  }
}
```

Restart the gateway and verify:
```bash
openclaw gateway restart
palaia doctor
```

### Agent Identity (optional)

Single-agent systems work with the default name. For multi-agent setups:
```bash
palaia init --agent YOUR_AGENT_NAME
```

## Updating Palaia

When the user asks to update, or when `palaia status` shows a version mismatch:

```bash
palaia upgrade
```
This auto-detects the install method (pip/uv/pipx), preserves all installed extras (fastembed, mcp, sqlite-vec, curate), runs `palaia doctor --fix`, and upgrades the OpenClaw plugin if installed. No manual steps needed.

**If `palaia upgrade` is not recognized** (versions before v2.3.0), update manually:

```bash
# Step 1: Find install method
which palaia

# Step 2: Upgrade (use the method matching the path from Step 1)
# pip (path contains site-packages or .local):
pip install --upgrade "palaia[fastembed]"
# uv (path contains uv):
uv tool install "palaia[fastembed]"
# pipx (path contains pipx):
pipx install "palaia[fastembed]" --force

# Step 3: Health check + migration
palaia doctor --fix

# Step 4: Update OpenClaw plugin (if installed)
npm install -g @byte5ai/palaia@latest
```

After the manual update, `palaia upgrade` will be available for future updates.
<!-- end:install -->

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

Before doing anything else with Palaia, run `palaia doctor` silently. If it reports ANY warnings, address them immediately by following `palaia doctor --fix` recommendations. Do not proceed with other Palaia tasks until doctor reports no issues.

---

## Core Concepts

### Auto-Capture
Conversations are automatically captured when the OpenClaw plugin is active. You do NOT need to manually write things from conversations — Palaia handles it. Manual `palaia write` is only for structured knowledge: processes, tasks, and knowledge from external sources.

### Three Tiers
- **HOT** — Active memories (< 7 days or frequently accessed). Always searched.
- **WARM** — Aging memories (7-30 days). Searched by default.
- **COLD** — Archived memories (> 30 days). Only searched with `--all`.

### Scopes
- **private** — Only the writing agent can read it
- **team** — All agents in the workspace can read it (default)
- **public** — Exportable and shareable across workspaces

### Entry Types
- **memory** — Facts, decisions, learnings (default)
- **process** — Workflows, checklists, SOPs
- **task** — Action items with status, priority, assignee, due date

---

## Storage & Search

### Database Backends

| Backend | Use Case | Vector Search | Install |
|---------|----------|---------------|---------|
| **SQLite** (default) | Local, single-agent or small team | sqlite-vec (native KNN) or Python fallback | Included |
| **PostgreSQL** | Distributed teams, multiple hosts | pgvector (ANN, IVFFlat/HNSW) | `pip install 'palaia[postgres]'` |

SQLite is zero-config — `palaia init` creates a single `palaia.db` file with WAL mode for crash safety. For teams with agents on multiple machines, PostgreSQL centralizes the store:
```bash
palaia config set database_url postgresql://user:pass@host/db
# or: export PALAIA_DATABASE_URL=postgresql://...
```

### Semantic Vector Search

Palaia uses **hybrid search**: BM25 keyword matching (always active) combined with semantic vector embeddings (when a provider is configured). This finds memories by meaning, not just keywords.

**Embedding providers** (checked in chain order, first available wins):

| Provider | Type | Latency | Install |
|----------|------|---------|---------|
| **fastembed** | Local (CPU) | ~10ms/query | `pip install 'palaia[fastembed]'` (default) |
| **sentence-transformers** | Local (CPU/GPU) | ~10ms/query | `pip install 'palaia[sentence-transformers]'` |
| **Ollama** | Local (server) | ~50ms/query | `ollama pull nomic-embed-text` |
| **OpenAI** | API | ~200ms/query | Set `OPENAI_API_KEY` |
| **Gemini** | API | ~200ms/query | Set `GEMINI_API_KEY` |
| **BM25** | Built-in | <1ms/query | Always available (keyword only) |

Configure the chain: `palaia config set embedding_chain '["fastembed", "bm25"]'`

Check what's available: `palaia detect`

### Embed Server (Performance)

For fast CLI queries, palaia runs a background embed-server that keeps the model loaded in memory:
```bash
palaia embed-server --socket --daemon   # Start background server
palaia embed-server --status            # Check if running
palaia embed-server --stop              # Stop server
```
Without the server, each CLI call loads the model fresh (~3-5s). With the embed-server: **~1.5s per CLI query** (Python startup + server call) or **<500ms via MCP/Plugin** (no CLI overhead).

The OpenClaw plugin starts the embed-server automatically. For CLI-only usage, it auto-starts on first query when a local provider (fastembed, sentence-transformers) is configured.

### MCP Server (Claude Desktop, Cursor, any MCP host)

Palaia works as a standalone MCP memory server — **no OpenClaw required**. Any AI tool that supports MCP can use palaia as persistent local memory.

```bash
pip install 'palaia[mcp]'
palaia-mcp                              # Start MCP server (stdio)
palaia-mcp --root /path/to/.palaia      # Explicit store
palaia-mcp --read-only                  # No writes (untrusted hosts)
```

**Claude Desktop** (`~/.config/claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "palaia": {
      "command": "palaia-mcp",
      "args": []
    }
  }
}
```

**Cursor** (Settings → MCP Servers → Add, or `.cursor/mcp.json`):
- Command: `palaia-mcp`
- Arguments: (none, or `--root /path/to/.palaia`)

**Claude Code** (`~/.claude/settings.json`):
```json
{"mcpServers": {"palaia": {"command": "palaia-mcp"}}}
```

**MCP Tools:**

| Tool | Purpose |
|------|---------|
| `palaia_search` | Semantic + keyword search across all memories |
| `palaia_store` | Save new memory (fact, process, task) |
| `palaia_read` | Read a specific entry by ID |
| `palaia_edit` | Update an existing entry |
| `palaia_list` | List entries by tier, type, or project |
| `palaia_status` | Show store health, entry counts, provider info |
| `palaia_gc` | Run garbage collection (tier rotation) |

**Read-only mode** (`--read-only`): Disables `palaia_store`, `palaia_edit`, `palaia_gc`. Use this when connecting