PLUR

Local memory store an assistant writes corrections and conventions to and recalls across tools

By plur-ai TypeScript Local · stdio Knowledge and memory

56 popularity score ★ 313 ↓ 1.4k/wk

Connect your client

Local (npm)

Add in one click

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal
claude mcp add plur -- npx -y @plur-ai/mcp
Claude Desktopclaude_desktop_config.json
{
  "mcpServers": {
    "plur": {
      "command": "npx",
      "args": [
        "-y",
        "@plur-ai/mcp"
      ]
    }
  }
}
Cursor~/.cursor/mcp.json
{
  "mcpServers": {
    "plur": {
      "command": "npx",
      "args": [
        "-y",
        "@plur-ai/mcp"
      ]
    }
  }
}
VS Code.vscode/mcp.json
{
  "servers": {
    "plur": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@plur-ai/mcp"
      ]
    }
  }
}
Codex~/.codex/config.toml
[mcp_servers.plur]
command = "npx"
args = ["-y", "@plur-ai/mcp"]
Gemini CLITerminal
gemini mcp add --scope user plur npx -- -y @plur-ai/mcp

Settings 9

PLUR_PATH Optional: Folder for the engram store. Default ~/.plur/.
PLUR_TOOL_PROFILE Optional: full exposes every tool directly; lean or cursor exposes 14 core tools plus plur_admin. Default lean.
PLUR_TELEMETRY Optional: on enables the content-free usage counters, off disables them; a saved preference applies when unset. Default off.
Set together: search
PLUR_DISABLE_EMBEDDINGS Optional: Set to 1, true or yes to skip the embedding model and search by keyword only.
PLUR_EMBEDDER Optional: Embedding model: minilm, bge-small, bge-base, embedding-gemma or openai-3-large (the last needs OPENAI_API_KEY). Default bge-small.
PLUR_MODEL_DOWNLOAD Optional: Set to off to stop the embedding model being fetched; a model not already on disk is then not loaded.
PLUR_RERANKER Optional: Set to bge-reranker-v2-m3 to opt in to a local cross-encoder reranker for recall. Default off.
Set together: llm
OPENROUTER_API_KEY secret Optional: Enables the LLM-based tools through OpenRouter with gpt-4o-mini; used before OPENAI_API_KEY when both are set. For plur_extract_meta, plur_tensions scans.
OPENAI_API_KEY secret Optional: Enables the LLM-based tools through OpenAI with gpt-4o-mini, and the openai-3-large embedder. For plur_extract_meta, plur_tensions scans.

What it does

PLUR keeps what an assistant learns while working (corrections, preferences, project conventions, decisions) as small typed records it calls engrams. They are stored as plain YAML in ~/.plur/, or in the folder named by PLUR_PATH. The MCP server, published as @plur-ai/mcp, gives the assistant tools to save, search, rate, retire and re-scope those records and to log timestamped events. It can also push the store to a git remote so the same memory follows you to another machine or a team.

Search runs on your machine, mixing keyword ranking with a small local embedding model, and engrams can carry a scope such as project:my-app so one project's notes stay out of another's.

In v0.22.1 there are 45 tools. By default the server runs a lean profile with 14 of them exposed plus plur_admin, a dispatcher through which the other 30 are called by name. PLUR_TOOL_PROFILE=full exposes the 44 directly. The README's own tool table is shorter. A comment in tools.ts explains why the core set holds tools that delete or rewrite memory, such as plur_tensions and plur_report_failure: the dispatcher is never allowed to delete or overwrite.

New in this line is the folder map at ~/.plur/folders.yaml, edited with plur folders set from a terminal. A folder can be on, off, ask or remote-only, and can carry a default scope. In an off folder the 33 tools that touch engrams return a plain answer without reading or writing any store. In a folder with no decision yet they return a question with ready-made plur folders set commands for the user to choose from. The server never writes the map itself (packages/mcp README).

What it needs

RuntimeNode.js 22+
Runs onmacOS, Windows, Linux
Also
  • git and a private remote, only for plur_sync

Node.js 22 or newer, per the package's engines field and its README. The repository's main README still says 20. The makers' setup also installs @plur-ai/cli globally and runs plur init, which writes client configuration and session hooks. The server starts without it, but the folder map is changed with the plur folders commands from that CLI. The embedding model is downloaded once (plur doctor does this). Without it search is keyword-only. An OpenRouter or OpenAI API key is needed only for the LLM-based tools.

Limits

  • Not covered Stores and recalls engrams only. Its README says it does not index or search source code or files.
  • Limit Under the default lean profile only 14 tools plus plur_admin are listed; the other 30 are reached through plur_admin unless PLUR_TOOL_PROFILE=full is set (tools.ts).
  • Limit In a folder the folder map turns off, or one not yet decided, the 33 memory tools read and write nothing and return a notice or a question instead.
  • Limit If the client's workspace roots cannot be fetched, or folders.yaml cannot be parsed, memory tools do nothing on that call.
  • Limit Server startup is not yet gated by the folder map: starting in an off folder can still register a .plur/ store found there (issue #1523).
  • Not covered Clients without a PLUR adapter (Windsurf, Gemini CLI, other generic clients) get the tools but no automatic injection.
  • Limit A personal sync pushes every engram, private ones included, so the README says to use a private repository.
  • Early release plur_recall_hybrid is a deprecated alias of plur_recall.
  • Limit The main README says Node.js 20 or newer, but the package's engines field requires 22.

It stores and recalls engrams only; its README says it does not index or search source code or files. Unless PLUR_TOOL_PROFILE=full is set, most tools are reachable only through plur_admin (tools.ts). In a folder the folder map turns off, or when the client's workspace roots cannot be fetched, memory tools do nothing. Clients without a PLUR adapter (Windsurf, Gemini CLI and other generic MCP clients) get the tools but no automatic injection, so memory is used only when the model chooses to call them. A personal sync pushes every engram, private ones included, so the README warns to use a private repository. plur_recall_hybrid is deprecated. The Python SDK is not yet on PyPI.

Who it suits

Suits a developer who switches between Claude Code, Cursor, Codex or OpenCode and wants one memory of corrections and conventions that stays on their own disk in files they can read, diff and edit, with optional git sharing for a team. Its adapters for those clients load memory automatically; in other clients it relies on the model to call the tools. It is not a code-search or documentation tool, and not a hosted memory API: its README points readers who need a hosted service or a temporal knowledge graph to other products, and to code-intelligence tools for searching source.

Tools 45

19 only read, 20 change things, 6 can delete or overwrite. A ? marks an optional parameter.

plur_admin changes
Runs any tool not exposed directly under the lean profile, by action name; action help lists themaction: stringargs?: object
plur_session_start changes
Opens a session and returns engrams relevant to the stated tasktask: stringtags?: arraydefault_scope?: string
plur_session_end changes
Closes a session and saves the learnings the agent passes insummary: stringsession_id?: stringengram_suggestions: array
plur_learn changes
Saves one correction, preference or convention as an engram, with optional scopestatement: stringtype?: enumscope?: stringdomain?: stringtags?: arrayrationale?: stringsource?: stringpinned?: booleancommitment?: enumlocked_reason?: stringvalid_from?: stringvalid_until?: stringsupersedes?: arraysession_id?: stringmeasured_under?: objectattribution?: objectclaim_class?: enumlicense?: stringvisibility?: enum
plur_learn_batch changes
Saves many engrams in one call, linking near-duplicates instead of overwriting themengrams: arraymax_llm_calls?: numbersession_id?: string
plur_recall
Searches engrams, hybrid keyword plus embeddings by default or keyword-only with mode keywordquery: stringmode?: enumscope?: stringdomain?: stringlimit?: numberbudget?: objectcaller_session_id?: stringinclude_episodes?: booleansession_id?: string
plur_recall_hybrid
Deprecated alias of plur_recall kept for older setupsquery: stringscope?: stringdomain?: stringlimit?: numberbudget?: objectcaller_session_id?: stringinclude_episodes?: booleansession_id?: string
plur_inject
Picks scored engrams for a task within a token budgettask: stringbudget?: numberscope?: stringsession_id?: string
plur_inject_hybrid
Same selection using keyword plus embedding search, falling back to keywordtask: stringbudget?: numberscope?: stringsession_id?: string
plur_feedback changes
Rates an engram as useful or not, which changes how often it is chosenid?: stringsignal?: enumscope?: stringsignals?: array
plur_pin changes
Turns the always-load flag on or off for an engramid?: stringpinned?: booleanlist?: booleanscope?: string
plur_forget deletes
Retires an engram so it stops being injected, keeping its historyid?: stringsearch?: stringreason?: stringscope?: string
plur_capture changes
Records a timestamped event such as an incident or milestonesummary: stringagent?: stringchannel?: stringsession_id?: stringtags?: array
plur_timeline
Lists recorded events filtered by time, agent or channelsince?: stringuntil?: stringagent?: stringchannel?: stringsearch?: string
plur_ingest changes
Pulls candidate engrams out of supplied text by pattern matching, optionally saving themcontent: stringsource?: stringextract_only?: booleanscope?: stringdomain?: string
plur_episode_to_engram changes
Turns a recorded event into a lasting engramepisode_id: stringscope?: stringdomain?: stringtags?: array
plur_packs_preview
Shows a pack's manifest, contents and scan warnings before installsource: string
plur_packs_install changes
Installs an engram pack from a local folder or an https .tar.gz addresssource: string
plur_packs_uninstall deletes
Removes an installed pack and its engramsname: string
plur_packs_list
Lists installed packs with hashes and sources
plur_packs_discover
Browses packs offered in the PLUR pack registryquery?: stringtags?: arraycategory?: string
plur_packs_export changes
Writes selected engrams out as a shareable pack, leaving out private and secret-bearing onesname: stringdescription?: stringfilter_domain?: stringfilter_scope?: stringfilter_tags?: arrayfilter_type?: enumoutput_dir?: stringcreator?: stringlicense?: string
plur_sync changes
Commits the store with git and pushes or pulls a personal or shared remoteremote?: stringfull?: booleanremote_type?: enum
plur_sync_status
Reports git sync state: remote, uncommitted changes, ahead and behind
plur_outbox changes
Shows team-store writes waiting to be retried, and retries themflush?: boolean
plur_extract_meta changes
Derives higher-level meta-engrams from stored ones; needs an LLM API keyllm_base_url: stringllm_api_key: stringllm_model?: stringdomain?: stringscope?: stringrun_validation?: booleandry_run?: boolean
plur_meta_engrams
Lists existing meta-engrams with their confidence scoresdomain?: stringmin_confidence?: numberhierarchy_level?: enumlimit?: number
plur_validate_meta deletes
Tests a meta-engram against another domain; a third failure can retire itmeta_engram_id: stringtest_domain: stringllm_base_url: stringllm_api_key: stringllm_model?: string
plur_status
Reports store health, engram counts, the storage path and folder-map statedomain?: stringcreated_after?: stringcheck_updates?: boolean
plur_provenance
Shows where an engram came from, who stated it and whether it may be reusedid?: stringsearch?: stringformat?: enum
plur_receipt
Counts how often stored engrams were actually retrieved over a windowdays?: number
plur_doctor
Checks the embedder, hybrid search, the folder map and remote-store sign-inretry?: booleanrerank_eval?: boolean
plur_session_scope changes
Changes the default write scope partway through a sessionop: enumscope?: stringreason?: stringsession_id?: string
plur_stores_add changes
Registers another store, a folder or a remote URL with a tokenpath?: stringurl?: stringtoken?: stringscope: stringshared?: booleanreadonly?: boolean
plur_stores_list
Lists configured stores with scope, path and engram count
plur_suggest_scope
Ranks registered scopes by fit for a statement, without network callsstatement: stringdomain?: stringtags?: arraymin_confidence?: number
plur_scopes_discover changes
Asks the enterprise server which scopes a remote token may write to, optionally registering themurl?: stringregister?: boolean
plur_promote changes
Activates candidate engrams so they can be injectedid?: stringids?: array
plur_rescope changes
Moves an engram to another scope, such as personal to teamid?: stringids?: arraytarget_scope: stringkeep_local?: booleandry_run?: boolean
plur_tensions deletes
Lists, scans for, confirms, dismisses or resolves contradictions; resolving retires the losing engramscope?: stringdomain?: stringscan?: booleanpersist?: booleanaction?: enumid?: stringwinner?: stringstatus?: enumllm_base_url?: stringllm_api_key?: stringllm_model?: stringmin_confidence?: numbermax_pairs?: numberbatch_size?: numbertemporal_discount?: boolean
plur_tensions_purge deletes
Deletes all stored conflict links from local engrams
plur_history
Shows the change history of one engram or of recent activityengram_id?: stringlimit?: number
plur_report_failure deletes
Logs a failure against a procedural engram, which can rewrite the procedure's textengram_id: stringfailure_context: stringllm_base_url?: stringllm_api_key?: stringllm_model?: string
plur_similarity_search
Scores engrams by embedding similarity to a statement, for spotting duplicatesquery: stringlimit?: numberscope?: string
plur_profile
Builds or returns a summary profile drawn from stored engrams, cached for 24 hoursscope?: stringllm_base_url?: stringllm_api_key?: stringllm_model?: stringforce_regenerate?: boolean

Similar servers