# https://github.com/plur-ai/plur Project Manual Generated at: 2026-07-21 23:16:40 UTC ## Table of Contents - [Overview, Install & Quick Start](#page-overview) - [Core Engine: Engrams, Episodes, Storage & Scopes](#page-core-engine) - [Search, Recall, Injection & Recall Quality](#page-search-recall) - [Integrations: MCP, CLI, OpenClaw, Hermes, Python & LangChain](#page-integrations) ## Overview, Install & Quick Start ### Related Pages Related topics: [Core Engine: Engrams, Episodes, Storage & Scopes](#page-core-engine), [Integrations: MCP, CLI, OpenClaw, Hermes, Python & LangChain](#page-integrations)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/plur-ai/plur/blob/main/README.md) - [CLAUDE.md](https://github.com/plur-ai/plur/blob/main/CLAUDE.md) - [CONTRIBUTING.md](https://github.com/plur-ai/plur/blob/main/CONTRIBUTING.md) - [ROADMAP.md](https://github.com/plur-ai/plur/blob/main/ROADMAP.md) - [CHANGELOG.md](https://github.com/plur-ai/plur/blob/main/CHANGELOG.md) - [llms-install.md](https://github.com/plur-ai/plur/blob/main/llms-install.md) - [package.json](https://github.com/plur-ai/plur/blob/main/package.json)
# Overview, Install & Quick Start ## What Plur Is Plur is a memory and recall layer for AI agents, distributed as a TypeScript monorepo on npm. The repository is organised around three workspaces — `packages/core` (the domain library), `packages/cli` (the user-facing command surface) and `packages/mcp` (the Model Context Protocol server that AI agents call directly) — wired together at the root `package.json` level. Source: [package.json:1-40]() The project targets two primary consumers: - **AI agents** that integrate via MCP and call tools such as `plur_session_start`, `plur_scopes_discover`, and `plur_recall_hybrid`. Source: [README.md:1-60]() - **Human operators** that drive the same capabilities from a terminal through the `plur` CLI, where commands like `plur scopes list/register/dismiss/reoffer` form the primary user-facing surface. Source: [README.md:60-120]() The latest published release, **v0.14.0**, is described in the changelog as a hardening cut focused on recall/reranker fixes, hardened shared-scope metadata, feedback and hook reliability, and CLI pack management. Source: [CHANGELOG.md:1-30]() ## Installation The install path is documented for both LLM consumers and humans in a dedicated guide. Source: [llms-install.md:1-20]() Standard install steps for an npm consumer: 1. **Install the published packages.** The CLI and MCP server are published separately; install whichever surface you need, or both for a complete agent + operator setup. 2. **Pin to a known version.** The codebase currently pins MCP SDK v2 at the exact beta `2.0.0-beta.4` across `@modelcontextprotocol/server`, `@modelcontextprotocol/client`, and `@modelcontextprotocol/core`; upgrading to GA is tracked separately. Source: [CHANGELOG.md:30-60]() 3. **Create the config directory.** Plur writes a YAML config to `~/.plur/config.yaml`. The file is created on first write (for example when scopes are registered or dismissed) and stores lists such as `dismissed_scopes`. Source: [CONTRIBUTING.md:1-40]() 4. **Verify the install** with the doctor-style check, exposed as the `plur_doctor` MCP tool, which reports healthy even in headless contexts (a known gap tracked separately from installation itself). Source: [README.md:120-180]() The MCP server is consumed by MCP-capable clients; the CLI binary is invoked as `plur ` once installed globally or via `npx`. ## Quick Start The canonical first-run flow is: 1. **Start an MCP session.** The agent (or operator invoking the MCP surface) calls `plur_session_start`. On success, the response includes a count of *authorized-but-unregistered* scopes — e.g. "Your token is authorized for N more scope(s) not yet registered." Source: [README.md:180-240]() 2. **Inspect or opt-out of extra scopes.** The user-facing command is `plur scopes` (alias: `plur scopes list`), which prints the discovered scopes together with their server-authoritative `description` and `covers[]` metadata. From here the operator can `register`, `dismiss`, or `reoffer` per scope. Source: [CONTRIBUTING.md:40-90]() 3. **Discover and register from the agent side.** The `plur_scopes_discover` MCP tool can register scopes in one call (`register:true`); the planned follow-up shrinks the auto-nudge to one quiet line and excludes scopes already in `dismissed_scopes`. Source: [CHANGELOG.md:60-100]() 4. **Recall.** Use `plur_recall_hybrid` (or other recall tools) to read back memories. Note: in headless / non-interactive runs (cron, CI, scheduled tasks), an empty session-directory path can cause `ENOENT: mkdir ''`; this is a tracked gap and `plur_doctor` does not yet surface it. Source: [CONTRIBUTING.md:90-140]() A minimal happy-path invocation sequence: | Step | CLI (operator) | MCP (agent) | |------|-----------------------|----------------------------| | 1 | `plur scopes list` | `plur_session_start` | | 2 | `plur scopes register ` | `plur_scopes_discover register:true` | | 3 | `plur scopes dismiss ` | (n/a — CLI-primary) | | 4 | (recall via API) | `plur_recall_hybrid` | Source: [README.md:240-300]() ## Project Layout & Conventions - **Monorepo workspaces:** `packages/core`, `packages/cli`, `packages/mcp`. Source: [package.json:1-40]() - **Config:** `~/.plur/config.yaml`, written through the same path used by `registerDiscoveredScopes`; new keys such as `dismissed_scopes` are added there for per-scope opt-out. Source: [CONTRIBUTING.md:1-40]() - **Scope metadata:** shared scopes carry a self-describing `description` and `covers[]` list, delivered to clients via `/api/v1/me` (`scope_metadata`) and cached locally; metadata edits are not yet propagated to running clients until the next `/me` pull. Source: [ROADMAP.md:1-60]() - **Contributing norms:** the repository enforces a *claim-before-you-code* convention — contributors are expected to be assigned on the linked issue before opening a PR, with a CI backstop that warns on PR-open when the issue is assigned to someone else and auto-assigns if unassigned. Source: [CONTRIBUTING.md:140-200]() - **AI attribution policy:** the project explicitly disallows AI co-authorship attribution in commits (see `CONTRIBUTING.md` and `CLAUDE.md`). Source: [CLAUDE.md:1-40]() For deeper dives, follow the Developer documentation table in `CLAUDE.md` — the architecture-decision records (ADRs), test pyramid, runbooks, and telemetry references are surfaced there. Source: [CLAUDE.md:40-100]() --- ## Core Engine: Engrams, Episodes, Storage & Scopes ### Related Pages Related topics: [Overview, Install & Quick Start](#page-overview), [Search, Recall, Injection & Recall Quality](#page-search-recall), [Integrations: MCP, CLI, OpenClaw, Hermes, Python & LangChain](#page-integrations)
Related Source Files The following source files were used to generate this page: - [packages/core/src/index.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/index.ts) - [packages/core/src/engrams.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/engrams.ts) - [packages/core/src/episodes.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/episodes.ts) - [packages/core/src/decay.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/decay.ts) - [packages/core/src/scope-routing.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/scope-routing.ts) - [packages/core/src/scope-util.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/scope-util.ts) - [packages/mcp/src/tools.ts](https://github.com/plur-ai/plur/blob/main/packages/mcp/src/tools.ts)
# Core Engine: Engrams, Episodes, Storage & Scopes The `packages/core` package is the heart of `plur`. It exports the `Plur` class — the single object that agents and CLI/MCP layers use to capture, recall, and share memories. Four primitives do the heavy lifting: **engrams** (atomic memory records), **episodes** (temporal groupings), **storage** (persistence + derived caches), and **scopes** (routing + sharing). Everything else in the repository — MCP tools, CLI subcommands, hybrid recall — is a thin surface in front of these primitives. ## Architecture at a glance ```mermaid flowchart LR A[Engrams
atomic units] --> B[Episodes
temporal grouping] B --> C[Storage
SQLite + config.yaml] C --> D[Scope Routing
local / shared / hybrid] D --> E[MCP tools
plur_recall_* / plur_remember] D --> F[CLI
plur scopes / plur doctor] ``` The `Plur` class wires these together: writes flow through scope routing to choose a backend, reads flow back through the same router with optional re-rank and decay scoring. ## Engrams — atomic memory An **engram** is the smallest persistable unit: a single fact, observation, or note an agent wants to remember. `packages/core/src/engrams.ts` defines the schema (id, content, scope, episodeId, timestamps, decay tier, provenance tags) and the operations to insert, fetch, and re-rank candidates. Engrams are content-addressed and immutable from the caller's perspective — updates create new revisions. `Source: [packages/core/src/engrams.ts:1-80]()` Key behaviors: - **Scope-bound**: every engram carries a `scopeId`; recall filters by it before re-ranking. - **Decay-aware**: each engram belongs to a decay tier whose half-life is computed in `packages/core/src/decay.ts`. Frequently recalled engrams are refreshed; untouched ones drop in score. - **Provenance**: derived engrams (e.g., from summarization) record their source engrams for traceability, which is what the "derived-state provenance" ADR covers. ## Episodes — temporal grouping An **episode** is a bounded session or task that bundles a set of related engrams. `packages/core/src/episodes.ts` manages lifecycle: start (open an episode), append (link an engram), close (freeze + index). Episodes make recall contextually sensible — an agent asking "what did we do yesterday?" expects episode-scoped results, not the whole corpus. `Source: [packages/core/src/episodes.ts:42-120]()` Episodes are not strictly required for storage (standalone engrams are valid), but every MCP tool that records memory — `plur_remember`, `plur_recall_hybrid` write paths — opens or attaches to an episode implicitly so recall can default to "this session + recent history." ## Storage — SQLite + config Persistence is split across two files: 1. **SQLite database** (path resolved by `Plur`) — engrams, episodes, embeddings, and recall caches. 2. **`~/.plur/config.yaml`** — durable settings: `dismissed_scopes`, registered scope URLs, and token metadata. The config write path used by `registerDiscoveredScopes` is the same one that the upcoming `dismissed_scopes` opt-out (issue #649) will reuse. `Source: [packages/core/src/index.ts:30-95]()` Storage handles derived state (recall caches, embeddings index) separately from source-of-truth rows. A recall cache miss never blocks a write — re-derivation is lazy, which is the pattern flagged in the ADR about derived-state provenance. ## Scopes — routing and sharing Scopes determine **where** an engram lives and **who** can read it. `packages/core/src/scope-routing.ts` is the decision point on every read/write: - **Local scope** → write to SQLite only. - **Shared scope** → push to a registered remote endpoint via `/api/v1/me`-derived metadata. - **Hybrid** → write locally *and* propagate to shared, recall from both with re-ranking. `packages/core/src/scope-util.ts` provides the helpers that parse, normalize, and validate scope identifiers used by the router. `Source: [packages/core/src/scope-routing.ts:1-60]()` Scope metadata (`description`, `covers[]`) is **server-authoritative** — clients receive it via `/api/v1/me` and cache it locally. This is the freshness gap tracked in #648: edits on the server don't reach running clients until the next `/me` pull. Discovery of authorized-but-unregistered scopes is already surfaced by `plur_session_start`; the per-scope opt-out (issues #649, #650, #651) layers a `dismissed_scopes` filter on top, exposed to users via `plur scopes` and to agents via a quieter one-line session nudge in `plur_session_start`. `Source: [packages/mcp/src/tools.ts:1920-1940]()` ## Cross-cutting concerns | Concern | File | Role | |---|---|---| | Memory quality / decay scoring | `packages/core/src/decay.ts` | Half-life per tier, refresh-on-recall | | Re-ranking | `packages/core/src/engrams.ts` | Stage-3 write-scope ranker mentioned in #648 | | Headless safety | `packages/core/src/index.ts` | Resolves session dir; fixes the `mkdir ''` failure from #641 | | CLI surface | `packages/cli/src` | `plur scopes`, `plur doctor`, pack management | Together these layers let the same `Plur` instance serve an interactive agent (MCP), a headless cron job, and a human at the terminal — with identical recall semantics and a single source of truth for memory. --- ## Search, Recall, Injection & Recall Quality ### Related Pages Related topics: [Core Engine: Engrams, Episodes, Storage & Scopes](#page-core-engine), [Integrations: MCP, CLI, OpenClaw, Hermes, Python & LangChain](#page-integrations)
Related Source Files The following source files were used to generate this page: - [packages/core/src/fts.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/fts.ts) - [packages/core/src/embeddings.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/embeddings.ts) - [packages/core/src/embedders/index.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/embedders/index.ts) - [packages/core/src/embedders/bge-small.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/embedders/bge-small.ts) - [packages/core/src/hybrid-search.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/hybrid-search.ts) - [packages/core/src/rerankers/index.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/rerankers/index.ts) - [packages/mcp/src/tools.ts](https://github.com/plur-ai/plur/blob/main/packages/mcp/src/tools.ts)
# Search, Recall, Injection & Recall Quality ## Overview Plur exposes memory as a search substrate. Every tool an agent calls — `plur_recall`, `plur_recall_hybrid`, scope discovery, write-scope ranking — is a thin wrapper around a two-stage retrieval pipeline: a **first-pass hybrid search** that fuses full-text and vector similarity signals, followed by an optional **reranker** that reorders candidates using a more expressive model. The pipe output is then **injected** into the model prompt with provenance metadata so downstream turns (and feedback) can attribute each surfaced fact. This page describes how those four pieces fit together: search → recall → injection → recall-quality controls. ## Hybrid Search (first pass) The first pass runs on every recall. It blends two scorers: - **FTS5 keyword retrieval** — implemented in `packages/core/src/fts.ts`. It owns tokenization, BM25-style scoring, and the on-disk FTS5 shadow table that mirrors the primary content table. FTS handles precise identifiers, error messages, and operator-style queries (`auth`, `401`, etc.) where embedding similarity is weak. Source: [packages/core/src/fts.ts:1-120]() - **Vector retrieval** — implemented in `packages/core/src/embeddings.ts` and the pluggable backend in `packages/core/src/embedders/index.ts`. The default backend (`packages/core/src/embedders/bge-small.ts`) loads BGE-small as a local ONNX model so embeddings can be computed offline without sending text to a third-party service. Source: [packages/core/src/embeddings.ts:1-160](), [packages/core/src/embedders/index.ts:1-90](), [packages/core/src/embedders/bge-small.ts:1-80]() The two result lists are fused by `packages/core/src/hybrid-search.ts` using reciprocal rank fusion (RRF). RRF is preferred over score normalization because FTS BM25 and cosine scores live on different scales and the absolute magnitudes vary across queries. RRF only needs ranks, which keeps the fusion robust. Source: [packages/core/src/hybrid-search.ts:1-140]() ## Recall tools and headless paths The MCP surface materializes recall as two tools in `packages/mcp/src/tools.ts`: - `plur_recall` — calls the hybrid pipeline above directly with a per-turn query and returns the top-N candidates, sorted by RRF score. - `plur_recall_hybrid` — same pipeline plus an explicit reranker pass and a structured provenance block (scope id, ranker stage, score components). It is the tool agents use when they need a *justification* per fact rather than just a list. Both tools share a session directory convention. Community issue #641 reports that `plur_recall_hybrid` fails with `ENOENT: no such file or directory, mkdir ''` in headless/cron contexts because the session-dir environment variable resolves to empty when the MCP server is launched without an interactive shell. `plur_doctor` still reports healthy because the failure is in the tool's write-then-read step, not in the underlying index. The issue tracks a fix that derives the session dir from a stable fallback before any mkdir call. Source: [packages/mcp/src/tools.ts:800-940](), [packages/mcp/src/tools.ts:1700-1920]() ## Reranking and recall quality The second stage is a reranker pluggable in the same shape as embedders. `packages/core/src/rerankers/index.ts` exposes the registry and the default cross-encoder reranker. The reranker consumes the top-K candidates from the hybrid pass and produces a calibrated relevance score that is then used to re-sort, dedupe near-duplicates, and emit a per-stage provenance trail. Recall quality levers exposed via config: | Lever | Where | Effect | |---|---|---| | Hybrid `topK` | `hybrid-search.ts` | Candidate pool size for the reranker. Larger improves recall, smaller is cheaper. | | Reranker `topN` | `rerankers/index.ts` | Final list size injected into the prompt. | | Score-floor | `fts.ts` / `embeddings.ts` | Drops low-confidence hits before fusion, controlling precision. | | Scope-filter | tool input | Constrains both legs of the hybrid pass to one or more scopes. | The v0.14.0 release notes call out "sharper recall + reranker fixes" as a hardening focus; the reranker default was tightened to reject candidates whose cross-encoder score falls below the FTS-only baseline, which reduces hallucinated top hits in noisy sessions. Source: [packages/core/src/rerankers/index.ts:1-120](), [packages/mcp/src/tools.ts:1700-1920]() ## Injection and freshness Recall is only useful when its outputs survive into the model's working context. Injection happens in `packages/mcp/src/tools.ts` where each tool's result is wrapped in a fenced block that includes: - The query string used. - The stage at which each item was chosen (FTS / embedding / reranker). - The scope id, so the agent can cite it back. Scope-metadata freshness is a known seam. Per community issue #648, edits to server-authoritative `scope_metadata` (`description`, `covers[]`) are not reflected until the client re-pulls `/api/v1/me`, because the client caches the metadata locally. The scope-metadata cache is keyed by `(scope_id, etag)` and the write-scope ranker (Stage 3) is the first consumer to notice a stale entry — it will silently rank against an outdated `covers[]`. A freshness signal in `/me` is proposed as a low-priority fix. Source: [packages/mcp/src/tools.ts:1200-1340](), [packages/mcp/src/tools.ts:1800-1920]() ## Related community threads - #647 — proactive registration of authorized-but-unregistered scopes shares the same session-start injection point used by recall results; the proposed shrink to "N scope(s) available — run `plur scopes`" lives just above the recall injection. - #649 — the core persist/reoffer layer for `dismissed_scopes` is the input filter that runs before the hybrid pass, so a dismissed scope never reaches the reranker. - #651 — MCP layer counterpart to #649 that excludes dismissed scopes from the recall nudge without changing the recall algorithm itself. Together these describe a retrieval pipeline whose **quality** is determined by fusion + reranking, whose **safety** is determined by the scope filter, and whose **freshness** is determined by the metadata cache invalidation path on `/api/v1/me`. --- ## Integrations: MCP, CLI, OpenClaw, Hermes, Python & LangChain ### Related Pages Related topics: [Overview, Install & Quick Start](#page-overview), [Core Engine: Engrams, Episodes, Storage & Scopes](#page-core-engine), [Search, Recall, Injection & Recall Quality](#page-search-recall)
Related Source Files The following source files were used to generate this page: - [packages/mcp/src/index.ts](https://github.com/plur-ai/plur/blob/main/packages/mcp/src/index.ts) - [packages/mcp/src/tools.ts](https://github.com/plur-ai/plur/blob/main/packages/mcp/src/tools.ts) - [packages/mcp/src/server.ts](https://github.com/plur-ai/plur/blob/main/packages/mcp/src/server.ts) - [packages/mcp/ARCHITECTURE.md](https://github.com/plur-ai/plur/blob/main/packages/mcp/ARCHITECTURE.md) - [packages/cli/src/index.ts](https://github.com/plur-ai/plur/blob/main/packages/cli/src/index.ts) - [packages/cli/src/plur.ts](https://github.com/plur-ai/plur/blob/main/packages/cli/src/plur.ts) - [packages/cli/src/commands/scopes.ts](https://github.com/plur-ai/plur/blob/main/packages/cli/src/commands/scopes.ts) - [packages/openclaw/index.ts](https://github.com/plur-ai/plur/blob/main/packages/openclaw/index.ts) - [packages/hermes/src/index.ts](https://github.com/plur-ai/plur/blob/main/packages/hermes/src/index.ts) - [packages/python/plur/__init__.py](https://github.com/plur-ai/plur/blob/main/packages/python/plur/__init__.py) - [packages/langchain/src/index.ts](https://github.com/plur-ai/plur/blob/main/packages/langchain/src/index.ts)
# Integrations: MCP, CLI, OpenClaw, Hermes, Python & LangChain Plur exposes its recall, memory, and shared-scope capabilities through a layered set of integration surfaces so the same core primitives can be reached from agents, scripts, terminal users, and third-party frameworks. Each surface preserves a single source of truth on the server while adapting the interaction model to the host environment. ## Overview The integrations live under `packages/` and share the underlying `Plur` client. The MCP package is the primary agent-facing surface, the CLI is the primary human-facing surface, and OpenClaw, Hermes, Python, and LangChain wrap the client for specific ecosystems. All surfaces resolve to the same HTTP API (`/api/v1/me`, `/api/v1/recall`, `/api/v1/feedback`, etc.) and read the same `~/.plur/config.yaml`. Source: [packages/mcp/ARCHITECTURE.md:1-40](). ## MCP Integration The Model Context Protocol server is implemented in `packages/mcp/src/index.ts`, which wires transport selection and dispatches tool registrations from `packages/mcp/src/tools.ts`. The transport layer (`packages/mcp/src/server.ts`) supports both stdio and HTTP transports so the same binary can be launched by Claude Desktop, Cursor, or a remote agent. Source: [packages/mcp/src/server.ts:1-80](). Tools are exposed under stable names such as `plur_session_start`, `plur_recall`, `plur_recall_hybrid`, `plur_feedback`, and `plur_scopes_discover`. `plur_session_start` returns the agent-facing nudge when authorized-but-unregistered scopes exist: "Your token is authorized for N more scope(s) not yet registered … call `plur_scopes_discover register:true` to add them all in one step." Source: [packages/mcp/src/tools.ts:1900-1980](). Community issue #651 (active) plans to shrink this nudge to one quiet line and exclude scopes the user has dismissed locally, routing agents to the CLI for the user-facing register/dismiss flow. Source: [packages/mcp/src/tools.ts:1920-1940](). ## CLI Integration `packages/cli/src/index.ts` is the entry point and registers subcommands backed by handlers in `packages/cli/src/plur.ts`. Subcommands include `plur recall`, `plur feedback`, `plur doctor`, `plur scopes`, and `plur pack`. Each command parses argv, instantiates a `Plur` client from `~/.plur/config.yaml`, and prints results in a human-readable table. Source: [packages/cli/src/plur.ts:1-90](). `plur scopes` is the user-facing surface for the opt-out work tracked in issues #647, #649, and #650. `plur scopes list` enumerates authorized-but-unregistered shared scopes using their self-describing `description`; `plur scopes register ` and `plur scopes dismiss ` write back to the same `registerDiscoveredScopes` path the MCP layer uses, keeping one persistence path. Source: [packages/cli/src/commands/scopes.ts:1-60](). `plur_doctor` reports session-dir health for the diagnostic surfaced by issue #641 — note that as of v0.14.0 it does not catch the empty session-dir path that breaks `plur_recall_hybrid` in headless contexts. Source: [packages/cli/src/plur.ts:120-180](). ## Platform Integrations | Package | Purpose | Entry point | | --- | --- | --- | | `packages/openclaw` | Adapts plur recall/scopes for OpenClaw agents | `packages/openclaw/index.ts` | | `packages/hermes` | Hermes messenger bridge for notifications and recall replies | `packages/hermes/src/index.ts` | | `packages/python` | Python bindings mirroring the TypeScript `Plur` client | `packages/python/plur/__init__.py` | | `packages/langchain` | LangChain tool wrappers (`PlurRecallTool`, `PlurFeedbackTool`) | `packages/langchain/src/index.ts` | The Python and LangChain wrappers re-export the canonical methods (`recall`, `feedback`, `register_discovered_scopes`) so behavior stays identical across surfaces. Source: [packages/python/plur/__init__.py:1-40](), [packages/langchain/src/index.ts:1-60](). Hermes subscribes to the same `/api/v1/me` `scope_metadata` payload used by MCP and the CLI, which is why issue #648 proposes a freshness signal — scope-metadata edits currently wait for the next `/me` pull before running clients see them. Source: [packages/hermes/src/index.ts:30-90](). ## Versioning and SDK Compatibility The MCP package was migrated to MCP SDK v2 split packages in PR #638 and is currently pinned to exact betas (`@modelcontextprotocol/server@2.0.0-beta.4`, `@modelcontextprotocol/client@2.0.0-beta.4`, `@modelcontextprotocol/core@2.0.0-beta.4`) ahead of the 2026-07-28 RC; issue #645 tracks the GA bump. Source: [packages/mcp/ARCHITECTURE.md:60-95](), [packages/mcp/src/index.ts:1-50](). Across all integrations, v0.14.0 ships hardened shared-scope metadata, sharper recall/reranker fixes, feedback and hook reliability work, and the new CLI pack management commands that round out the user-facing surface. --- --- ## Pitfall Log Project: plur-ai/plur Summary: Found 33 structured pitfall item(s), including 8 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/plur-ai/plur/issues/645 ## 2. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: Proactively offer to register authorized-but-unregistered scopes (per-scope, remembered opt-out) - User impact: Developers may expose sensitive permissions or credentials: Proactively offer to register authorized-but-unregistered scopes (per-scope, remembered opt-out) - Evidence: failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/647 ## 3. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: Scope-metadata edits not reflected in running clients (cached until next /me pull) — freshness signal? - User impact: Developers may expose sensitive permissions or credentials: Scope-metadata edits not reflected in running clients (cached until next /me pull) — freshness signal? - Evidence: failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/648 ## 4. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: plur sync: scope-aware push — don't send private-visibility engrams to shared remotes - User impact: Developers may expose sensitive permissions or credentials: plur sync: scope-aware push — don't send private-visibility engrams to shared remotes - Evidence: failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/640 ## 5. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/plur-ai/plur/issues/647 ## 6. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/plur-ai/plur/issues/648 ## 7. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/plur-ai/plur/issues/650 ## 8. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/plur-ai/plur/issues/649 ## 9. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: Upgrade MCP SDK v2 from 2.0.0-beta.4 to stable GA when released - User impact: Developers may fail before the first successful local run: Upgrade MCP SDK v2 from 2.0.0-beta.4 to stable GA when released - Evidence: failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/645 ## 10. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: compat: MCP SDK v2 migration — import split + Zod v3→v4 (deadline 2026-07-28) - User impact: Developers may fail before the first successful local run: compat: MCP SDK v2 migration — import split + Zod v3→v4 (deadline 2026-07-28) - Evidence: failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/637 ## 11. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: plur-hermes 0.9.11 — pin CLI 0.9.12 - User impact: Upgrade or migration may change expected behavior: plur-hermes 0.9.11 — pin CLI 0.9.12 - Evidence: failure_mode_cluster:github_release | https://github.com/plur-ai/plur/releases/tag/hermes-v0.9.11 ## 12. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v0.10.0 — security-hardening release - User impact: Upgrade or migration may change expected behavior: v0.10.0 — security-hardening release - Evidence: failure_mode_cluster:github_release | https://github.com/plur-ai/plur/releases/tag/v0.10.0 ## 13. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v0.11.0 — Hooks that actually finish, tension lifecycle, migration importers - User impact: Upgrade or migration may change expected behavior: v0.11.0 — Hooks that actually finish, tension lifecycle, migration importers - Evidence: failure_mode_cluster:github_release | https://github.com/plur-ai/plur/releases/tag/v0.11.0 ## 14. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v0.12.0 - User impact: Upgrade or migration may change expected behavior: v0.12.0 - Evidence: failure_mode_cluster:github_release | https://github.com/plur-ai/plur/releases/tag/v0.12.0 ## 15. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v0.13.0 - User impact: Upgrade or migration may change expected behavior: v0.13.0 - Evidence: failure_mode_cluster:github_release | https://github.com/plur-ai/plur/releases/tag/v0.13.0 ## 16. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v0.14.0 - User impact: Upgrade or migration may change expected behavior: v0.14.0 - Evidence: failure_mode_cluster:github_release | https://github.com/plur-ai/plur/releases/tag/v0.14.0 ## 17. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/plur-ai/plur/issues/637 ## 18. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/plur-ai/plur ## 19. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: CI: warn on PR-open when the linked issue is assigned to someone else (+ auto-assign if unassigned) - User impact: Developers may misconfigure credentials, environment, or host setup: CI: warn on PR-open when the linked issue is assigned to someone else (+ auto-assign if unassigned) - Evidence: failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/593 ## 20. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: Orphaned docs + missing CLAUDE.md/CONTRIBUTING references (test-pyramid, ADRs, runbooks, telemetry, no-AI-attribution) - User impact: Developers may misconfigure credentials, environment, or host setup: Orphaned docs + missing CLAUDE.md/CONTRIBUTING references (test-pyramid, ADRs, runbooks, telemetry, no-AI-attribution) - Evidence: failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/620 ## 21. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: plur_recall_hybrid fails with "ENOENT: mkdir ''" in headless/scheduled runs (empty session-dir path); plur_doctor still reports healthy - User impact: Developers may misconfigure credentials, environment, or host setup: plur_recall_hybrid fails with "ENOENT: mkdir ''" in headless/scheduled runs (empty session-dir path); plur_doctor still reports healthy - Evidence: failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/641 ## 22. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: scopes opt-out (cli): 'plur scopes' list/register/dismiss/reoffer — the user-facing surface - User impact: Developers may misconfigure credentials, environment, or host setup: scopes opt-out (cli): 'plur scopes' list/register/dismiss/reoffer — the user-facing surface - Evidence: failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/650 ## 23. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: scopes opt-out (core): persist dismissed scopes + single register/dismiss/reoffer + filter discovery - User impact: Developers may misconfigure credentials, environment, or host setup: scopes opt-out (core): persist dismissed scopes + single register/dismiss/reoffer + filter discovery - Evidence: failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/649 ## 24. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/plur-ai/plur/issues/644 ## 25. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/plur-ai/plur/issues/641 ## 26. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/plur-ai/plur ## 27. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/plur-ai/plur ## 28. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/plur-ai/plur ## 29. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/plur-ai/plur ## 30. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/plur-ai/plur/issues/593 ## 31. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/plur-ai/plur/issues/620 ## 32. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/plur-ai/plur ## 33. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/plur-ai/plur