PLUR Install Instructions for AI Agents
========================================

PLUR is the open standard for AI agent memory. Memory is open, human-readable YAML
(engrams) you can read, edit, and delete — not weights. Open spec, Apache-2.0:
https://plur.ai/spec.html

Step 1 — Detect your platform:
  Run: which openclaw
  If found → you are an OpenClaw agent. Use OPENCLAW INSTALL below.
  Run: python3 -c "import hermes_agent" 2>/dev/null
  If found → you are a Hermes agent. Use HERMES INSTALL below.
  Otherwise → use MCP INSTALL below.

OPENCLAW INSTALL (recommended — fully automatic memory):
  openclaw plugins install @plur-ai/claw
  openclaw gateway --force
  Done. Memory works automatically from the next session.

HERMES INSTALL (Python plugin — auto-hooks into LLM calls):
  pip install plur-hermes
  npm install -g @plur-ai/cli@latest
  Done. Plugin auto-registers via the Hermes plugin system.

MCP INSTALL (Claude Code, Cursor, Windsurf, Codex, OpenCode, other MCP clients):
  Requires Node.js 20 or newer.
  1. Run: npm install -g @plur-ai/cli@latest @plur-ai/mcp@latest
  2. Run: plur init
  3. Run: plur doctor
  4. Restart your editor.

  Claude Code: init registers MCP in ~/.claude.json and hooks in
  ~/.claude/settings.json. A project .mcp.json is a separate configuration.
  Cursor: run plur init --cursor from your project root.
  Codex: after upgrading both CLI and MCP, run plur init --codex, then
  plur doctor --codex. Init repairs older MCP pins and token_env forwarding
  while preserving other settings. Restart Codex; use /hooks to trust PLUR's hooks.
  Token variables must be set in the environment that starts Codex.
  Windows CLI and WSL2 are tested. Actual Windows desktop acceptance remains
  unverified: https://github.com/plur-ai/plur/issues/1625
  Antigravity: run plur init --antigravity.
  Other MCP clients: register the installed plur-mcp executable using the
  host's MCP configuration format, then verify it with plur doctor.

OPENCODE (native plugin for V1 and V2):
  Run: plur init --opencode
  Run: plur doctor
  Restart OpenCode, including its background service on V2. Init adds the
  plugin and installed MCP server to
  ~/.config/opencode/opencode.json, or the existing opencode.jsonc.
  OPENCODE_CONFIG_DIR takes precedence; otherwise XDG_CONFIG_HOME overrides
  the default config directory. PLUR and @plur-ai/opencode both use version
  0.21.5. The plugin supports OpenCode V1 (1.18.0+) and V2 (2.0.23+).
  The older 0.2.1 plugin does not load in V2. If an unpinned cached plugin
  stays on that version, set its plugin entry to @plur-ai/opencode@0.21.5
  and restart OpenCode including its V2 background service.
  Init understands native V2 plugins objects and mcp.servers entries.
  Init updates older exact plugin pins while preserving JSONC comments and
  unrelated settings. Newer pins, tags and unpinned entries are kept.
  Use --keep-opencode-plugin to keep an intentional older pin.

UPGRADE:
  npm install -g @plur-ai/cli@latest @plur-ai/mcp@latest
  plur init
  plur doctor
  Restart the editor to load the updated MCP server and configuration.

SEARCH MODEL:
  plur doctor downloads the search model (~133 MB) when missing and downloads
  are allowed. Search runs locally after that download. Without the model,
  recall uses keyword search; a recall or short-lived editor hook does not
  download the model.

UNIVERSAL CLI (after installing the packages above):
  plur learn "statement"
  plur recall "query"
  plur inject "task description"
  plur status

Default MCP tools (lean profile, 14 tools):
  plur_session_start, plur_session_end, plur_learn, plur_recall,
  plur_feedback, plur_forget, plur_status, plur_receipt, plur_doctor,
  plur_packs_uninstall, plur_tensions_purge, plur_tensions,
  plur_validate_meta, plur_admin.

  plur_recall uses hybrid search by default; use mode:"keyword" for BM25 only.
  Other operations (including batch learning, capture, timeline, ingest, sync,
  pack installation and store management) use plur_admin. Discover their names
  and argument schemas with: { "action": "help" }
  Example: plur_admin { "action": "plur_sync", "args": {} }
  PLUR_TOOL_PROFILE=full exposes the full tool set directly.

Verify: ask your agent "What's my PLUR status?" — it should call plur_status.

Storage: ~/.plur/ (plain YAML files, local, private, human-readable)
Requirements: Node.js 20 or newer for the CLI and MCP server.

For teams: PLUR for Enterprise is self-hosted (VPC / your hardware), with SSO, SCIM,
RBAC, and an audit log. Open core, Apache-2.0, model-agnostic. https://plur.ai/enterprise.html

Docs: https://plur.ai | Spec: https://plur.ai/spec.html | GitHub: https://github.com/plur-ai/plur