CLI commands

@plur-ai/cli is the universal bridge. Every other adapter delegates to the same engine, so anything you can do in MCP or OpenClaw you can do from the shell. Current verified release: @plur-ai/cli@0.13.0.

This page walks each command in depth — not just signatures, but when you’d reach for it and what to expect when it works.

Install

npm install -g @plur-ai/cli@0.13.0
# or, without installing:
npx @plur-ai/cli@0.13.0 <command>

The global install is recommended for daily use — npx re-resolves every invocation, costing ~300 ms each time.

Global flags

These apply to every command:

Flag	Effect
--json	Machine-readable output (auto-detected when piped).
--path <dir>	Override the storage path (default ~/.plur, or $PLUR_PATH). Exception: for plur import, --path is the input file and --store overrides storage.
--fast	BM25-only search — skip embeddings. Affects recall and inject.
--quiet	Suppress non-essential output.
--version / --help	Print version / usage.

plur init

Bootstrap PLUR on this machine. Installs Claude Code hooks AND registers the plur MCP server. Idempotent — safe to re-run to repair a half-installed setup, and worth re-running after upgrading (it strips and reinstalls its own hooks).

plur init                                            # project-level .claude/settings.json
plur init --global                                   # force global ~/.claude/settings.json
plur init --domain myapp --scope project:my-app      # also writes .plur.yaml
plur init --cursor                                   # also set up Cursor (v0.13.0)

What it does

1. Registers the plur MCP server and lifecycle hooks in .claude/settings.json (project, the default) or ~/.claude/settings.json (--global).
2. Installs a local hook shim at ~/.plur/bin/plur-hook that calls the resolved CLI entrypoint directly — avoids npx cold-start cost and version-bump races.
3. Registers PLUR in the Claude Desktop config unless --no-desktop.
4. With --scope and/or --domain, writes .plur.yaml in the current directory so sessions started here default to that scope.
5. Cursor setup (v0.13.0, experimental): with --cursor — or automatically when a .cursor/ directory exists (silence with --no-cursor) — writes .cursor/mcp.json with PLUR_TOOL_PROFILE=cursor (the reduced ~11-tool profile), .cursor/hooks.json wiring the four Cursor lifecycle hooks, and a static .cursor/rules/plur-memory.mdc rule. The dynamic rules files (plur-context.mdc, plur-reminder.mdc) are gitignored because they’re rewritten each session with recalled engram content.

Flags

Flag	Effect
--global / --project	Force global or project-level .claude/settings.json (default: project).
--no-desktop	Skip Claude Desktop config registration.
--domain <name>	Default domain for engrams captured in this directory (.plur.yaml).
--scope <s>	Default scope, e.g. project:my-app (.plur.yaml).
--cursor / --no-cursor	Force / skip Cursor setup (auto-detected via .cursor/).

Gotchas

• If ~/.plur/ exists but behaves oddly, plur doctor is the right tool — init doesn’t repair storage.
• Since 0.11.0 the prompt-time injection hook installs async with a 90s ceiling — re-run plur init after upgrading from an older version to migrate a sync-hook install that was timing out on large stores.

plur init-remote

Opt this project into recall from a PLUR Enterprise server. Writes remote_url / remote_token (and optional remote_scopes) into .plur.yaml so the prompt-time hook queries Enterprise for this project. Projects without this stay 100% local — Enterprise never sees their prompts.

plur init-remote --url https://plur.example.com --token plur_sk_...
plur init-remote --url https://plur.example.com --token plur_sk_... \
  --scopes "org:acme,group:acme/engineering"
plur init-remote --verify        # connectivity check against existing config

Flags

Flag	Effect
--url <url>	Enterprise base URL.
--token <key>	API key. Tested against /api/v1/me before writing — a bad token never produces a silently-broken config.
--scopes <list>	Optional comma-separated scope whitelist. Without it the hook queries all readable scopes.
--no-gitignore	Skip adding .plur.yaml to .gitignore. Not recommended — the file holds the token in plaintext.
--verify	Read the nearest .plur.yaml (walking upward, bounded by .git) and test connectivity. Exits 2 on failure.

Token sensitivity: .gitignore protects against commits but not cloud-synced folders, cp -r, zip, or backups. Treat .plur.yaml as a credential file.

plur learn

Save an engram. The most-used write command.

plur learn "Always validate user input at API boundaries"
plur learn "Deploys must run migrations first." \
  --type procedural \
  --domain software.deployment \
  --scope group:platform
echo "..." | plur learn          # stdin

The CLI prints the new engram’s ID, type, and resolved scope. Save the ID if you want to give feedback or forget it later.

When to reach for it

Most of the time you don’t run plur learn by hand — the adapter hooks capture corrections. Hand-run it when:

• You’re seeding a fresh PLUR install with conventions from a colleague’s brain dump.
• You’re scripting bulk writes (pipe statements through stdin).
• You’re intentionally superseding an old rule: --supersedes ENG-... links the replacement so tension scans don’t flag it as a contradiction.

Flags

Flag	Default	Notes
--type	behavioral	behavioral / terminological / procedural / architectural.
--domain	none	Topic tag, e.g. software.git. Boosts ranking on related queries.
--scope	auto-routed	Without --scope, the engram flows through unscoped routing (auto-route on a confident covers match, else the default, global). With it, the scope is honored as-is — including remote team scopes.
--tags a,b,c	none	Comma-separated keywords. Each one is a BM25 token.
--rationale	none	The “why” — enters the search corpus too.
--source	none	Origin attribution (URL, conversation ref).
--supersedes id1,id2	none	Engram IDs this statement intentionally replaces.
--visibility	none	private / public / template — gates pack export.
--abstract, --derived-from, --knowledge-anchors <json>, --dual-coding <json>	none	Advanced schema fields, mainly used by the Hermes bridge. Malformed JSON fails loudly.

Gotchas

• A self-contained statement embeds better. “Always validate input at API boundaries” beats “Always do that.”
• Writes to a remote team scope block on the network (5s timeout). On timeout or failure the engram is queued in the outbox and retried on the next sync/session start.
• Sensitive content (secrets, keys) aimed at a shared scope is demoted to a private scope with a warning — re-scope deliberately if it’s a false positive.

plur recall

Search engrams. Hybrid by default — BM25 + local embeddings + Reciprocal Rank Fusion. Add the global --fast flag for BM25-only (instant, no embedder).

plur recall "deploy migrations"
plur recall "how do we handle auth" --limit 5 --json
plur recall "auth" --fast              # BM25 only, sub-100ms

The embeddings half means queries that don’t share keywords with the engram statement still find it: “how do we deploy?” matches an engram that says “always run migrations before rolling pods.”

Flags

Flag	Default	Notes
--limit <n>	10	Number of results.
--fast	off	Global flag — skip embeddings, BM25 only.

Gotchas

• First-ever hybrid call downloads the embedder (bge-small-en-v1.5, ~50 MB). Allow a few seconds.
• Exits with code 2 when no results match — script-friendly.
• There is no separate recall-hybrid command: hybrid IS the default; --fast is the opt-out.

plur inject

Get the relevant engrams for a task — what an agent’s session-start hook would pre-load.

plur inject "fix the auth bug in the login flow"
plur inject "add POST /users endpoint" --json
plur inject "deploy frontend" --budget 1000

inject differs from recall: recall returns engrams by relevance to a query string; inject returns a budget-aware selection formatted as ## DIRECTIVES / ## CONSTRAINTS / ## ALSO CONSIDER blocks ready to prepend to a system prompt.

Flags

Flag	Default	Notes
--budget <n>	2000	Token budget across the result.
--no-with-default-protocol	off	By default, inject appends a “Learning Protocol” block instructing the agent to record learnings (and use plur_learn with supersedes for corrections). Opt out for consumers without PLUR MCP tooling.
--fast	off	Global flag — BM25-only selection.

plur list

Enumerate engrams. A read-only inventory tool — useful for audits, migrations, and curating packs.

plur list
plur list --scope project:my-app
plur list --type behavioral --domain plur.brand
plur list --meta --json

Flags

Flag	Default	Notes
--scope, --domain, --type	none	Filters. Combine freely.
--limit <n>	none	Cap the output.
--meta	off	Only meta-engrams (IDs starting META-).

plur forget

Retire an engram. History is preserved — the engram moves to retired and is excluded from injection, but stays on disk for audit.

plur forget ENG-2026-0525-001
plur forget "outdated rule" --reason "superseded by ENG-2026-0530-002"

Arguments that look like an ID (ENG-, ABS-, META- prefix) are retired directly. Anything else is treated as a search: a single match is retired, multiple matches are listed so you can pick the exact ID.

Flags

Flag	Notes
--search	Force search mode even for ID-shaped input.
--reason <r>	Free text. Stored for audit.

plur feedback

Rate an engram. The signal that trains recall.

plur feedback ENG-2026-0329-001 positive
plur feedback ENG-2026-0329-001 negative
plur feedback --batch '[{"id":"ENG-1","signal":"positive"},{"id":"ENG-2","signal":"neutral"}]'

Signals are positive, negative, or neutral. Feedback adjusts activation — positive strengthens future recall, negative weakens it.

When to reach for it

• The engram was injected and visibly used well → positive.
• The engram was injected and was completely off-topic → negative.
• Adapter hooks emit implicit feedback automatically; reserve manual calls for the unambiguous cases.

plur capture

Record an episode — a timestamped event you want in the timeline.

plur capture "Deploy succeeded after migration fix"
plur capture "Decided to merge PR #42" --agent gregor
echo "summary from a script" | plur capture

Episodes differ from engrams: episodes are history (what happened when), engrams are knowledge (what’s always true).

Flags

Flag	Notes
--agent <name>	Who emitted it. Default cli.
--session <id>	Group episodes under one session.

plur timeline

Query the episode history.

plur timeline
plur timeline "deploy" --limit 10

Takes an optional full-text query over episode summaries and a --limit (default 20). For richer filtering (by agent, channel, date range), use the plur_timeline MCP tool.

plur status

Quick health check.

plur status
plur status --json | jq .

Output covers: engram count, episode count, pack count, injection-provenance event counts, and the storage root. For embedder and search-stack health, use plur doctor — status reports counts, not diagnostics.

plur doctor

Diagnose the integration — Claude Code, Claude Desktop, and (v0.13.0) Cursor wiring.

plur doctor
plur doctor --no-handshake     # skip the live MCP handshake probe

Doctor checks MCP registration, hook installation, the ~/.plur/bin shim, storage, the embedder (probed in an isolated subprocess so a native crash can’t take doctor down), and Cursor-specific wiring (.cursor/mcp.json, .cursor/hooks.json, tool-profile env, and the live MCP tool count — it will tell you if Cursor is loading the full 39-tool surface instead of the reduced profile). Each red line includes the fix command.

Note the split: the CLI’s plur doctor diagnoses wiring; the MCP tool plur_doctor diagnoses the engine (embedder, hybrid search, reranker, remote-store auth). Run doctor before opening an issue.

plur sync

Cross-machine sync via git.

plur sync git@github.com:you/plur-memory.git    # first time — sets the remote
plur sync                                        # routine pull + push
plur sync --full                                 # drop and rebuild the derived index from YAML

sync is git underneath — ~/.plur/ is a git repo with engrams as YAML files. YAML is the source of truth; --full is the recovery path when the derived index (used by search) looks out of sync with what list and recall report — after an embedder upgrade, a schema migration, or index corruption. Sync warns if an index rebuild failed rather than reporting a false “ok”.

Use a private remote — sync pushes visibility: private engrams too (they’re private to packs, not to your own devices). scope: local engrams never leave the machine.

See Sync across machines for the conceptual walkthrough.

plur packs

Knowledge Pack lifecycle — list, preview, install, uninstall, export.

plur packs list
plur packs preview ./my-pack
plur packs install ./my-pack
plur packs uninstall my-pack
plur packs export react-patterns --domain react --description "React conventions"

preview

Lists a pack’s engrams, security scan results, and warnings without installing. Always preview before installing from an untrusted source. (inspect is an alias.)

install

Takes a local pack directory. Verifies integrity, runs a security scan, and reports conflicts (duplicates or contradictions with existing engrams) — the pack still installs, and the output tells you how to resolve conflicts with plur forget.

uninstall

Removes the pack and its engrams. (remove is an alias.)

export

Bundles engrams matching the filters into ~/plur-packs/<name> (or --output <dir>) with a manifest and integrity hash. Secret-containing and private-visibility engrams are excluded and reported.

Flag	Notes
--domain <d> / --scope <s> / --tags t1,t2 / --type <t>	Thematic filters.
--description <text> / --creator <name>	Manifest metadata.
--output <dir>	Default ~/plur-packs/<name>.

See Building a Knowledge Pack.

plur stores

Additional engram stores — extra local store files, or remote scopes on a PLUR Enterprise server.

plur stores list
plur stores add ~/team/engineering.yaml group:acme/engineering --shared
plur stores add ./readonly-pack.yaml pack:vendor --readonly
plur stores discover                 # what scopes is my token authorized for?
plur stores discover --register      # register all of them in one step

Subcommands

Subcommand	Notes
list	All configured stores with scope, path, and engram count.
add <path> <scope> [--shared] [--readonly]	Register a store file under a scope. A local store is keyed by its path — adding a second scope to the same path is a no-op and says so.
discover [--register]	Query configured remote stores’ /api/v1/me for authorized scopes; --register adds the unregistered ones (shared-family scopes only).

For connecting a project to an Enterprise server (remote recall at prompt time), use plur init-remote — that’s the opt-in path. See Migrating local → Enterprise.

plur ingest

Extract engrams from text. Pattern-based extraction — no LLM required.

plur ingest "We decided to always use Caddy for TLS termination."
cat meeting-notes.md | plur ingest --domain backend
plur ingest --extract-only < transcript.txt      # preview without saving

Takes content as a positional argument or stdin — not a file path. To import structured memory exports from other systems, use plur import instead.

Flags

Flag	Notes
--source <s>	Attribution stored on extracted engrams.
--scope <s> / --domain <d>	Applied to extracted engrams.
--extract-only	Print candidates without saving. Without it, extraction saves directly.

plur import

Migrate memories from another system into the engram format.

plur import --from mem0 --path ./mem0-export.json --dry-run
plur import --from gp-engram --path ./memory.db --scope project:my-app
plur import --from generic --path ./memories.jsonl --mapping ./mapping.json

Sources: generic (JSON / JSONL / CSV with an optional field-mapping config), gp-engram (SQLite .db), mem0 (JSON export). All imports route through the same path as plur learn, so content-hash dedup and the secret guard apply — never a raw append. The report lists imported / skipped / conflict / error counts; potential contradictions point you at plur tensions --scan.

Flags

Flag	Notes
--from <source>	generic | gp-engram | mem0.
--path <file>	The input file. (For this command only, --path is the input; use --store to override storage.)
--dry-run	Analyze and print the migration report without writing.
--scope <s>	Force all imported engrams into one scope.
--mapping <file.json>	Field mapping for --from generic: {"fields": {...}, "defaults": {...}}.
--store <dir>	Override the PLUR storage directory (default $PLUR_PATH or ~/.plur).

plur promote

plur promote ENG-2026-0525-001

Moves a candidate engram to active (with reset activation) so it appears in injection results. Useful after plur ingest --extract-only review workflows. One ID at a time; retired engrams can’t be promoted.

plur similarity-search

Search by cosine similarity, with scores.

plur similarity-search "validate input at boundaries" --limit 5

Unlike recall, this returns the raw embedding cosine score per result — the dedup lens: > 0.9 duplicate, 0.7–0.9 related, < 0.7 new. Run it before bulk imports or when deciding whether to learn or --supersedes. Flags: --limit <n> (default 10), --scope <s>. Exits 2 when nothing matches.

plur batch-decay

Apply ACT-R decay to all local engrams. Run weekly (cron or a maintenance session).

plur batch-decay
plur batch-decay --context-scope project:my-app    # don't decay the active project

Reports processed / decayed / skipped counts and any status transitions (e.g. active → dormant). Only local-store engrams decay client-side.

plur tensions

Contradiction management. List persisted tensions, scan for new ones with an LLM judge, and walk each through the confirm / dismiss / resolve lifecycle. See Tensions & contradictions.

plur tensions                              # list unresolved tension records
plur tensions --status all                 # include dismissed/resolved
plur tensions --scan                       # LLM scan; new detections persisted
plur tensions --scan --no-persist          # dry run — no records written
plur tensions --scan --scope project:plur --min-confidence 0.8
plur tensions confirm T-2026-0703-001      # real conflict
plur tensions dismiss T-2026-0703-001      # false positive — pair suppressed
plur tensions resolve T-2026-0703-001 --winner ENG-...   # keep winner, retire loser

Flags (scan mode)

Flag	Default	Notes
--scan	off	Run the LLM contradiction scan. Requires OPENROUTER_API_KEY or OPENAI_API_KEY, or --llm-base-url + --llm-api-key (+ optional --model).
--no-persist	off	Dry run: no records written, recorded-pair suppress list ignored.
--scope / --domain	none	Narrow the scan.
--min-confidence <n>	0.7	Judge confidence threshold.
--max-pairs <n>	50	Candidate pairs to judge (highest-overlap first).
--batch-size <n>	5	Pairs per LLM call; 1 for sequential judging.
--temporal-discount / --no-temporal-discount	config	Days-apart confidence discount for temporal-evolution pairs (off by default).

plur audit

Content-layer health check — the sibling of plur doctor (infra layer). Walks a runtime’s working memory (Claude Code auto-memory by default), recalls related engrams for each entry, and classifies every entry: conflict (an engram negates it), duplicate (an engram already covers it), snapshot (volatile facts that belong in a live source), orphan (old, no engram coverage), or durable (fine where it is). Each classification comes with a suggested next step.

plur audit                          # claude-code auto-memory (default)
plur audit --limit 5                # recall depth per entry
plur audit --from-json ./memory.json --json

Flag	Notes
--source <s>	claude-code (default) | claw | hermes. The claw/hermes adapters are stubs — use --from-json.
--from-json <path>	Cross-language bridge: audit working memory exported as JSON by another runtime’s adapter.
--limit <n>	Engrams recalled per entry (default 5).

plur migrate

Schema migrations for the engram store.

plur migrate status      # current vs latest schema version
plur migrate             # apply pending migrations (alias: migrate up)
plur migrate down 4      # roll back to schema version 4

Migrations back up the store before applying; the backup path is printed. Newer PLUR versions run migrations as needed — this command exists for explicit control and rollback.

plur rerank-eval

Per-store reranker self-eval gate (advisory). Cross-encoders can be net-negative out-of-domain — this is the quick self-check to run before enabling PLUR_RERANKER on a store. It samples the store’s own engrams, synthesizes probe queries, and compares the reranker’s ordering against plain RRF.

plur rerank-eval
plur rerank-eval --reranker ms-marco-minilm-l6 --sample 30 --seed 7
plur rerank-eval --force        # ignore the cached verdict

Reports ΔMRR, Hit@1 before/after, promotion/demotion counts, per-probe latency, and a verdict: helpful, harmful, or insufficient-data. The verdict is cached in the store (stale after 7 days or >20% store-size drift) and surfaced by plur_doctor. Advisory only — a harmful verdict never auto-disables reranking, but the command exits 1 on it so scripts can gate.

Flag	Notes
--reranker <name>	bge-reranker-v2-m3 (quality tier) or ms-marco-minilm-l6 (tiny tier).
--sample <N> / --seed <N>	Probe count and RNG seed for reproducible runs.
--force	Re-run even if a fresh cached verdict exists.

Internal hook commands

The hook-* commands (hook-inject, hook-observe, hook-learn-check, hook-session-guard, hook-session-mark, hook-session-remind, hook-correction-detect, hook-revert-detect, and the four hook-cursor-* handlers) are invoked by the hooks that plur init installs — Claude Code and Cursor lifecycle events call them with event JSON on stdin. You never run them by hand; they’re listed in plur --help for transparency. See Hooks.

Exit codes

Kept deliberately simple:

Code	Meaning
0	Success.
1	Error (bad usage, engine failure) — also rerank-eval’s harmful verdict.
2	No results (recall, similarity-search) or connectivity failure (init-remote).