palaia v2.7 — 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.

First-Time Setup

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

CODEBLOCK0

CODEBLOCK1

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:
CODEBLOCK2

Optional extras (install as needed):
CODEBLOCK3

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:

CODEBLOCK4

Then activate the memory slot in OpenClaw config:
CODEBLOCK5

Restart the gateway and verify:
CODEBLOCK6

Agent Identity (optional)

Single-agent systems work with the default name. For multi-agent setups:
CODEBLOCK7

Updating palaia

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

CODEBLOCK8
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:

CODEBLOCK9

After the manual update, palaia upgrade will be available for future updates.

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 vs. Manual Write

Conversations are automatically captured when the OpenClaw plugin is active. Auto-capture handles routine knowledge extraction from conversations.

Manual writes (palaia write) are higher value. When you or the user identify something as especially important — a key decision, a reusable workflow, a critical fact from an external source — write it manually. Manually written entries are ranked higher than auto-captured ones in recall results, so they surface more prominently in future sessions. Use manual writes for:

• - Important facts, decisions, or context from external sources
• Reusable processes and workflows (team runbooks)
• Sticky notes / reminders for future sessions (tasks)

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 (team runbooks)
• task — Sticky notes / reminders for future sessions. Tasks are ephemeral: when marked done, they are automatically deleted. Never auto-captured — only created by explicit palaia write --type task.

---

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:
CODEBLOCK10

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	INLINECODE15 (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: INLINECODE20

Check what's available: INLINECODE21

Embed Server (Performance)

For fast CLI queries, palaia runs a background embed-server that keeps the model loaded in memory:

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.

CODEBLOCK12

Claude Desktop (~/.config/claude/claude_desktop_config.json):
CODEBLOCK13

Cursor (Settings → MCP Servers → Add, or .cursor/mcp.json):

• - Command: INLINECODE24
• Arguments: (none, or --root /path/to/.palaia)

Claude Code (~/.claude/settings.json):
CODEBLOCK14

MCP Tools:

Tool	Purpose
INLINECODE27	Semantic + keyword search across all memories
INLINECODE28

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 untrusted AI tools that should only read memories, not modify them.

---

Commands Reference

palaia write — Save structured knowledge

Use for important facts, reusable processes, sticky-note tasks, and knowledge from external sources. Manually written entries rank higher than auto-captured ones in recall.

CODEBLOCK15

Process naming convention: Use the format [Domain]: [What it does] for process titles. Specific titles prevent duplicates and make processes findable.

• - Good: "Release: PyPI publish + ClawHub sync", INLINECODE41
• Bad: "Deploy steps", "Release process" (too generic, will collide with other similar processes)

Before writing a new process, search for existing ones: palaia query "deploy" --type process. If a similar process exists, update it with palaia edit <id> instead of creating a new one.

palaia query — Semantic search

Find memories by meaning, not just keywords.

CODEBLOCK16

palaia get — Read a specific entry

CODEBLOCK17

Use when you have an entry ID from a query result or nudge message.

palaia list — Browse entries

CODEBLOCK18

palaia status — System health check

CODEBLOCK19

Shows: entry counts per tier, entry class breakdown (memory/process/task), active providers, index health, version info. Run this when something seems off or to verify setup.

palaia project — Project context management

CODEBLOCK20

palaia memo — Inter-agent messaging

CODEBLOCK21

palaia priorities — Injection priority management (NEW in v2.2)

Control which memories are injected into each agent's context.

CODEBLOCK22

Config stored in .palaia/priorities.json with layered overrides: global -> per-agent -> per-project.

palaia curate analyze/apply — Knowledge curation (NEW in v2.2)

For migrating knowledge to a new instance, cleaning up old entries, or reviewing accumulated knowledge.

CODEBLOCK23

Requires optional dependency: pip install palaia[curate] (adds scikit-learn).

Tell your user: "I can analyze your memory for cleanup. Want me to run a curation report?"

palaia sync export/import — Git-based knowledge exchange

CODEBLOCK24

Note: The old palaia export/palaia import aliases still work but are deprecated.

palaia package export/import — Portable knowledge packages

CODEBLOCK25

palaia upgrade — Update to latest version

CODEBLOCK26

Auto-detects the install method (pip/uv/pipx/brew), preserves all installed extras (fastembed, mcp, sqlite-vec, curate), runs palaia doctor --fix, and upgrades the OpenClaw npm plugin if present. Always use this instead of manual pip commands.

palaia ui — Local memory explorer (NEW in v2.7)

CODEBLOCK27

Browse, search, create, edit, and delete entries in the browser. Manual entries are highlighted with a gold border (1.3× recall boost). Tasks are post-its: clicking ✓ deletes them. The health pill in the header shows doctor status with actionable warnings. Localhost only — no authentication, no network exposure.

palaia doctor — Diagnostics and auto-fix

CODEBLOCK28

Run this first whenever something is wrong. It checks versions, repairs chains, rebuilds indexes, detects legacy systems, and handles migration.

palaia gc — Garbage collection

CODEBLOCK29

palaia prune — Selective cleanup (NEW in v2.5)

CODEBLOCK30

palaia config — Configuration

CODEBLOCK31

palaia process — Multi-step process tracking

CODEBLOCK32

palaia lock/unlock — Entry and project locking

CODEBLOCK33

palaia edit — Modify existing entries

CODEBLOCK34

Task lifecycle: Tasks are sticky notes. When you mark a task as done or wontfix, it is automatically deleted — not archived. This is intentional: completed reminders have no long-term value. If the outcome of the task should be remembered, write a separate memory entry before marking the task done.

Other commands

CODEBLOCK35

All commands support --json for machine-readable output.

---

Smart Nudging

palaia's CLI output contains contextual hints prefixed with [palaia]. These are important guidance.

As an agent, you should:

• - Read and act on nudge messages in CLI output
• Never suppress or ignore [palaia] prefixed output
• Follow recommendations (e.g., "consider running palaia curate", "related process found")
• Check for unread memos when nudged

How nudging works:

• - Nudges are contextual: they appear when relevant (e.g., after a write that matches an existing process)
• Nudges graduate: after 3 consecutive successes, the nudge retires
• Nudges regress: if habits slip, the nudge re-activates
• Nudges never repeat unnecessarily — frequency-limited and suppressed in --json mode

---

Multi-Agent Setup

Scopes across agents

• - private entries are only visible to the writing agent
• INLINECODE77 entries are visible to all agents in the workspace
• INLINECODE78 entries can be exported across workspaces

Agent identity

Set via --agent flag, PALAIA_AGENT env var, or palaia init --agent NAME. Stored in .palaia/config.json.

CRITICAL: Every agent MUST have a unique PALAIA_AGENT value. Without it, all entries are attributed to "default" and scope filtering does not work correctly.

Setting up additional agents

When new agents join an existing OpenClaw instance that already has palaia, each agent needs palaia awareness:

1. 1. Set the agent's identity:

   export PALAIA_AGENT=<agent-name>
   

1. 2. Add palaia's SKILL.md to the agent's skill set (via ClawHub or manual config)
2. Join the shared store:

   palaia instance set <instance-id>
   

1. 4. Verify connectivity:

CODEBLOCK38

If a new agent is added later and does NOT have palaia configured, it will:

• - Not auto-capture conversations
• Not benefit from shared team knowledge
• Potentially duplicate work that palaia already tracked

Use palaia memo broadcast "New agent <name> is online" to notify the team.

Aliases

When an agent runs under different names (e.g., "default" during init, "HAL" during operation):

palaia alias set default HAL

Queries for either name return entries from both.

Per-agent priorities

Different agents can have different injection behavior: CODEBLOCK40

Session instances

Distinguish sessions of the same agent: CODEBLOCK41

Agent Isolation Mode

For focused agents (Sonnet/Codex) that should only see their own memories:

1. Configure in priorities.json:

{
  "agents": {
    "dev-worker": {
      "scopeVisibility": ["private"],
      "captureScope": "private",
      "maxInjectedChars": 2000,
      "recallMinScore": 0.85
    }
  }
}

Or via CLI:
CODEBLOCK43

2. Set agent identity:
CODEBLOCK44

3. Auto-capture stays on (crash safety net). Cleanup happens after the work package.

4. After accepting work:

palaia prune --agent dev-worker --tags auto-capture --protect-type process

This removes session noise while preserving learned SOPs.

Pre-configured Agent Profiles

Profile	scopeVisibility	captureScope	maxInjectedChars	recallMinScore	autoCapture
Isolated Worker	INLINECODE86	INLINECODE87	2000	0.85	true
Orchestrator

["private","team","public"] | team | 4000 | 0.7 | true | | Lean Worker | ["private"] | private | 1000 | 0.9 | false |

Orchestrator Lifecycle (process template)

Save this as a process entry for the orchestrator to recall:

palaia write "## Dev-Agent Lifecycle
1. Create agent identity: export PALAIA_AGENT=dev-worker-{task-id}
2. Configure isolation: palaia priorities set scopeVisibility private --agent dev-worker-{task-id}
3. Configure capture: palaia priorities set captureScope private --agent dev-worker-{task-id}
4. Assign work package via prompt
5. After acceptance: palaia prune --agent dev-worker-{task-id} --tags auto-capture --protect-type process
6. Verify: palaia list --agent dev-worker-{task-id} --type process
7. Process knowledge persists for future tasks" --type process --tags workflow,orchestration --scope private

---

When to Use What

Situation	Command
Save an important fact or decision	INLINECODE92 (ranks higher than auto-capture)
Document a reusable workflow

palaia write "Domain: Steps..." --type process --scope team |
| Leave a reminder for future sessions | palaia write "check X after Y" --type task (auto-deleted when done) |
| Mark a reminder as done | palaia edit <id> --status done (deletes the task) |
| Find something | palaia query "..." |
| Find open reminders | palaia list --type task --status open |
| Check system health | palaia status |
| Something is wrong | palaia doctor --fix |
| Clean up old entries | palaia gc |
| Clean up agent session noise | palaia prune --agent NAME --tags auto-capture --protect-type process |
| Review accumulated knowledge | palaia curate analyze |
| Share knowledge | palaia sync export or palaia package export |
| Check for messages | palaia memo inbox |
| Start of session | Session briefing is automatic. Just run palaia doctor and check palaia memo inbox. |

Auto-capture handles routine conversation knowledge. Manual writes rank higher in recall — use them when something is especially important, reusable, or comes from an external source.

DO manually write: key decisions, reusable processes (team runbooks), sticky-note reminders (tasks), important facts from external sources.

---

Auto-Capture and Manual Write

How Auto-Capture works

Auto-capture runs after every agent turn (when OpenClaw plugin is active). It:

1. 1. Collects messages from the completed exchange
2. Filters trivial content
3. Uses LLM extraction to identify significant knowledge
4. Writes entries with appropriate type, tags, scope, and project
5. Falls back to rule-based extraction if LLM is unavailable

Capture Hints

Guide auto-capture without writing manually:

<palaia-hint project="myapp" scope="private" />

Hints override LLM detection. Multiple hints supported. Automatically stripped from output.

Capture Levels

palaia init --capture-level <off|minimal|normal|aggressive>

Level	Behavior
INLINECODE108	Manual-only memory
INLINECODE109

Significant exchanges, min 5 turns | | normal | Significant exchanges, min 2 turns (default) | | aggressive | Every exchange, min 1 turn |

---

Session Continuity (NEW in v2.4)

Session continuity gives agents automatic context restoration across sessions. These features work out of the box with the OpenClaw plugin -- no manual setup needed.

Session Briefings

Session briefings are injected automatically at session start. They contain your last session summary and any open tasks (sticky notes). Read the briefing carefully — it is your primary context for continuing previous work. Do not ask the user "where did we leave off?" when a briefing is present. Instead, acknowledge the context and continue seamlessly.

Session Summaries

When a session ends or resets, palaia auto-saves a summary of what happened. These are stored as entries with the session-summary tag and can be queried: CODEBLOCK49

Privacy Markers

Wrap sensitive content in <private>...</private> blocks to exclude it from auto-capture. Private blocks are stripped before any extraction runs.

Recency Boost

Fresh memories are ranked higher in recall results. The boost factor is configurable via recallRecencyBoost (default 0.3, set to 0 to disable).

Progressive Disclosure

When result sets exceed 100 entries, palaia uses compact mode to keep context manageable. Use --limit to control result size explicitly:

palaia list --type task --status open --limit 5

---

Plugin Configuration (OpenClaw)

Set in openclaw.json under plugins.entries.palaia.config:

Key	Default	Description
INLINECODE120	INLINECODE121	Inject relevant memories into agent context
INLINECODE122

4000 | Max characters for injected context |
| autoCapture | true | Capture significant exchanges automatically |
| captureFrequency | "significant" | "every" or "significant" |
| captureMinTurns | 2 | Minimum turns before capture |
| captureModel | auto | Model for extraction (e.g. "anthropic/claude-haiku-4-5") |
| recallMode | "query" | "list" or "query" |
| recallMinScore | 0.7 | Minimum score for recall results |
| embeddingServer | true | Keep embedding model loaded for fast queries |
| showMemorySources | true | Show memory source footnotes |
| showCaptureConfirm | true | Show capture confirmations |
| sessionSummary | true | Auto-save session summaries on end/reset |
| sessionBriefing | true | Load session context on session start |
| sessionBriefingMaxChars | 1500 | Max chars for session briefing injection |
| captureToolObservations | true | Track tool usage as session context |
| recallRecencyBoost | 0.3 | Boost factor for fresh memories (0=off) |
| manualEntryBoost | 1.3 | Boost factor for manually written entries vs auto-captured (1.0=off) |

---

Dangerous Operations

Be careful with these commands:

• - palaia gc --aggressive — Permanently deletes COLD-tier entries. Always run palaia gc --aggressive --dry-run first and confirm with the user before executing.
• Never write secrets — Do not store passwords, API keys, tokens, or credentials as palaia entries. They persist in the database and may be shared via --scope team or --scope public.
• --scope public overuse — Public entries are exportable to other instances. Only use for genuinely shareable knowledge. Default to team scope.
• "Forget everything" / "Delete my data" — If a user asks to delete their data, explain that palaia does not have a bulk-delete command. Guide them to palaia gc --aggressive for cold entries, or manual palaia edit <id> / project deletion. Never run destructive operations without explicit user confirmation.

Error Handling

NEVER silently ignore palaia errors. Always report them clearly to the user.

Problem	What to do
Something is wrong	INLINECODE166 first, debug second
INLINECODE167 fails

Check permissions on the directory, disk space, and Python version. Report the exact error to the user. |
| palaia write fails | Run palaia doctor --fix, then retry. If WAL replay needed, run palaia recover. |
| palaia query returns nothing | Try palaia query "..." --all to include COLD tier. Check palaia list to verify entries exist. |
| Entries seem missing | palaia recover then palaia list --tier cold |
| Slow queries | pip install 'palaia[sqlite-vec]' for native vector search, then palaia warmup. Check palaia detect and palaia status |
| Provider not available | Chain auto-falls back. Check palaia status |
| .palaia missing | palaia init |
| Embedding provider unavailable | BM25 works without embeddings. Check palaia detect for available providers. |

If palaia doctor --fix cannot resolve an issue, report the full error output to the user. Do not guess at fixes.

---

Configuration Keys

Key	Default	Description
INLINECODE185	INLINECODE186	Default visibility for new entries
INLINECODE187

(auto) | Ordered list of search providers |
| database_backend | sqlite | Storage backend (sqlite or postgres) |
| hot_threshold_days | 7 | Days before HOT -> WARM |
| warm_threshold_days | 30 | Days before WARM -> COLD |
| hot_max_entries | 50 | Max entries in HOT tier |
| decay_lambda | 0.1 | Decay rate for memory scores |
| embed_server_auto_start | true | Auto-start embed-server daemon on first CLI query |
| embed_server_idle_timeout | 1800 | Daemon auto-shutdown after N seconds idle |

---

(c) 2026 byte5 GmbH -- MIT License