Create an engram — record a reusable learning, preference, or correction. Multi-agent note: in an orchestration that spawns subagents, have the PARENT session own plur_learn writes — spawned subagents should return their findings as text for the parent to persist, rather than each calling plur_learn (tool availability is not guaranteed in every subagent context). See plur-ai/plur#281.

Create many engrams in one call — the batch form of plur_learn. Accepts an array of engram objects and writes them sequentially through the SAME dedup + policy pipeline as plur_learn (content-hash NOOP → semantic recall → LLM ADD/UPDATE/MERGE decision). Dedup also applies WITHIN the batch: a statement duplicating an earlier item in the same array resolves to NOOP against it. Returns ids aligned 1:1 with the input array (ids[i] is the engram id for input i, or null if input i failed), the per-item decisions (each carrying its input_index), aggregate stats, and any per-item failures (each with its input index) — a single bad item does not abort the batch. Use this when an orchestration fans out and wants to persist consolidated findings without N separate calls. LLM dedup calls are capped (default 50, override with max_llm_calls) to bound bulk-import cost. Note: unlike plur_learn, batch items take the LOCAL learn path — remote-scope auto-routing (learnRouted) is not applied per item, so for shared/remote-store writes prefer plur_learn or pass an explicit local scope. See plur-ai/plur#281.

Query engrams by BM25 keyword matching — use plur_recall_hybrid for semantic similarity. Note: a project-scope filter also returns personal-family engrams (local, global, user:, agent:); an explicit scope=global recall returns ALL personal-family engrams — wider than scope=global INJECT, which is targeted to the global namespace only.

Hybrid search — BM25 + local embeddings merged via Reciprocal Rank Fusion. No API calls, fully local. Best default for most use cases.

Get a scored context injection for a task — returns directives and considerations within token budget

Hybrid injection — BM25 + embeddings for better context selection. Falls back to BM25 if embeddings unavailable. Best default for injection.

Rate an engram's usefulness — trains injection relevance over time. Supports single or batch mode.

Toggle the always-load (pinned) flag on an engram. Pinned engrams bypass the keyword-relevance gate at injection time and are eligible for loading on every session, regardless of overlap with the user task. Use sparingly — meta-rules, safety conventions, core operating principles. Pass {id, pinned:true} to pin or {id, pinned:false} to unpin. List current pinned with {list:true}.

Retire an engram by ID or search term — marks it as no longer active without deleting history

Append an episode to the episodic timeline — records what happened in a session

Query the episodic timeline — retrieve past episodes filtered by time, agent, or search

Extract engram candidates from content using pattern matching — optionally auto-save them

Preview a pack before installing — shows manifest, engram list, security scan, and warnings. Always call this before plur_packs_install to let the user review what they are importing.

Install an engram pack from a directory path. Runs a mandatory security scan (blocks if secrets found), detects conflicts with existing engrams, and records install metadata in the registry. Call plur_packs_preview first to show the user what the pack contains.

Uninstall an engram pack by name — removes the pack and all its engrams

List all installed engram packs with integrity hashes, install dates, and source paths

Browse available engram packs from the registry — discover curated expertise packs to install

Sync engrams via git AND refresh the derived index from YAML. Initializes repo on first call, commits and pushes/pulls on subsequent calls. Provide a remote URL on first call to enable cross-device sync. Pass full=true to drop-and-rebuild the index from YAML (recovery path; YAML stays untouched).

Check git sync status — whether repo is initialized, has remote, is dirty, ahead/behind counts

Extract meta-engrams from stored engrams using the 6-stage pipeline (structural analysis → clustering → alignment → formulation → hierarchy). Requires an LLM API endpoint.

List existing meta-engrams (engrams with META- prefix) with their structural templates and confidence scores

Test a meta-engram template against engrams from a new domain — updates confidence and domain_coverage

Return system health — running version, engram count, episode count, pack count, storage root. Optionally filter engram counts by domain prefix and/or creation date.

Diagnose the PLUR ENGINE (embedder, hybrid search, remote-store auth) — not hook/MCP wiring. Reports whether the embedding model loaded, whether hybrid search is fully operational, and — for any configured enterprise/remote store — whether its auth is valid (probes /api/v1/me and decodes token expiry), so a dead or soon-to-expire token surfaces instead of hiding behind a "healthy" report. Run this first when recall feels off or team engrams stop syncing. Does NOT check .cursor/mcp.json, .cursor/hooks.json, or the live MCP tool count — for that, run the plur doctor CLI command in a terminal (a different, more thorough check with the same name).

Start a session — inject relevant engrams for your task. Call at the beginning of every session.

End a session. BEFORE calling this tool, review the conversation and extract learnings:

1. Corrections the user made ("no, use X not Y") → type: behavioral

2. Preferences stated ("always X", "never Y") → type: behavioral

3. Codebase patterns discovered (naming, structure, conventions) → type: architectural

4. Technical facts learned (API quirks, config, gotchas) → type: procedural

5. Terminology defined or clarified → type: terminological

Include at least one engram_suggestion if ANYTHING was learned. An empty suggestions array means nothing worth remembering happened — this should be rare.

Register an additional engram store. Either filesystem (path) or remote (url+token, e.g. PLUR Enterprise). One remote URL can host multiple scopes — call once per team scope you are authorized for; each registers independently. Returns status: "added" or "already_registered".

List all configured engram stores with their scope, path, and engram count. When a store declares self-describing scope metadata, its description and covers (topics the scope is the home for) are included so you can pick the right scope.

Suggest which registered scope(s) an engram belongs in, ranked by fit. Deterministic — no LLM, no network. Scores the statement keywords, optional domain (a dotted namespace like "plur.core.security"), and tags against the covers[] each scope declares. ADVISORY ONLY: this does not route or store anything; pass the chosen scope to plur_learn yourself. Returns candidates sorted by confidence (empty when nothing matches).

Discover which scopes your remote token is authorized for via the enterprise server (GET /api/v1/me), and which of those are not yet registered locally. Read-only by default; pass register:true to register all authorized-but-unregistered scopes in one step. Only shared-family scopes (group:/project:/space:/team:/org:/public) are auto-registered — personal-family scopes (global/local/user:/agent:) advertised by /me are skipped and surfaced in the result. Use this when you have access to multiple team scopes on one server.

Activate candidate engrams so they appear in injection results

Tension lifecycle (#181). Default: list persisted tension records (unresolved first). scan:true runs an LLM contradiction scan, persists NEW detections as records, and skips already-recorded pairs. Lifecycle actions: action:"confirm" (real conflict), action:"dismiss" (false positive — pair suppressed from future scans), action:"resolve" + winner: (loser engram retired). Scan requires OPENAI_API_KEY or OPENROUTER_API_KEY env var, or explicit llm_base_url + llm_api_key args.

Purge all conflict relations from local engrams — removes accumulated false positives from the legacy tension-detection system

Promote an episode to a persistent episodic engram — useful when a session event deserves long-term memory

View the event-sourced history of an engram or all recent history — shows creation, updates, feedback, and evolution events

Report a failure for a procedural engram — triggers procedure evolution via LLM if configured. Only works on procedural engrams. Max 3 revisions per procedure per 24h.

Export engrams as a shareable thematic pack with privacy scanning and integrity hash. Filters out private and secret-containing engrams automatically. Output goes to ~/plur-packs/ by default.

Search engrams by cosine similarity, returning scores. Used for dedup classification — scores > 0.9 indicate duplicates, 0.7-0.9 related, < 0.7 new.

Generate or retrieve a cognitive profile — a narrative summary synthesized from stored engrams. Cached for 24h.