Skip to main content
Glama
PLUR Memory

PLUR Memory

Official

PLUR — Your agents share the same memory

MCP Toplist

npm version CI License: Apache-2.0 GitHub stars Glama score

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.

plur.ai · Benchmark · Engram Spec · npm · Comparisons

Benchmarks

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.

Retrieval recall — full LongMemEval-S (N=500), R@5, fully local:

Stack

R@5

Notes

BM25 only

92.2%

no embedder — fully airgapped

Hybrid (BGE-small, shipping default)

95.6%

local embedder; one-time model download

+ BGE-reranker-v2-m3

97.6%

local cross-encoder, max quality — opt-in, ≈5s p50 on CPU

Numbers come from plur-ai/plur-bench, which is the source of truth for every benchmark figure PLUR publishes. Where an in-repo number and a plur-bench number disagree, plur-bench wins — it is the reproducible harness, and it is what CI regression-checks.

Chunk granularity, canonical-doc scoring, corpus SHA256 pinned — reproduce it in 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.

Run it yourself — and tell us what you get. The harness is 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.

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.

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.

Operational — local-first, zero-cost search, data-sovereign by design.

More in progress: LoCoMo, agentic task suites, cross-tool portability, decay / contradiction correctness. Full methodology →

Related MCP server: Memryzed

The idea

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.

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.

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.

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.

Install

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.

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.

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).

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.

OpenCode

plur init --opencode
plur doctor

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.

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.

Which integration you get

Every MCP client can call PLUR's tools. Only some have an adapter — the hooks and always-on context that make memory load automatically instead of waiting for the agent to think of it. Without one, recall and learning depend entirely on the model choosing to call the tools, which degrades badly under context pressure.

Harness

Tools

Auto-injection + enforcement

Claude Code

✅

✅ hooks + CLAUDE.md

Codex

✅

✅ hooks + AGENTS.md (trust /hooks once)

Cursor

✅

✅ hooks + rules

OpenCode

✅

✅ memory plugin + MCP tools

OpenClaw

✅

✅ ContextEngine plugin

Hermes

✅

✅ plugin

Antigravity CLI (agy)

✅

✅ hooks + AGENTS.md

Windsurf, Gemini CLI, other MCP clients

✅

❌ tools only

If your harness is in the last row, paste the PLUR section from CLAUDE.md into its own context file (AGENTS.md, GEMINI.md, …) as an interim measure — that restores the instruction layer, though not automatic injection.

Antigravity CLI (agy)

plur init --antigravity

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.

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.

Gemini CLI users: Google is transitioning Gemini CLI to Antigravity — install agy and run the command above. Gemini CLI itself remains tools-only.

OpenClaw

openclaw plugins install @plur-ai/claw
openclaw config set plur.enabled true

That's it. PLUR works in the background from here. No workflow changes needed — just use your tools as usual. Corrections accumulate automatically.

DeepSeek Harness

dsh plugin add @plur-ai/dsh

Native, not an MCP bridge. PLUR mounts as a Cordis plugin and writes your engrams straight into the system prompt, so the model reads them the way it reads its own instructions — no tool call, no round trip, and no turn spent deciding whether to look. The section is re-rendered on each assembly rather than appended, so memory does not accumulate in the context as a session runs.

Five tools (plur_recall, plur_learn, plur_forget, plur_feedback, plur_status) are still registered for when the agent wants to reach for memory deliberately. Scope defaults closed — each workspace gets its own, resolved from its .plur.yaml.

/plur reports status; /plur-memory opens the memory viewer below.

Hermes Agent

pip install plur-hermes
npm install -g @plur-ai/cli

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.

Python SDK (LangChain, llama.cpp, scripts)

For Python environments that aren't Hermes:

pip install "plur-ai @ git+https://github.com/plur-ai/plur.git#subdirectory=packages/python"
npm install -g @plur-ai/cli   # bridge (required)

Note: plur-ai is not yet on PyPI — use the git install above until #915 is resolved.

from plur_ai import Plur

plur = Plur()
plur.learn("always use async generators for streaming LLM output")
results = plur.recall("streaming patterns")
context = plur.inject("write a streaming endpoint", limit=10)

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/ for LangChain and llama.cpp integration examples.

Verify it works

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.

Read your memory

plur dashboard

Opens a local page listing every engram: what was learned, what actually gets recalled, and how often. Read-only, loopback-only, and served from your own machine — nothing is uploaded. --port moves it, --no-open skips the browser. Inside DeepSeek Harness the same page is one /plur-memory away.

Available in English and 中文; it follows your browser, or ?lang=zh.

See it in action

Once it's running, teach your agent something once:

"Always use pnpm in this project — npm install breaks the lockfile in CI."

Start a new session the next day and ask:

You: How do I run the tests?

<plur-memory> 1 engram · project:my-api </plur-memory>

Agent: Use pnpm — you mentioned npm breaks the lockfile in CI:

  pnpm test                           # full suite
  pnpm test -- src/auth.test.ts       # single file

New session. No reminder. The correction was there.

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.

How it works

PLUR has two storage primitives:

Engrams — learned knowledge that persists across sessions. Each engram is a typed assertion ("always use blue-green deploys", "never force-push to main") with:

  • Activation — retrieval strength that decays over time (ACT-R model) and strengthens on access. Stale facts naturally fade from injection without manual cleanup.

  • Feedback signals — positive/negative ratings that train injection quality over time

  • Scope — hierarchical namespace (global, project:myapp, cluster:prod, service:api) controlling where the engram applies

  • Polarity — automatic classification of "do" vs "don't" rules, so constraints are injected separately from directives

  • Associations — links to other engrams, including co-access edges that form automatically when engrams are recalled together

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.

You correct your agent  →  engram created  →  YAML on your disk
Agent fixes an incident →  episode captured →  timeline searchable
Next session starts     →  relevant engrams injected  →  agent remembers
You rate the result     →  engram strengthens or decays  →  quality improves
Unused engrams          →  activation decays  →  naturally fade from injection

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 →

Plugins (OpenClaw, Hermes) automatically capture learnings from agent conversations — no manual saving needed. The agent's corrections become engrams without you doing anything.

See the full engram spec for schema details, activation model, and injection algorithm.

Open format

The engram is an open, versioned format — not a black box. Every engram is plain YAML validated against a published JSON Schema, generated from the same Zod source the engine uses (the schemas live in 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.

Usage

import { Plur } from '@plur-ai/core'

const plur = new Plur()

// Learn from a correction. The engine's read and write methods are async —
// they return promises so a `Plur` can be backed by a network store as well
// as by the default local YAML one.
await plur.learn('toEqual() in Vitest is strict — use toMatchObject() for partial matching', {
  type: 'behavioral',
  scope: 'project:my-app',
  domain: 'dev/testing'
})

// Recall (hybrid: BM25 + embeddings, zero cost)
const results = await plur.recallHybrid('vitest assertion matching')

// Inject relevant engrams into agent context. You get context blocks ready to
// paste into a prompt plus the IDs that went into them — not the engrams
// themselves. `budget` is the ceiling in tokens; selection fills it by relevance.
const injection = await plur.inject('Write tests for the user service', {
  scope: 'project:my-app',
  budget: 2000
})
console.log(injection.directives)   // also .constraints, .consider
console.log(`${injection.count} engrams, ${injection.tokens_used} tokens`)

// Feedback trains the system — rate anything you have an ID for, whether it came
// back from recall or went out in an injection (injection.injected_ids).
if (results[0]) await plur.feedback(results[0].id, 'positive')

// Capture an event (episode). Episode operations stay synchronous — they are
// backed by episodes.yaml, not the engram primary store.
plur.capture('Fixed CrashLoopBackOff on bee-3-4 by increasing memory limits', {
  agent: 'claude-code',
  channel: 'terminal'
})

// Query timeline
const incidents = plur.timeline({ agent: 'claude-code' })

// Sync across machines (use a private git remote — all engrams including private-visibility ones are pushed)
await plur.sync('git@github.com:you/plur-memory.git')

Tools

Tool

What it does

plur_learn

Store a correction, preference, or convention

plur_learn_batch

Store many engrams in one call (batch dedup + per-item failure isolation)

plur_recall

Retrieve relevant memories — hybrid (BM25 + embeddings) by default; mode:"keyword" for BM25-only

plur_inject_hybrid

Select engrams for current task within token budget

plur_feedback

Rate relevance (trains quality over time)

plur_forget

Retire a memory (activation decays, eventually pruned)

plur_rescope

Move an existing engram to another scope — personal → team, or back

plur_session_scope

Change the session's default write scope mid-session

plur_capture

Record an event — incident, resolution, session milestone

plur_timeline

Query episode history by time, agent, or channel

plur_ingest

Extract engrams from text automatically

plur_sync

Sync via git. personal remotes mirror everything (use a private repo); shared remotes receive only shared-scope, non-private engrams

plur_status

Check system health and engram counts

plur_receipt

Counted, local report of what your memory retrieved for you

plur_outbox

Inspect (and retry) team writes queued while their store was unreachable

The outbox

A write to a team scope goes to that team's remote store. When the store cannot be reached — VPN off, server down, token expired — the engram is not lost and not silently dropped: it is written locally with queue metadata and retried on the next session start, on plur sync, or on demand.

The queue is not a directory. It lives as structured_data._outbox inside the affected engrams in engrams.yaml, which is why it needs a command to see:

plur outbox            # what is queued, for which scope, how long, last error
plur outbox --flush    # retry now

The same thing is available to agents as plur_outbox ({flush: true} to retry), and plur status reports the pending count. Neither surface prints the target URL or the token.

The folder map

~/.plur/folders.yaml records what PLUR does in each folder, and every integration follows it:

Setting

What it does

plur: on

Memory works here as usual

plur: off

PLUR does nothing here

plur: ask

Ask once per session

scope: <s>

Default scope for memories saved here

trusted: true

This folder's .plur.yaml may set its scope and team server

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)

plur folders set ~/client-work --remote-only --scope group:acme/client
plur folders set ~/private --off
plur folders list

The file starts with a commented example of every setting, and the CLI keeps your comments and order when it writes. Details, including exactly what a remote-only folder refuses and what happens when the team server is down: docs/folder-map.md.

The memory receipt

plur receipt (and the plur_receipt MCP tool) show what your memory actually did — counted from PLUR's own retrieval history, never estimated:

Your Memory Receipt
===================
  2026-07-03 .. 2026-07-22  (71 sessions)

  423 times a memory you taught PLUR
  was put in front of the model.
  (plus 45 times an installed-pack memory)

  across 71 retrievals in 71 sessions
  drawing on 162 distinct engrams

  MOST-RELIED-ON
      34x  PLUR positioning thesis across every vertical: PLUR layers …
      28x  Datacore app CoS architecture: reasoning layer added on to…
      ...

  STORE HEALTH
       4,517   engrams stored (you: 3,746, packs: 771)
         162   retrieved at least once (4% of store)
       4,355   not retrieved since 2026-07-03 (96%)
    Over a short logging window a low rate is expected, not a fault —
    memory is meant to be selective, and much of the store predates logging.

(REUSE stats and coverage caveats are also shown; trimmed here for length.)

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.)

Syncing across devices

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):

  • 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.

  • 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.

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.

Benchmark details

Per-category retrieval recall, from an earlier in-repo run — full LongMemEval-S (N=500), fully local (BGE-small + BGE-reranker-v2-m3, chunk granularity). Its overall figure (98.0%) predates the current plur-bench measurement of the same stack (97.6%) and has not been re-run per category; treat the shape as indicative and the headline table above as current.

Category

R@5

R@10

single-session-assistant

100.0%

100.0%

knowledge-update

100.0%

100.0%

single-session-user

98.6%

100.0%

multi-session

98.5%

100.0%

temporal-reasoning

97.7%

98.5%

single-session-preference

86.7%

90.0%

overall

98.0%

99.0%

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).

Full methodology →

PLUR vs other agent-memory tools

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:

  • 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.

  • 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).

  • 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.

  • Cross-tool — the same ~/.plur/ store works in Claude Code, Cursor, Windsurf, OpenClaw, and Hermes. Your memory isn't trapped in one vendor.

  • It learns and forgets — feedback-trained retrieval with ACT-R decay and an on-demand contradiction scan, not a grow-forever store.

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/.

What PLUR is — and isn't

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.

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 or your IDE's built-in search are the right choice.

The two are complementary:

PLUR

Code intelligence tools

Stores

Learned knowledge (engrams) + event timeline (episodes)

Code structure, symbols, definitions

Search

Engram recall (BM25 + embeddings over memory)

AST traversal, symbol lookup, semantic code search

Learns

From agent corrections, feedback, usage patterns

From static analysis of source code

Captures

Auto-extracts learnings from conversations (via plugins)

N/A

Decays

Yes — unused memories fade (ACT-R model)

No — code index reflects current state

Timeline

Episodes track what happened when (incidents, fixes, decisions)

Git log only

Cross-tool

Any MCP client (Claude Code, Cursor, Windsurf, OpenClaw, Hermes)

Typically tied to one tool

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.

Packages

Package

Description

@plur-ai/core

Engram engine — learn, recall, inject, search, decay

@plur-ai/mcp

MCP server for Claude Code, Cursor, Windsurf

@plur-ai/claw

OpenClaw ContextEngine plugin

@plur-ai/cli

CLI — plur learn / recall / inject / status

@plur-ai/dsh

DeepSeek Harness plugin — engrams in the prompt, no tool call

@plur-ai/opencode

opencode plugin — engrams in the prompt, no tool call

@plur-ai/migrate

Store migrations, shipped with the release they migrate to

plur-hermes

Hermes Agent plugin (Python, via CLI bridge)

plur-ai

Python SDK — learn/recall/inject for LangChain, llama.cpp, scripts

plur-langchain

LangChain BaseMemory + BaseChatMessageHistory adapter

packages/ui is internal — the memory viewer's pages, bundled into the CLI and the DeepSeek Harness plugin rather than published. It is not on npm.

Architecture

@plur-ai/core
├── engrams.ts           Engram CRUD + YAML persistence
├── episodes.ts          Episode capture + timeline queries
├── fts.ts               BM25 with IDF, TF saturation (k1/b), length normalization
├── embeddings.ts        BGE-small-en-v1.5, 384-dim, local ONNX
├── hybrid-search.ts     Reciprocal Rank Fusion
├── inject.ts            Context-aware selection + spreading activation
├── decay.ts             ACT-R activation decay
├── secrets.ts           Secret detection (API keys, passwords, tokens)
├── sync.ts              Git-based sync + file locking (O_EXCL)
├── storage.ts           Path detection + YAML I/O
└── storage-indexed.ts   Optional SQLite read index

@plur-ai/mcp          Wraps core as MCP tools
@plur-ai/claw          OpenClaw ContextEngine hooks (assemble/compact/afterTurn)
plur-hermes            Python plugin for Hermes Agent (auto inject/learn)
plur-ai                Python SDK — direct learn/recall/inject for scripts and frameworks

Storage

Everything is plain YAML. Open it, read it, edit it.

~/.plur/
├── engrams.yaml     # learned knowledge (source of truth)
├── episodes.yaml    # session timeline
├── config.yaml      # settings
└── engrams.db       # optional SQLite read index (auto-generated)

PLUR_PATH overrides the default location.

Who wrote this engram

Every engram records the actor that wrote it, in provenance.origin. Set the identity for this machine in config.yaml:

provenance:
  identity: agent:claude-code    # agent:<name> — one per writing actor

With no identity configured, engrams are stamped agent:unidentified. That is recorded honestly rather than guessed, so a store written by several actors still shows that it was — but the attribution is only useful once each writer names itself. plur status reports the value in effect.

For a store several agents write to (a shared team store, or one machine running an MCP server alongside a CLI), give each writer its own identity.

Indexing is on by default (index: true) and the backend is chosen from the size of your store, so there is normally nothing to configure:

Store size

Backend

What answers a query

under 5,000 engrams

yaml

in-memory BM25 + exact cosine

5,000 and up

pglite

embedded Postgres + pgvector

50,000 and up

postgres

a Postgres server you point it at — BM25 in SQL; semantic recall scores in memory (see below)

YAML stays the source of truth in every tier except postgres (ADR-0001, ADR-0005) — the index is a cache that rebuilds automatically, and you can delete it anytime. Set backend: in config.yaml to pin a tier explicitly.

One caveat on the postgres tier, stated here because it is this table's headline row: core does not write embeddings to a Postgres primary store (ADR-0005 amendment). Keyword/BM25 recall runs in SQL, but engram_embeddings stays empty unless your deployment populates it, so semantic and hybrid recall fall back to loading engrams and scoring in memory — correct results, at the O(N) cost this tier otherwise avoids. The adapter says so once at schema init; vectorIndex: 'exact' acknowledges and silences it.

sqlite (engrams.db, via better-sqlite3) is the legacy index and is no longer selected automatically.

Requirements

  • Node.js 22+ (22.21+ or 24+ behind an HTTPS proxy, with NODE_USE_ENV_PROXY=1)

  • 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.

Development

git clone https://github.com/plur-ai/plur.git
cd plur
pnpm install && pnpm build && pnpm test

~3500 tests across ~200 files. pnpm test:watch for development.

Contributing

  • Bug reports — issue with reproduction steps

  • Feature requests — issue describing the use case

  • Code — fork, branch, PR. Tests required.

  • Integrations — build PLUR support for other tools

Before submitting: pnpm test passes, pnpm build succeeds, no new external deps in core without discussion.

Conventions: TypeScript, Zod validation, Vitest, no external APIs in core, YAML storage, zero-cost search by default.

License

Apache-2.0

Available Tools

39 tools
plur_captureA

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

Inputs: summary (required), tags, agent, channel, +1 more.

plur_doctorA

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

Inputs: retry, rerank_eval.

plur_episode_to_engramA

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

Inputs: episode_id (required), tags, scope, domain.

plur_extract_metaA

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

Inputs: llm_api_key (required), llm_base_url (required), scope, domain, +3 more.

plur_feedbackB
Idempotent

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

Inputs: id, signal, signals.

plur_forgetA
DestructiveIdempotent

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

Inputs: id, search.

plur_historyA
Read-onlyIdempotent

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

Inputs: limit, engram_id.

plur_ingestB

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

Inputs: content (required), scope, domain, source, +1 more.

plur_injectA
Read-onlyIdempotent

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

Inputs: task (required), scope, budget.

plur_inject_hybridA
Read-onlyIdempotent

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

Inputs: task (required), scope, budget.

plur_learnA

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

Inputs: statement (required), tags, type, scope, +9 more.

plur_learn_batchA

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

Inputs: engrams (required), max_llm_calls.

plur_meta_engramsA
Read-onlyIdempotent

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

Inputs: limit, domain, min_confidence, hierarchy_level.

plur_packs_discoverB
Read-onlyIdempotent

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

Inputs: tags, query, category.

plur_packs_exportA

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

Inputs: name (required), creator, output_dir, description, +4 more.

plur_packs_installA
Idempotent

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

Inputs: source (required).

plur_packs_listA
Read-onlyIdempotent

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

Inputs: no named parameters.

plur_packs_previewA
Read-onlyIdempotent

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

Inputs: source (required).

plur_packs_uninstallA
Destructive

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

Inputs: name (required).

plur_pinA
Idempotent

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

Inputs: id, list, pinned.

plur_profileA
Read-onlyIdempotent

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

Inputs: scope, llm_model, llm_api_key, llm_base_url, +1 more.

plur_promoteB
Idempotent

Activate candidate engrams so they appear in injection results

Inputs: id, ids.

plur_recallA
Read-onlyIdempotent

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

Inputs: query (required), limit, scope, budget, +2 more.

plur_recall_hybridA
Read-onlyIdempotent

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

Inputs: query (required), limit, scope, budget, +3 more.

plur_report_failureA

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

Inputs: engram_id (required), failure_context (required), llm_model, llm_api_key, +1 more.

plur_scopes_discoverA
Idempotent

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

Inputs: url, register.

plur_session_endA

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

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

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

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

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

  5. Terminology defined or clarified → type: terminological

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

Inputs: summary (required), engram_suggestions (required), session_id.

plur_session_startB
Read-only

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

Inputs: task (required), tags, default_scope.

plur_statusA
Read-onlyIdempotent

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

Inputs: domain, created_after.

plur_stores_addA
Idempotent

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

Inputs: scope (required), url, path, token, +2 more.

plur_stores_listA
Read-onlyIdempotent

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

Inputs: no named parameters.

plur_suggest_scopeA
Read-onlyIdempotent

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

Inputs: statement (required), tags, domain.

plur_syncA
Idempotent

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

Inputs: full, remote.

plur_sync_statusA
Read-onlyIdempotent

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

Inputs: no named parameters.

plur_tensionsA
Idempotent

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

Inputs: id, scan, scope, action, +11 more.

plur_tensions_purgeA
DestructiveIdempotent

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

Inputs: no named parameters.

plur_timelineA
Read-onlyIdempotent

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

Inputs: agent, since, until, search, +1 more.

plur_validate_metaA

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

Inputs: llm_api_key (required), test_domain (required), llm_base_url (required), meta_engram_id (required), +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 39 tools

    Disambiguation2/5

    Multiple overlapping clusters create real selection ambiguity: six retrieval tools (plur_recall, plur_recall_hybrid, plur_similarity_search, plur_inject, plur_inject_hybrid, plur_timeline) and five creation paths (plur_learn, plur_learn_batch, plur_ingest, plur_capture, plur_episode_to_engram) have fuzzy boundaries. An agent will struggle to choose between plur_recall_hybrid vs plur_similarity_search, or plur_pin vs plur_promote, since both pairs control injection visibility.

    Naming Consistency3/5

    The plur_ prefix is applied uniformly and resource families like packs_* and stores_* follow tidy noun-verb patterns, but the set mixes verb-led names (plur_learn, plur_recall, plur_forget) with bare nouns (plur_timeline, plur_status, plur_history, plur_profile, plur_tensions) and odd entries like plur_doctor and plur_similarity_search. Readable, but not a single predictable convention.

    Tool Count2/5

    At 39 tools, this is well into the overgrown range. While the domain is genuinely broad, several tools are near-duplicates (recall/recall_hybrid, inject/inject_hybrid, learn/learn_batch), and subdomains like tensions and meta-engrams add complexity that could be consolidated. The cognitive load on an agent selecting from 39 options is high.

    Completeness4/5

    The surface covers the full engram lifecycle — create (learn, learn_batch, ingest, capture), query (recall, timeline, history), update (feedback, pin, promote), and retire (forget) — plus packs, scopes, sync, meta-engrams, and diagnostics. Minor gaps: there is no direct get-engram-by-ID tool, and content edits happen implicitly through the learn dedup pipeline rather than an explicit update tool.

    Maintenance

    ActivityMaintained
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers