Skip to content
Back to search

plur

Shared memory for AI agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/plur-ai/plur with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/plur-ai/plur'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/plur-ai--plur/badge.svg)](/listings/plur-ai--plur)

HTML

<a href="/listings/plur-ai--plur"><img src="/api/listings/plur-ai--plur/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires **Node.js 20 or newer**. Install both packages so editor configurations can use the installed MCP server:

npm install -g @plur-ai/cli@latest @plur-ai/mcp@latest
plur init
plur doctor

Restart your editor after setup. `plur doctor` checks the configuration and MCP handshake, and downloads the search model if it is missing and downloads are allowed. Search runs locally after that download; without the model it falls back to keyword search.

Tell your agent

Set up PLUR memory for me: install @plur-ai/cli@latest and @plur-ai/mcp@latest globally, run `plur init`, then `plur doctor`. Show me any checks that fail.

Claude Code

`plur init` creates the local store at `~/.plur/`, registers the user-scoped MCP server in `~/.claude.json`, and writes global hooks to `~/.claude/settings.json`. A project `.mcp.json` is a separate project-scoped configuration; `~/.claude/mcp.json` is not the user-scoped registration path. The hooks inject memory and close session state when Claude Code emits `SessionEnd`. Run init again after upgrading PLUR to refresh its configuration.

For **multi-project setups**, use domain/scope to separate knowledge:

cd ~/projects/my-app
plur init --domain myapp --scope project:my-app

This creates a `.plur.yaml` in the project with defaults that hooks apply automatically. Engrams learned in that project are tagged; recall filters by scope but always includes global knowledge.

**Set scope per engram, by content.** Scope is not a once-per-session setting — every `plur_learn` call takes its own `scope`, chosen from what the engram is about. Team/shared knowledge goes to a team scope (e.g. `group:<org>/<team>`, used by PLUR Enterprise); project details to `project:<name>`; personal preferences stay local. Don't let team-relevant knowledge fall back to `global` by omitting scope — `global` leaks into every project and (with a team store configured) never reaches the team. `plur_session_start` lists the remote scopes a token can write to.

Upgrade

npm install -g @plur-ai/cli@latest @plur-ai/mcp@latest
plur init
plur doctor

Restart the editor so it launches the updated MCP server.

Cursor

From your project root:

plur init --cursor

This writes `.cursor/mcp.json`, `.cursor/hooks.json` and `.cursor/rules/plur-memory.mdc`. Cursor uses the reduced `cursor` tool profile: core tools are direct, and other operations are available through `plur_admin`. Call `plur_admin` with `{ "action": "help" }` to discover their current names and arguments.

Codex

plur init --codex

Registers a new MCP server via `codex mcp add` in `~/.codex/config.toml`, writes lifecycle hooks to `~/.codex/hooks.json` (`CODEX_HOME` overrides the directory), and adds a PLUR section to `AGENTS.md`. Auto-detected when `~/.codex/` exists.

To upgrade an existing Codex installation:

npm install -g @plur-ai/cli@latest @plur-ai/mcp@latest
plur init --codex
plur doctor --codex

Init updates recognized older PLUR launch pins in place, preserving environment settings, timeouts, tool policies and comments. It preserves newer pins and custom or HTTP servers. Use `--keep-codex-mcp` to retain an intentional older launch entry. Restart Codex after changing its configuration.

For remote stores using `plur remote --token-env NAME`, both `remote` and `init --codex` add the required variable names to Codex's `env_vars`; they never copy token values into its config. The variable must also be available to the process that launches Codex. A variable exported in PowerShell does not prove that a separately launched desktop app inherited it.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "plur",
  3. "version": "0.9.13",
  4. "description": "Persistent, local-first shared memory for AI agents. Corrections, preferences, and conventions persist across sessions, tools, and machines — stored as plain YAML on your disk, with zero-cost local search.",
  5. "author": {
  6. "name": "PLUR",
  7. "url": "https://plur.ai"
  8. },
  9. "homepage": "https://plur.ai",
  10. "repository": "https://github.com/plur-ai/plur",
  11. "license": "Apache-2.0",
  12. "keywords": [
  13. "memory",
  14. "agent-memory",
  15. "mcp",
  16. "local-first",
  17. "context-engine"
  18. ]
  19. }
README.md · README · 645 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <a href="https://plur.ai"><img src="assets/plur-banner.png" alt="PLUR — local-first shared memory for AI agents. Haiku + PLUR beats Opus without it, at ~10× less cost." width="100%"></a>
  3. </p>
  4. # PLUR — Your agents share the same memory
  5. [![MCP Toplist](https://mcptoplist.com/badge/io.github.plur-ai%2Fplur.svg)](https://mcptoplist.com/server/io.github.plur-ai%2Fplur)
  6. [![npm version](https://img.shields.io/npm/v/@plur-ai/core?logo=npm&color=cb3837)](https://www.npmjs.com/package/@plur-ai/core)
  7. [![CI](https://img.shields.io/github/actions/workflow/status/plur-ai/plur/ci.yml?branch=main&logo=github&label=CI)](https://github.com/plur-ai/plur/actions/workflows/ci.yml)
  8. [![License: Apache-2.0](https://img.shields.io/github/license/plur-ai/plur?color=blue)](LICENSE)
  9. [![GitHub stars](https://img.shields.io/github/stars/plur-ai/plur?style=social)](https://github.com/plur-ai/plur/stargazers)
  10. [![Glama score](https://glama.ai/mcp/servers/plur-ai/plur/badges/score.svg)](https://glama.ai/mcp/servers/plur-ai/plur)
  11. Persistent, **open** memory for AI agents — local-first, zero-cost, shared across MCP tools (Claude Code, Codex, Cursor, OpenCode, Hermes, OpenClaw). Your agent's memory is plain-text **engrams** you can read, correct, and delete — not weights you can't.
  12. [plur.ai](https://plur.ai) · [Benchmark](https://plur.ai/benchmark.html) · [Engram Spec](https://plur.ai/spec.html) · [npm](https://www.npmjs.com/org/plur-ai) · [Comparisons](comparisons/)
  13. ## Benchmarks
  14. PLUR is memory, not just retrieval — so we measure it on more than one axis, on the **full** corpus, and we publish the harness so you can reproduce every number.
  15. **Retrieval recall — full LongMemEval-S (N=500), R@5, fully local:**
  16. | Stack | R@5 | Notes |
  17. |-------|-----|-------|
  18. | BM25 only | 92.2% | no embedder — fully airgapped |
  19. | Hybrid (BGE-small, shipping default) | 95.6% | local embedder; one-time model download |
  20. | **+ BGE-reranker-v2-m3** | **97.6%** | local cross-encoder, max quality — opt-in, ≈5s p50 on CPU |
  21. Numbers come from [plur-ai/plur-bench](https://github.com/plur-ai/plur-bench),
  22. which is the source of truth for every benchmark figure PLUR publishes. Where
  23. an in-repo number and a plur-bench number disagree, plur-bench wins — it is the
  24. reproducible harness, and it is what CI regression-checks.
  25. Chunk granularity, canonical-doc scoring, corpus SHA256 pinned — reproduce it in [plur-ai/plur-bench](https://github.com/plur-ai/plur-bench). No cloud call is required for any of these numbers (an *optional* cloud embedder, openai-3-large, reaches 97.0% hybrid). A faster reranker — `ms-marco-minilm-l6` (p50≈245ms vs BGE's ≈5s on CPU) — trades a little recall for sub-second latency.
  26. **Run it yourself — and tell us what you get.** The harness is [plur-ai/plur-bench](https://github.com/plur-ai/plur-bench): CPU-runnable, no API key needed for the local path, corpus auto-fetched and SHA-verified. If you run it, we'd genuinely love to see your numbers — open an issue or discussion with your results, **especially if they don't match ours.** Independent reproduction is worth more than any number we publish, and we'll gladly credit you.
  27. **Retrieval ≠ answer accuracy — and we report them separately, never conflated.** End-to-end (LLM-judge) answer accuracy with the reranker stack is **60.5%**, versus **52.0%** for dumping full context into the prompt and **5.5%** with no memory at all.
  28. **Agent-task impact** — same task, with memory vs without: Haiku + PLUR outperforms Opus *without* it at roughly **10× less cost**; house rules **12–0** across Haiku, Sonnet, and Opus.
  29. **Operational** — local-first, zero-cost search, data-sovereign by design.
  30. *More in progress: LoCoMo, agentic task suites, cross-tool portability, decay / contradiction correctness.* [Full methodology →](https://plur.ai/benchmark.html)
  31. ## The idea
  32. You correct your agent's coding style on Monday. On Tuesday, it makes the same mistake. You explain your architecture in Cursor. That night, Claude Code has no idea.
  33. PLUR fixes this. Install it once, and corrections, preferences, and conventions persist — across sessions, tools, and machines. Your memory is stored as plain YAML on your disk. No cloud, no API calls, no black box.
  34. The interesting part: in our tool-routing and local-knowledge benchmark, **Haiku with PLUR memory outperformed Opus without it** — 2.6x better on tool routing, at roughly 10x less cost. Turns out the bottleneck isn't model intelligence. It's context.
  35. **The model is rented; your memory is owned.** Swap Haiku for Opus for whatever ships next month — the reasoning is a commodity you don't control. The part that's *yours* — everything the agent has learned about your work, your corrections, your conventions — shouldn't live in someone else's cloud or be baked into weights you can't read. PLUR keeps it in plain files on your disk, in an open format you can inspect, correct, and delete. That's what owning your intelligence actually means.
  36. ## Install
  37. Requires **Node.js 20 or newer**. Install both packages so editor configurations can use the installed MCP server:
  38. ```bash
  39. npm install -g @plur-ai/cli@latest @plur-ai/mcp@latest
  40. plur init
  41. plur doctor
  42. ```
  43. Restart your editor after setup. `plur doctor` checks the configuration and MCP handshake, and downloads the search model if it is missing and downloads are allowed. Search runs locally after that download; without the model it falls back to keyword search.
  44. ### Tell your agent
  45. ```text
  46. Set up PLUR memory for me: install @plur-ai/cli@latest and @plur-ai/mcp@latest globally, run `plur init`, then `plur doctor`. Show me any checks that fail.
  47. ```
  48. ### Claude Code
  49. `plur init` creates the local store at `~/.plur/`, registers the user-scoped MCP server in `~/.claude.json`, and writes global hooks to `~/.claude/settings.json`. A project `.mcp.json` is a separate project-scoped configuration; `~/.claude/mcp.json` is not the user-scoped registration path. The hooks inject memory and close session state when Claude Code emits `SessionEnd`. Run init again after upgrading PLUR to refresh its configuration.
  50. For **multi-project setups**, use domain/scope to separate knowledge:
  51. ```bash
  52. cd ~/projects/my-app
  53. plur init --domain myapp --scope project:my-app
  54. ```
  55. This creates a `.plur.yaml` in the project with defaults that hooks apply automatically. Engrams learned in that project are tagged; recall filters by scope but always includes global knowledge.
  56. **Set scope per engram, by content.** Scope is not a once-per-session setting — every `plur_learn` call takes its own `scope`, chosen from what the engram is about. Team/shared knowledge goes to a team scope (e.g. `group:<org>/<team>`, used by PLUR Enterprise); project details to `project:<name>`; personal preferences stay local. Don't let team-relevant knowledge fall back to `global` by omitting scope — `global` leaks into every project and (with a team store configured) never reaches the team. `plur_session_start` lists the remote scopes a token can write to.
  57. ### Upgrade
  58. ```bash
  59. npm install -g @plur-ai/cli@latest @plur-ai/mcp@latest
  60. plur init
  61. plur doctor
  62. ```
  63. Restart the editor so it launches the updated MCP server.
  64. ### Cursor
  65. From your project root:
  66. ```bash
  67. plur init --cursor
  68. ```
  69. This writes `.cursor/mcp.json`, `.cursor/hooks.json` and `.cursor/rules/plur-memory.mdc`. Cursor uses the reduced `cursor` tool profile: core tools are direct, and other operations are available through `plur_admin`. Call `plur_admin` with `{ "action": "help" }` to discover their current names and arguments.
  70. ### Codex
  71. ```bash
  72. plur init --codex
  73. ```
  74. Registers a new MCP server via `codex mcp add` in `~/.codex/config.toml`, writes lifecycle hooks to `~/.codex/hooks.json` (`CODEX_HOME` overrides the directory), and adds a PLUR section to `AGENTS.md`. Auto-detected when `~/.codex/` exists.
  75. To upgrade an existing Codex installation:
  76. ```bash
  77. npm install -g @plur-ai/cli@latest @plur-ai/mcp@latest
  78. plur init --codex
  79. plur doctor --codex
  80. ```
  81. Init updates recognized older PLUR launch pins in place, preserving environment settings, timeouts, tool policies and comments. It preserves newer pins and custom or HTTP servers. Use `--keep-codex-mcp` to retain an intentional older launch entry. Restart Codex after changing its configuration.
  82. For remote stores using `plur remote --token-env NAME`, both `remote` and `init --codex` add the required variable names to Codex's `env_vars`; they never copy token values into its config. The variable must also be available to the process that launches Codex. A variable exported in PowerShell does not prove that a separately launched desktop app inherited it.
  83. `plur doctor --codex` starts the MCP command from the Codex user config with Codex-style environment filtering, checks its reported version against the CLI, and reports missing token forwarding or values. It does not check project/profile overrides, another running application's environment, hook trust, or a remote write. `--no-handshake` reports the runtime as unverified and exits nonzero. Verify saving and recalling a test memory in the actual Codex session before treating desktop setup as complete. Native Windows and WSL2 have separate home directories and registrations; run setup in each environment you use.
  84. Injection uses hybrid search (BM25 + embeddings) with an automatic BM25 fallback if the embedder is slow or unavailable. Set `PLUR_HOOK_HYBRID=0` to force BM25 (applies to the Antigravity hooks too; `PLUR_CODEX_HYBRID` is honoured as an alias). `PLUR_HOOK_HYBRID_DEADLINE_MS` tunes the fallback deadline — keep it below your harness's hook timeout (Codex 25s, Antigravity 20s).
  85. **One manual step after install:** open Codex, run `/hooks`, and trust the PLUR entries. Codex fingerprints every hook and refuses to run untrusted ones — *silently*, with no warning and a zero exit code. Until you trust them, memory simply never loads. `plur doctor` says so too.
  86. ### OpenCode
  87. ```bash
  88. plur init --opencode
  89. plur doctor
  90. ```
  91. This adds the memory plugin and MCP tools to `~/.config/opencode/opencode.json`, or to the existing `opencode.jsonc` when no `.json` exists. `OPENCODE_CONFIG_DIR` takes precedence; otherwise `XDG_CONFIG_HOME/opencode` overrides the default directory.
  92. The MCP command uses Node and the installed `@plur-ai/mcp` entry when available. Init updates an older exact `@plur-ai/opencode` pin to the plugin version shipped with the CLI while preserving comments, formatting and unrelated settings. Newer pins, tags and unpinned entries remain unchanged. Use `--keep-opencode-plugin` to retain an intentional old pin. Restart OpenCode to load the changed configuration. [Plugin details](packages/opencode/README.md).
  93. ### Which integration you get
  94. Every MCP client can call PLUR's tools. Only some have an *adapter* — the hooks
  95. and always-on context that make memory load automatically instead of waiting for
  96. the agent to think of it. Without one, recall and learning depend entirely on the
  97. model choosing to call the tools, which degrades badly under context pressure.
  98. | Harness | Tools | Auto-injection + enforcement |
  99. |---|---|---|
  100. | Claude Code | ✅ | ✅ hooks + `CLAUDE.md` |
  101. | Codex | ✅ | ✅ hooks + `AGENTS.md` (trust `/hooks` once) |
  102. | Cursor | ✅ | ✅ hooks + rules |
  103. | OpenCode | ✅ | ✅ memory plugin + MCP tools |
  104. | OpenClaw | ✅ | ✅ ContextEngine plugin |
  105. | Hermes | ✅ | ✅ plugin |
  106. | Antigravity CLI (`agy`) | ✅ | ✅ hooks + `AGENTS.md` |
  107. | Windsurf, Gemini CLI, other MCP clients | ✅ | ❌ tools only |
  108. If your harness is in the last row, paste the PLUR section from `CLAUDE.md` into
  109. its own context file (`AGENTS.md`, `GEMINI.md`, …) as an interim measure — that
  110. restores the instruction layer, though not automatic injection.
  111. ### Antigravity CLI (agy)
  112. ```bash
  113. plur init --antigravity
  114. ```
  115. Writes hooks and the MCP server into agy's global config (`~/.gemini/config/`) and adds a PLUR section to `AGENTS.md`. Auto-detected when `~/.gemini/antigravity-cli/` exists. No trust step — agy runs configured hooks on first invocation; just restart agy.
  116. Antigravity has no session-start event and no per-prompt hook, so PLUR drives everything from `PreInvocation`: per-prompt recall is read from the conversation transcript, and the turn's memory is re-injected as an ephemeral message on every model invocation so it survives tool calls without accumulating in history.
  117. Gemini CLI users: Google is transitioning Gemini CLI to Antigravity — install `agy` and run the command above. Gemini CLI itself remains tools-only.
  118. ### OpenClaw
  119. ```bash
  120. openclaw plugins install @plur-ai/claw
  121. openclaw config set plur.enabled true
  122. ```
  123. That's it. PLUR works in the background from here. No workflow changes needed — just use your tools as usual. Corrections accumulate automatically.
  124. ### DeepSeek Harness
  125. ```bash
  126. dsh plugin add @plur-ai/dsh
  127. ```
  128. Native, not an MCP bridge. PLUR mounts as a Cordis plugin and writes your
  129. engrams straight into the system prompt, so the model reads them the way it
  130. reads its own instructions — no tool call, no round trip, and no turn spent
  131. deciding whether to look. The section is re-rendered on each assembly rather
  132. than appended, so memory does not accumulate in the context as a session runs.
  133. Five tools (`plur_recall`, `plur_learn`, `plur_forget`, `plur_feedback`,
  134. `plur_status`) are still registered for when the agent wants to reach for
  135. memory deliberately. Scope defaults closed — each workspace gets its own,
  136. resolved from its `.plur.yaml`.
  137. `/plur` reports status; `/plur-memory` opens the memory viewer below.
  138. ### Hermes Agent
  139. ```bash
  140. pip install plur-hermes
  141. npm install -g @plur-ai/cli
  142. ```
  143. The plugin registers automatically via Hermes' plugin system. It injects relevant memories before each LLM call, extracts learnings from agent responses, and exposes all PLUR tools to the agent. Hermes shells out to the PLUR CLI.
  144. ### Python SDK (LangChain, llama.cpp, scripts)
  145. For Python environments that aren't Hermes:
  146. ```bash
  147. pip install "plur-ai @ git+https://github.com/plur-ai/plur.git#subdirectory=packages/python"
  148. npm install -g @plur-ai/cli # bridge (required)
  149. ```
  150. > **Note:** `plur-ai` is not yet on PyPI — use the git install above until [#915](https://github.com/plur-ai/plur/issues/915) is resolved.
  151. ```python
  152. from plur_ai import Plur
  153. plur = Plur()
  154. plur.learn("always use async generators for streaming LLM output")
  155. results = plur.recall("streaming patterns")
  156. context = plur.inject("write a streaming endpoint", limit=10)
  157. ```
  158. `plur-ai` bridges to the same on-disk store as Claude Code and OpenClaw — memory written from Python is immediately visible across all your tools. See [`packages/python/examples/`](packages/python/examples/) for LangChain and llama.cpp integration examples.
  159. ### Verify it works
  160. Run `plur doctor`, then ask your agent to call `plur_status` and show its engram count and storage path. The default lean MCP profile exposes core tools directly; use `plur_admin` with `{ "action": "help" }` for the remaining operations and their schemas.
  161. ### Read your memory
  162. ```bash
  163. plur dashboard
  164. ```
  165. Opens a local page listing every engram: what was learned, what actually gets
  166. recalled, and how often. Read-only, loopback-only, and served from your own
  167. machine — nothing is uploaded. `--port` moves it, `--no-open` skips the
  168. browser. Inside DeepSeek Harness the same page is one `/plur-memory` away.
  169. Available in English and 中文; it follows your browser, or `?lang=zh`.
  170. ### See it in action
  171. Once it's running, teach your agent something once:
  172. > *"Always use `pnpm` in this project — `npm install` breaks the lockfile in CI."*
  173. Start a new session the next day and ask:
  174. ```
  175. You: How do I run the tests?
  176. <plur-memory> 1 engram · project:my-api </plur-memory>
  177. Agent: Use pnpm — you mentioned npm breaks the lockfile in CI:
  178. pnpm test # full suite
  179. pnpm test -- src/auth.test.ts # single file
  180. ```
  181. New session. No reminder. The correction was there.
  182. That's the moment PLUR pays off — the agent remembers a project convention you mentioned once, without it being in any file it can read.
  183. ## How it works
  184. PLUR has two storage primitives:
  185. **[Engrams](https://plur.ai/spec.html)** — learned knowledge that persists across sessions. Each engram is a typed assertion ("always use blue-green deploys", "never force-push to main") with:
  186. - **Activation** — retrieval strength that decays over time (ACT-R model) and strengthens on access. Stale facts naturally fade from injection without manual cleanup.
  187. - **Feedback signals** — positive/negative ratings that train injection quality over time
  188. - **Scope** — hierarchical namespace (`global`, `project:myapp`, `cluster:prod`, `service:api`) controlling where the engram applies
  189. - **Polarity** — automatic classification of "do" vs "don't" rules, so constraints are injected separately from directives
  190. - **Associations** — links to other engrams, including co-access edges that form automatically when engrams are recalled together
  191. **Episodes** — timestamped event records for "what happened when." Each episode captures a summary, timestamp, agent attribution, and channel. Use episodes for incident timelines, session logs, and operational history. Query by time range, agent, or channel.
  192. ```
  193. You correct your agent → engram created → YAML on your disk
  194. Agent fixes an incident → episode captured → timeline searchable
  195. Next session starts → relevant engrams injected → agent remembers
  196. You rate the result → engram strengthens or decays → quality improves
  197. Unused engrams → activation decays → naturally fade from injection
  198. ```
  199. Search is fully local: BM25 (with IDF weighting, TF saturation, length normalization) + BGE embeddings + Reciprocal Rank Fusion. Zero API calls, zero per-query cost. [Benchmark methodology →](https://plur.ai/benchmark.html)
  200. Plugins (OpenClaw, Hermes) automatically capture learnings from agent conversations — no manual saving needed. The agent's corrections become engrams without you doing anything.
  201. See the [full engram spec](https://plur.ai/spec.html) for schema details, activation model, and injection algorithm.
  202. ## Open format
  203. The engram is an **open, versioned format** — not a black box. Every engram is plain YAML validated against a published [JSON Schema](https://plur.ai/spec.html), generated from the same Zod source the engine uses (the schemas live in [`spec/`](spec/)). Read it, diff it in git, write your own tooling against it, or build a different engine on the same format — your memory isn't locked to PLUR.
  204. ## Usage
  205. ```typescript
  206. import { Plur } from '@plur-ai/core'
  207. const plur = new Plur()
  208. // Learn from a correction. The engine's read and write methods are async —
  209. // they return promises so a `Plur` can be backed by a network store as well
  210. // as by the default local YAML one.
  211. await plur.learn('toEqual() in Vitest is strict — use toMatchObject() for partial matching', {
  212. type: 'behavioral',
  213. scope: 'project:my-app',
  214. domain: 'dev/testing'
  215. })
  216. // Recall (hybrid: BM25 + embeddings, zero cost)
  217. const results = await plur.recallHybrid('vitest assertion matching')
  218. // Inject relevant engrams into agent context. You get context blocks ready to
  219. // paste into a prompt plus the IDs that went into them — not the engrams
  220. // themselves. `budget` is the ceiling in tokens; selection fills it by relevance.
  221. const injection = await plur.inject('Write tests for the user service', {
  222. scope: 'project:my-app',
  223. budget: 2000
  224. })
  225. console.log(injection.directives) // also .constraints, .consider
  226. console.log(`${injection.count} engrams, ${injection.tokens_used} tokens`)
  227. // Feedback trains the system — rate anything you have an ID for, whether it came
  228. // back from recall or went out in an injection (injection.injected_ids).
  229. if (results[0]) await plur.feedback(results[0].id, 'positive')
  230. // Capture an event (episode). Episode operations stay synchronous — they are
  231. // backed by episodes.yaml, not the engram primary store.
  232. plur.capture('Fixed CrashLoopBackOff on bee-3-4 by increasing memory limits', {
  233. agent: 'claude-code',
  234. channel: 'terminal'
  235. })
  236. // Query timeline
  237. const incidents = plur.timeline({ agent: 'claude-code' })
  238. // Sync across machines (use a private git remote — all engrams including private-visibility ones are pushed)
  239. await plur.sync('git@github.com:you/plur-memory.git')
  240. ```
  241. ## Tools
  242. | Tool | What it does |
  243. |------|-------------|
  244. | `plur_learn` | Store a correction, preference, or convention |
  245. | `plur_learn_batch` | Store many engrams in one call (batch dedup + per-item failure isolation) |
  246. | `plur_recall` | Retrieve relevant memories — hybrid (BM25 + embeddings) by default; `mode:"keyword"` for BM25-only |
  247. | `plur_inject_hybrid` | Select engrams for current task within token budget |
  248. | `plur_feedback` | Rate relevance (trains quality over time) |
  249. | `plur_forget` | Retire a memory (activation decays, eventually pruned) |
  250. | `plur_rescope` | Move an existing engram to another scope — personal → team, or back |
  251. | `plur_session_scope` | Change the session's default write scope mid-session |
  252. | `plur_capture` | Record an event — incident, resolution, session milestone |
  253. | `plur_timeline` | Query episode history by time, agent, or channel |
  254. | `plur_ingest` | Extract engrams from text automatically |
  255. | `plur_sync` | Sync via git. `personal` remotes mirror everything (use a private repo); `shared` remotes receive only shared-scope, non-private engrams |
  256. | `plur_status` | Check system health and engram counts |
  257. | `plur_receipt` | Counted, local report of what your memory retrieved for you |
  258. | `plur_outbox` | Inspect (and retry) team writes queued while their store was unreachable |
  259. ### The outbox
  260. A write to a team scope goes to that team's remote store. When the store cannot
  261. be reached — VPN off, server down, token expired — the engram is **not lost and
  262. not silently dropped**: it is written locally with queue metadata and retried on
  263. the next session start, on `plur sync`, or on demand.
  264. The queue is not a directory. It lives as `structured_data._outbox` inside the
  265. affected engrams in `engrams.yaml`, which is why it needs a command to see:
  266. ```
  267. plur outbox # what is queued, for which scope, how long, last error
  268. plur outbox --flush # retry now
  269. ```
  270. The same thing is available to agents as `plur_outbox` (`{flush: true}` to
  271. retry), and `plur status` reports the pending count. Neither surface prints the
  272. target URL or the token.
  273. ## The folder map
  274. `~/.plur/folders.yaml` records what PLUR does in each folder, and every
  275. integration follows it:
  276. | Setting | What it does |
  277. |---|---|
  278. | `plur: on` | Memory works here as usual |
  279. | `plur: off` | PLUR does nothing here |
  280. | `plur: ask` | Ask once per session |
  281. | `scope: <s>` | Default scope for memories saved here |
  282. | `trusted: true` | This folder's `.plur.yaml` may set its scope and team server |
  283. | `plur: remote-only` + `scope: <s>` | Memories go only to the team server, in `<s>`; your personal memories are neither read nor written there (see the docs for what stays on disk) |
  284. ```
  285. plur folders set ~/client-work --remote-only --scope group:acme/client
  286. plur folders set ~/private --off
  287. plur folders list
  288. ```
  289. The file starts with a commented example of every setting, and the CLI keeps
  290. your comments and order when it writes. Details, including exactly what a
  291. remote-only folder refuses and what happens when the team server is down:
  292. [docs/folder-map.md](docs/folder-map.md).
  293. ## The memory receipt
  294. `plur receipt` (and the `plur_receipt` MCP tool) show what your memory actually did — counted from PLUR's own retrieval history, never estimated:
  295. ```
  296. Your Memory Receipt
  297. ===================
  298. 2026-07-03 .. 2026-07-22 (71 sessions)
  299. 423 times a memory you taught PLUR
  300. was put in front of the model.
  301. (plus 45 times an installed-pack memory)
  302. across 71 retrievals in 71 sessions
  303. drawing on 162 distinct engrams
  304. MOST-RELIED-ON
  305. 34x PLUR positioning thesis across every vertical: PLUR layers …
  306. 28x Datacore app CoS architecture: reasoning layer added on to…
  307. ...
  308. STORE HEALTH
  309. 4,517 engrams stored (you: 3,746, packs: 771)
  310. 162 retrieved at least once (4% of store)
  311. 4,355 not retrieved since 2026-07-03 (96%)
  312. Over a short logging window a low rate is expected, not a fault —
  313. memory is meant to be selective, and much of the store predates logging.
  314. ```
  315. (REUSE stats and coverage caveats are also shown; trimmed here for length.)
  316. It is local and read-only, and carries **no dollar or token figure by design**: on a subscription your marginal token cost is zero, and the value of an avoided rediscovery is not measurable from this data. The receipt reports only what it can count. Activation rate is store *coverage over the logging window*, not a quality score — it is naturally low and falls as you add engrams. `--days N` narrows the window; `--json` emits the raw shape. (The `plur_receipt` MCP tool returns the same figures plus a one-line `summary` that carries this framing to the agent.)
  317. ## Syncing across devices
  318. `plur.sync(remote)` is git underneath: it commits your engram store and pushes it to the remote you give it. What gets pushed depends on the remote's declared type (`sync.remote_type` in `config.yaml`, or the `remote_type` argument):
  319. - **`personal`** (default) — your own backup/mirror across your machines. The remote receives everything that is pushed, **including `visibility: private` engrams**: private visibility means "don't share this in a pack", not "don't mirror it to my own devices", so private engrams intentionally follow you from machine to machine. Because of that, **always use a private git remote** (a private GitHub/GitLab repo, or your own server). PLUR surfaces a `warning` in the sync result whenever private engrams are present. Never point a personal sync at a public repository.
  320. - **`shared`** — a team-visible remote. Only engrams with a **shared-family scope** (`group:`/`project:`/`space:`/`team:`/`org:`/`public`) **and a non-private visibility** are pushed; personal-family engrams (`local`, `global`, `user:*`, `agent:*`) and private-visibility engrams never reach the remote, by construction. Note the default visibility is `private`, so a shared remote receives only engrams whose visibility was set deliberately — teammates get what you chose to share, nothing else. The same guarantee covers the sibling store files (#686): an episode, candidate, or tension record is pushed only when every engram it references is itself in the push set — records derived from personal or private engrams (a tension's statement snapshots, a failure-report episode) stay local, as does any record referencing an engram the filter cannot resolve.
  321. In both modes **`scope: local` engrams** are machine-specific by design (paths, local ports, per-host quirks), so they are stripped from every commit and never reach any remote. Stripping happens on the *staged blob*: your local working copy always keeps every engram.
  322. ## Benchmark details
  323. Per-category retrieval recall, from an **earlier in-repo run** — full
  324. LongMemEval-S (N=500), fully local (BGE-small + BGE-reranker-v2-m3, chunk
  325. granularity). Its overall figure (98.0%) predates the current plur-bench
  326. measurement of the same stack (97.6%) and has not been re-run per category;
  327. treat the shape as indicative and the headline table above as current.
  328. | Category | R@5 | R@10 |
  329. |----------|-----|------|
  330. | single-session-assistant | 100.0% | 100.0% |
  331. | knowledge-update | 100.0% | 100.0% |
  332. | single-session-user | 98.6% | 100.0% |
  333. | multi-session | 98.5% | 100.0% |
  334. | temporal-reasoning | 97.7% | 98.5% |
  335. | single-session-preference | 86.7% | 90.0% |
  336. | **overall** | **98.0%** | **99.0%** |
  337. Retrieval recall (finding the right memory) and end-to-end answer accuracy (whether the model then answers correctly) are **different axes** — PLUR measures and reports them separately, never conflated. The agent-impact figures above come from a same-task A/B run (memory vs none).
  338. [Full methodology →](https://plur.ai/benchmark.html)
  339. ## PLUR vs other agent-memory tools
  340. Mem0, Letta (MemGPT), and Zep solve real problems — a drop-in memory API (Mem0), a self-managing agent OS (Letta), a temporal knowledge graph (Zep). PLUR's bet is a combination none of them ship together:
  341. - **Plain-text you own** — engrams are human-readable YAML you can read, `git diff`, edit, and provably delete. Not opaque vectors, agent-state blocks, or graph nodes you need tooling to inspect.
  342. - **Local-first, zero-cost** — hybrid BM25 + local embeddings, fully offline, no API bill (98% R@5 on the full LongMemEval-S corpus with no cloud call — see above).
  343. - **Team-shareable via git** — `plur sync` is git underneath, so the same memory follows you across machines *and* across a team. Most tools are single-user-local *or* cloud-team; PLUR is both, and you keep the data.
  344. - **Cross-tool** — the same `~/.plur/` store works in Claude Code, Cursor, Windsurf, OpenClaw, and Hermes. Your memory isn't trapped in one vendor.
  345. - **It learns and forgets** — feedback-trained retrieval with ACT-R decay and an on-demand contradiction scan, not a grow-forever store.
  346. If you need a hosted memory API or a temporal knowledge graph, use the tool built for that. If you want memory you can **read, own, share with your team, and move between tools**, that's PLUR. Side-by-side detail: [comparisons/](comparisons/).
  347. ## What PLUR is — and isn't
  348. PLUR is **agent memory** — it stores corrections, preferences, conventions, and architectural decisions that an AI agent learns during work sessions, and injects them back when they're relevant.
  349. PLUR is **not** a general-purpose search engine, a codebase indexer, or a replacement for code intelligence tools. It doesn't parse ASTs, navigate class hierarchies, or search your source files. If you need code-aware search (tree-sitter, language server features, symbol lookup), tools like [claude-mem](https://github.com/skydeckai/claude-mem) or your IDE's built-in search are the right choice.
  350. The two are complementary:
  351. | | PLUR | Code intelligence tools |
  352. |---|------|------------------------|
  353. | **Stores** | Learned knowledge (engrams) + event timeline (episodes) | Code structure, symbols, definitions |
  354. | **Search** | Engram recall (BM25 + embeddings over memory) | AST traversal, symbol lookup, semantic code search |
  355. | **Learns** | From agent corrections, feedback, usage patterns | From static analysis of source code |
  356. | **Captures** | Auto-extracts learnings from conversations (via plugins) | N/A |
  357. | **Decays** | Yes — unused memories fade (ACT-R model) | No — code index reflects current state |
  358. | **Timeline** | Episodes track what happened when (incidents, fixes, decisions) | Git log only |
  359. | **Cross-tool** | Any MCP client (Claude Code, Cursor, Windsurf, OpenClaw, Hermes) | Typically tied to one tool |
  360. While search is a core part of PLUR (finding the right engram to inject), the search targets are always engrams — not files, not code, not documents. PLUR's hybrid search (BM25 + embeddings + RRF) is optimized for short natural-language assertions, not source code.
  361. ## Packages
  362. | Package | Description |
  363. |---------|-------------|
  364. | [`@plur-ai/core`](packages/core) | Engram engine — learn, recall, inject, search, decay |
  365. | [`@plur-ai/mcp`](packages/mcp) | MCP server for Claude Code, Cursor, Windsurf |
  366. | [`@plur-ai/claw`](packages/claw) | OpenClaw ContextEngine plugin |
  367. | [`@plur-ai/cli`](packages/cli) | CLI — plur learn / recall / inject / status |
  368. | [`@plur-ai/dsh`](packages/dsh) | DeepSeek Harness plugin — engrams in the prompt, no tool call |
  369. | [`@plur-ai/opencode`](packages/opencode) | opencode plugin — engrams in the prompt, no tool call |
  370. | [`@plur-ai/migrate`](packages/migrate) | Store migrations, shipped with the release they migrate to |
  371. | [`plur-hermes`](packages/hermes) | Hermes Agent plugin (Python, via CLI bridge) |
  372. | [`plur-ai`](packages/python) | Python SDK — learn/recall/inject for LangChain, llama.cpp, scripts |
  373. | [`plur-langchain`](packages/langchain) | LangChain BaseMemory + BaseChatMessageHistory adapter |
  374. `packages/ui` is internal — the memory viewer's pages, bundled into the CLI and
  375. the DeepSeek Harness plugin rather than published. It is not on npm.
  376. ## Architecture
  377. ```
  378. @plur-ai/core
  379. ├── engrams.ts Engram CRUD + YAML persistence
  380. ├── episodes.ts Episode capture + timeline queries
  381. ├── fts.ts BM25 with IDF, TF saturation (k1/b), length normalization
  382. ├── embeddings.ts BGE-small-en-v1.5, 384-dim, local ONNX
  383. ├── hybrid-search.ts Reciprocal Rank Fusion
  384. ├── inject.ts Context-aware selection + spreading activation
  385. ├── decay.ts ACT-R activation decay
  386. ├── secrets.ts Secret detection (API keys, passwords, tokens)
  387. ├── sync.ts Git-based sync + file locking (O_EXCL)
  388. ├── storage.ts Path detection + YAML I/O
  389. └── storage-indexed.ts Optional SQLite read index
  390. @plur-ai/mcp Wraps core as MCP tools
  391. @plur-ai/claw OpenClaw ContextEngine hooks (assemble/compact/afterTurn)
  392. plur-hermes Python plugin for Hermes Agent (auto inject/learn)
  393. plur-ai Python SDK — direct learn/recall/inject for scripts and frameworks
  394. ```
  395. ### Storage
  396. Everything is plain YAML. Open it, read it, edit it.
  397. ```
  398. ~/.plur/
  399. ├── engrams.yaml # learned knowledge (source of truth)
  400. ├── episodes.yaml # session timeline
  401. ├── config.yaml # settings
  402. └── engrams.db # optional SQLite read index (auto-generated)
  403. ```
  404. `PLUR_PATH` overrides the default location.
  405. ### Who wrote this engram
  406. Every engram records the actor that wrote it, in `provenance.origin`. Set the
  407. identity for this machine in `config.yaml`:
  408. ```yaml
  409. provenance:
  410. identity: agent:claude-code # agent:<name> — one per writing actor
  411. ```
  412. With no identity configured, engrams are stamped `agent:unidentified`. That is
  413. recorded honestly rather than guessed, so a store written by several actors
  414. still shows that it was — but the attribution is only useful once each writer
  415. names itself. `plur status` reports the value in effect.
  416. For a store several agents write to (a shared team store, or one machine
  417. running an MCP server alongside a CLI), give each writer its own identity.
  418. Indexing is on by default (`index: true`) and the backend is chosen from the
  419. size of your store, so there is normally nothing to configure:
  420. | Store size | Backend | What answers a query |
  421. |---|---|---|
  422. | under 5,000 engrams | `yaml` | in-memory BM25 + exact cosine |
  423. | 5,000 and up | `pglite` | embedded Postgres + pgvector |
  424. | 50,000 and up | `postgres` | a Postgres server you point it at — BM25 in SQL; semantic recall scores in memory (see below) |
  425. YAML stays the source of truth in every tier except `postgres` (ADR-0001,
  426. ADR-0005) — the index is a cache that rebuilds automatically, and you can delete
  427. it anytime. Set `backend:` in `config.yaml` to pin a tier explicitly.
  428. One caveat on the `postgres` tier, stated here because it is this table's
  429. headline row: **core does not write embeddings to a Postgres primary store**
  430. (ADR-0005 amendment). Keyword/BM25 recall runs in SQL, but `engram_embeddings`
  431. stays empty unless your deployment populates it, so semantic and hybrid recall
  432. fall back to loading engrams and scoring in memory — correct results, at the
  433. O(N) cost this tier otherwise avoids. The adapter says so once at schema init;
  434. `vectorIndex: 'exact'` acknowledges and silences it.
  435. `sqlite` (`engrams.db`, via `better-sqlite3`) is the legacy index and is no
  436. longer selected automatically.
  437. ## Requirements
  438. - **Node.js 22+** (22.21+ or 24+ behind an HTTPS proxy, with `NODE_USE_ENV_PROXY=1`)
  439. - **2GB RAM minimum** — the embedding model (ONNX runtime) needs ~1GB for installation. On servers with less RAM, embeddings are skipped and search falls back to BM25 keyword matching.
  440. ## Development
  441. ```bash
  442. git clone https://github.com/plur-ai/plur.git
  443. cd plur
  444. pnpm install && pnpm build && pnpm test
  445. ```
  446. ~3500 tests across ~200 files. `pnpm test:watch` for development.
  447. ## Contributing
  448. - **Bug reports** — issue with reproduction steps
  449. - **Feature requests** — issue describing the use case
  450. - **Code** — fork, branch, PR. Tests required.
  451. - **Integrations** — build PLUR support for other tools
  452. Before submitting: `pnpm test` passes, `pnpm build` succeeds, no new external deps in core without discussion.
  453. Conventions: TypeScript, Zod validation, Vitest, no external APIs in core, YAML storage, zero-cost search by default.
  454. ## License
  455. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.