You correct your agent on Monday. On Tuesday, it makes the same mistake. PLUR fixes this. Corrections, preferences, and conventions persist across sessions. Your data stays on your disk as plain YAML. Search runs locally with zero API calls.

In our tool-routing and local-knowledge benchmark, Haiku with PLUR memory outperformed Opus without it — 2.6x better on tool routing, at 10x less cost. The bottleneck isn't model intelligence. It's context.

Why @plur-ai/core

This is the engine that powers everything. Use it directly when you're building your own agent framework or want programmatic control over memory. If you just want to add memory to Claude Code or Cursor, use @plur-ai/mcp instead — it wraps this package as MCP tools.

Install

npm install @plur-ai/core

Quick start

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

const plur = new Plur()

// Your agent gets corrected — save it. 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 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'
})

// Next session: recall what was learned (hybrid search, zero cost)
const results = await plur.recallHybrid('vitest assertion matching')

// Or inject the best engrams into a system prompt, within a token budget
const { directives, consider, tokens_used } = await plur.inject('Write tests for the user service', {
  scope: 'project:my-app',
  budget: 2000
})

// Rate what was useful — the system improves over time
await plur.feedback(results[0].id, 'positive')

// Sync across machines via git — use a PRIVATE remote: the push contains every
// engram, including visibility:private ones. scope:local engrams are the exception —
// they are machine-specific and stripped from every commit, so they never sync.
await plur.sync('git@github.com:you/plur-memory.git')

How it works

Knowledge is stored as engrams — small assertions that strengthen with use and decay when irrelevant, modeled on how human memory works (ACT-R activation). The system gets better over time, not just bigger.

You correct your agent  →  engram created       →  YAML on your disk
Next session starts     →  relevant ones injected →  agent remembers
You rate the result     →  engram strengthens    →  quality improves

Search is fully local: BM25 over enriched text + BGE-small-en-v1.5 embeddings + Reciprocal Rank Fusion. Zero API calls, zero per-query cost. Benchmark methodology →

Search modes

Five modes, from fastest to most accurate:

Method	Speed	API calls	Best for
`recall(query)`	Instant	None	Quick keyword lookup
`recallSemantic(query)`	~200ms	None	Meaning-based search (local embeddings)
`recallHybrid(query)`	~200ms	None	Best default — BM25 + embeddings via RRF
`recallAsync(query, { llm })`	~1s	1 LLM call	LLM-assisted semantic filtering
`recallExpanded(query, { llm })`	~3s	3-5 LLM calls	Query expansion for exhaustive retrieval

Full API

Method	What it does
`learn(statement, context?)`	Store an engram (correction, preference, convention, decision)
`recall(query, options?)`	BM25 keyword search — instant, zero cost
`recallHybrid(query, options?)`	BM25 + embeddings merged via RRF — best default
`recallSemantic(query, options?)`	Embedding-only search — meaning over keywords
`recallAsync(query, { llm })`	LLM-assisted semantic filtering
`recallExpanded(query, { llm })`	Query expansion + hybrid + RRF merge
`inject(task, options?)`	Select engrams for a task within a token budget
`feedback(id, signal)`	Rate an engram — trains injection relevance over time
`forget(id, reason?)`	Retire an engram (history preserved)
`sync(remote?)`	Git-based sync across machines
`syncStatus()`	Check sync state without making changes
`capture(summary, context?)`	Record a session event to the episodic timeline
`timeline(query?)`	Query past episodes by time, agent, or search
`ingest(content, options?)`	Extract engram candidates from text via pattern matching
`installPack(source, opts?)`	Install a shareable engram pack — scans for secrets (always blocked) and prompt-injection text (blocked unless `allowInjection`), strips `pinned`/locked fields
`exportPack(engrams, dir, manifest)`	Export engrams as a shareable pack — strips private engrams, feedback signals, and `pinned`/locked fields
`listPacks()`	List installed packs
`status()`	System health — counts, storage root, config

Storage

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

~/.plur/
├── engrams.yaml     # learned knowledge
├── episodes.yaml    # session timeline
├── candidates.yaml  # pending engrams
├── config.yaml      # settings
└── packs/           # installed engram packs

Override the location with PLUR_PATH env var or new Plur({ path: '...' }).

config.yaml can hold store tokens, so only your account may read it: PLUR sets it to 0600 on macOS and Linux, and to an access list naming only your account on Windows, after every write. On Windows, if that access list cannot be set and checked, PLUR refuses the write and changes nothing. One case: a drive that cannot keep access lists at all (FAT or exFAT, some network shares). There, set PLUR_ALLOW_UNPROTECTED_CONFIG=1 to write the file without protection. Each such write prints a line to stderr saying so.

Benchmark

Retrieval (LongMemEval R@5): 76.7% out-of-the-box · 97.0% with openai-3-large embeddings

Agent task impact: Haiku + PLUR outperforms Opus without memory at ~10× less cost. House rules: 12–0 across Haiku, Sonnet, Opus. A/B win rate: 89%.

Full methodology →